Skip to main content
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: 
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
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

fresh file.txt

​
Version Information

fresh --version

​
Getting Help

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

Build docs developers (and LLMs) love

Get started for freeTalk to us