CLI Commands

Complete command-line reference for Fresh text editor

Fresh is a terminal text editor with multi-cursor support. This page documents all CLI commands, flags, and file location syntax.

Basic Usage

fresh [OPTIONS] [FILES]...

Opening Files

FILES · string[]

Files to open. Supports advanced file location syntax (see below).

File Location Syntax

Fresh supports rich file location syntax for opening files at specific positions:

Basic line number

fresh file.txt:10
# Opens file.txt at line 10

Use single quotes to avoid shell expansion when using the @"message" syntax.

Global Options

--cmd · string[]

Run a command instead of opening files. See Commands below.

-a, --attach · string

Attach to a session. Use -a alone for current directory, or -a NAME for a named session.

--stdin · boolean

Read content from stdin (alternative to using - as filename).

--no-plugins · boolean

Disable plugin loading.

--config · path

Path to configuration file (overrides default config locations).

--log-file · path

Path to log file for editor diagnostics.

--event-log · path

Enable event logging to the specified file.

--no-restore · boolean

Don’t restore previous workspace session.

Alias: --no-session

--no-upgrade-check · boolean

Disable upgrade checking and anonymous telemetry.

--locale · string

Override the locale (e.g., en, ja, zh-CN).

See Internationalization for supported locales.

--gui · boolean

Launch in GUI mode with native window and GPU rendering.

Requires Fresh to be built with the gui feature enabled.

Commands

Commands are invoked using the --cmd flag:

fresh --cmd <command> [args...]

Configuration Commands

config show

Print the effective configuration (merged from all config layers).

fresh --cmd config show

config paths

Show directories used by Fresh (config, data, cache, etc.).

fresh --cmd config paths

Session Commands

Fresh supports persistent sessions that can be attached/detached.

session list

List all active sessions.

fresh --cmd session list
# Aliases: session ls, s list, s ls

session attach [NAME]

Attach to a session. Without NAME, attaches to the session for the current directory.

fresh --cmd session attach
fresh --cmd session attach mysession
# Aliases: session a, s attach, s a

session new NAME

Start a new named session.

fresh --cmd session new proj
# Aliases: session n, s new, s n

session kill [NAME]

Terminate a session. Without NAME, kills the current directory’s session. Use --all to kill all sessions.

fresh --cmd session kill
fresh --cmd session kill mysession
fresh --cmd session kill --all
# Aliases: session k, s kill, s k

session open-file NAME FILES [--wait]

Open files in a session without attaching. Use . for NAME to target the current directory’s session.

fresh --cmd session open-file . main.rs
fresh --cmd session open-file proj src/app.rs
# Aliases: s open-file

--wait · boolean

Block the CLI process until the user dismisses the popup (if @"message" was given) or closes the buffer.

This enables guided walkthroughs and sequential file review workflows.

Initialization Command

init [TYPE]

Initialize a new plugin, theme, or language configuration. Interactive prompt if TYPE is omitted.

fresh --cmd init
fresh --cmd init plugin
fresh --cmd init theme

Advanced Workflows

Guided Walkthrough with —wait

The --wait flag enables sequential file review workflows:

# Walk through multiple locations step-by-step
fresh --cmd session open-file . 'a.rs:1-10@"Step 1: Initialize"' --wait
fresh --cmd session open-file . 'b.rs:5-20@"Step 2: Process"' --wait
fresh --cmd session open-file . 'c.rs:30@"Step 3: Finalize"' --wait

How --wait works

When --wait is used:

1. Fresh opens the file at the specified location
2. If a @"message" is provided, displays it in a popup
3. The CLI process blocks until:
   • User presses Escape (if popup was shown)
   • User closes the buffer (if no popup)
4. Process exits, allowing the next command to run

This is useful for:

• Code review workflows
• Tutorial/walkthrough scripts
• Sequential debugging sessions

Using Fresh as Git Editor

Configure Fresh as your Git editor for commits, rebases, etc.:

git config core.editor 'fresh --cmd session open-file . --wait'

This opens files in the current directory’s session and waits for you to save and close.

Reading from Stdin

# Pipe content directly
cat file.txt | fresh --stdin

# Or use - as filename
echo "Hello" | fresh -

# View command output
git diff | fresh --stdin

Remote Editing (SSH)

Fresh supports editing files on remote hosts via SSH:

fresh user@host:/path/to/file.txt
fresh user@host:~/remote.rs:10:5

All files in a single Fresh invocation must be from the same remote host. You cannot mix local and remote files.

Examples

Open a file

fresh file.txt

Version Information

fresh --version

Getting Help

fresh --help

For more information, visit https://getfresh.dev/docs