> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/sinelaw/fresh/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
fresh [OPTIONS] [FILES]...
```

## Opening Files

<ParamField path="FILES" type="string[]">
  Files to open. Supports advanced file location syntax (see below).
</ParamField>

### File Location Syntax

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

<CodeGroup>
  ```bash Basic line number theme={null}
  fresh file.txt:10
  # Opens file.txt at line 10
  ```

  ```bash Line and column theme={null}
  fresh file.txt:10:5
  # Opens file.txt at line 10, column 5
  ```

  ```bash Line range theme={null}
  fresh file.txt:10-20
  # Opens file.txt with lines 10-20 selected
  ```

  ```bash Full range with columns theme={null}
  fresh file.txt:10:5-20:1
  # Selects from line 10 col 5 to line 20 col 1
  ```

  ```bash With popup message theme={null}
  fresh 'file.txt:10@"Check this line"'
  # Opens at line 10 with a markdown popup message
  ```

  ```bash Range with message theme={null}
  fresh 'file.txt:10-20@"Review this section"'
  # Selects lines 10-20 with a popup message
  ```
</CodeGroup>

<Note>
  Use single quotes to avoid shell expansion when using the `@"message"` syntax.
</Note>

## Global Options

<ParamField path="--cmd" type="string[]">
  Run a command instead of opening files. See [Commands](#commands) below.
</ParamField>

<ParamField path="-a, --attach" type="string" optional>
  Attach to a session. Use `-a` alone for current directory, or `-a NAME` for a named session.
</ParamField>

<ParamField path="--stdin" type="boolean">
  Read content from stdin (alternative to using `-` as filename).
</ParamField>

<ParamField path="--no-plugins" type="boolean">
  Disable plugin loading.
</ParamField>

<ParamField path="--config" type="path">
  Path to configuration file (overrides default config locations).
</ParamField>

<ParamField path="--log-file" type="path">
  Path to log file for editor diagnostics.
</ParamField>

<ParamField path="--event-log" type="path">
  Enable event logging to the specified file.
</ParamField>

<ParamField path="--no-restore" type="boolean">
  Don't restore previous workspace session.

  **Alias:** `--no-session`
</ParamField>

<ParamField path="--no-upgrade-check" type="boolean">
  Disable upgrade checking and anonymous telemetry.
</ParamField>

<ParamField path="--locale" type="string">
  Override the locale (e.g., `en`, `ja`, `zh-CN`).

  See [Internationalization](/reference/i18n) for supported locales.
</ParamField>

<ParamField path="--gui" type="boolean">
  Launch in GUI mode with native window and GPU rendering.

  <Note>Requires Fresh to be built with the `gui` feature enabled.</Note>
</ParamField>

## Commands

Commands are invoked using the `--cmd` flag:

```bash theme={null}
fresh --cmd <command> [args...]
```

### Configuration Commands

#### `config show`

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

```bash theme={null}
fresh --cmd config show
```

#### `config paths`

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

```bash theme={null}
fresh --cmd config paths
```

### Session Commands

Fresh supports persistent sessions that can be attached/detached.

#### `session list`

List all active sessions.

```bash theme={null}
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.

```bash theme={null}
fresh --cmd session attach
fresh --cmd session attach mysession
# Aliases: session a, s attach, s a
```

#### `session new NAME`

Start a new named session.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
fresh --cmd session open-file . main.rs
fresh --cmd session open-file proj src/app.rs
# Aliases: s open-file
```

<ParamField path="--wait" type="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.
</ParamField>

### Initialization Command

#### `init [TYPE]`

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

```bash theme={null}
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:

```bash theme={null}
# 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
```

<Accordion title="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
</Accordion>

### Using Fresh as Git Editor

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

```bash theme={null}
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

```bash theme={null}
# 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:

```bash theme={null}
fresh user@host:/path/to/file.txt
fresh user@host:~/remote.rs:10:5
```

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

## Examples

<CodeGroup>
  ```bash Open a file theme={null}
  fresh file.txt
  ```

  ```bash Open at specific line theme={null}
  fresh src/main.rs:42
  ```

  ```bash Open with selection and popup theme={null}
  fresh 'file.txt:10-20@"Check this code"'
  ```

  ```bash Attach to session theme={null}
  fresh -a
  fresh -a mysession
  ```

  ```bash Start named session theme={null}
  fresh --cmd session new proj
  ```

  ```bash Open file in existing session theme={null}
  fresh --cmd session open-file . main.rs
  ```

  ```bash List sessions theme={null}
  fresh --cmd session list
  ```

  ```bash Show configuration theme={null}
  fresh --cmd config show
  ```

  ```bash Disable plugins and telemetry theme={null}
  fresh --no-plugins --no-upgrade-check file.txt
  ```

  ```bash Use custom config theme={null}
  fresh --config ~/.config/fresh/work-config.json
  ```
</CodeGroup>

## Version Information

```bash theme={null}
fresh --version
```

## Getting Help

```bash theme={null}
fresh --help
```

For more information, visit [https://getfresh.dev/docs](https://getfresh.dev/docs)