> ## 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.

# Quick Start Guide

> Learn the basics of Fresh in 5 minutes — from installation to your first file edit

## Welcome to Fresh!

This quick start guide will have you editing files in Fresh within minutes. Fresh is designed to be immediately familiar if you've used any modern text editor.

<Note>
  **New to terminal editors?** Don't worry! Fresh works just like VS Code or Sublime Text. If you can use `Ctrl+C` to copy, you already know half of Fresh.
</Note>

## Installation

First, install Fresh using your preferred method:

<Tabs>
  <Tab title="Quick Install (Auto-detect)">
    ```bash theme={null}
    curl https://raw.githubusercontent.com/sinelaw/fresh/refs/heads/master/scripts/install.sh | sh
    ```
  </Tab>

  <Tab title="macOS (Homebrew)">
    ```bash theme={null}
    brew tap sinelaw/fresh
    brew install fresh-editor
    ```
  </Tab>

  <Tab title="Windows (winget)">
    ```bash theme={null}
    winget install fresh-editor
    ```
  </Tab>

  <Tab title="Linux (Arch)">
    ```bash theme={null}
    yay -S fresh-editor-bin
    ```
  </Tab>

  <Tab title="npm">
    ```bash theme={null}
    npm install -g @fresh-editor/fresh-editor
    ```
  </Tab>

  <Tab title="Cargo">
    ```bash theme={null}
    cargo install fresh-editor
    ```
  </Tab>
</Tabs>

See the [Installation](/installation) page for all available methods.

## Your First File

Let's open Fresh and create your first file!

<Steps>
  <Step title="Launch Fresh">
    Open your terminal and run:

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

    You'll see the Fresh editor with a clean, empty buffer. Welcome!
  </Step>

  <Step title="Type some text">
    Just start typing! Fresh has no modes — everything you type appears on screen.

    Try typing:

    ```
    Hello, Fresh!
    This is my first file in a terminal editor.
    It's easier than I thought!
    ```
  </Step>

  <Step title="Save your file">
    Press `Ctrl+S` to save. Fresh will prompt you for a filename.

    Type:

    ```
    hello.txt
    ```

    Press `Enter` to confirm. Your file is saved!
  </Step>

  <Step title="Exit Fresh">
    Press `Ctrl+Q` to quit Fresh.

    <Tip>Fresh will warn you if you have unsaved changes — you'll never accidentally lose work!</Tip>
  </Step>
</Steps>

## Opening Existing Files

You can open files in several ways:

<CodeGroup>
  ```bash Open a Single File theme={null}
  fresh README.md
  ```

  ```bash Open at a Specific Line theme={null}
  fresh src/main.rs:42
  ```

  ```bash Open at Line and Column theme={null}
  fresh src/main.rs:42:10
  ```

  ```bash Open Multiple Files theme={null}
  fresh Cargo.toml src/lib.rs README.md
  ```

  ```bash Open a Remote File (SSH) theme={null}
  fresh user@host:/path/to/file.txt
  ```

  ```bash Open Current Directory theme={null}
  fresh .
  ```
</CodeGroup>

<Tip>
  The `file:line:col` syntax is perfect for jumping to compiler errors or search results!
</Tip>

## Essential Keyboard Shortcuts

Fresh uses standard keyboard shortcuts you already know:

### File Operations

| Shortcut       | Action               |
| -------------- | -------------------- |
| `Ctrl+N`       | New file             |
| `Ctrl+O`       | Open file            |
| `Ctrl+S`       | Save file            |
| `Ctrl+Shift+S` | Save as              |
| `Ctrl+W`       | Close current buffer |
| `Ctrl+Q`       | Quit Fresh           |

### Editing

| Shortcut    | Action           |
| ----------- | ---------------- |
| `Ctrl+C`    | Copy             |
| `Ctrl+X`    | Cut              |
| `Ctrl+V`    | Paste            |
| `Ctrl+Z`    | Undo             |
| `Ctrl+Y`    | Redo             |
| `Ctrl+/`    | Toggle comment   |
| `Tab`       | Indent selection |
| `Shift+Tab` | Dedent selection |

### Selection

| Shortcut      | Action                                 |
| ------------- | -------------------------------------- |
| `Ctrl+A`      | Select all                             |
| `Ctrl+W`      | Select word under cursor               |
| `Ctrl+L`      | Select current line                    |
| `Ctrl+D`      | Select next occurrence (multi-cursor!) |
| `Shift+Arrow` | Extend selection                       |

### Search & Navigation

| Shortcut | Action                                |
| -------- | ------------------------------------- |
| `Ctrl+F` | Find in current file                  |
| `Ctrl+R` | Replace in current file               |
| `Ctrl+G` | Go to line number                     |
| `Ctrl+P` | **Command Palette** (most important!) |

<Warning>
  **Platform Differences**: Some keybindings may not work on all systems due to terminal limitations. Check the [Keybindings Reference](/reference/keybindings) or use the command palette for alternatives.
</Warning>

## The Command Palette

The **Command Palette** is your gateway to everything in Fresh. Press `Ctrl+P` to open it:

<Steps>
  <Step title="Open the Command Palette">
    Press `Ctrl+P`. You'll see a search bar at the top of the screen.
  </Step>

  <Step title="Try different modes">
    The command palette has multiple modes, activated by prefix characters:

    * **No prefix**: Fuzzy file finder — search for files in your project
    * **`>`**: Command mode — search and run editor commands
    * **`#`**: Buffer switcher — switch between open files
    * **`:`**: Go to line — jump to a specific line number

    <Tip>The hints line at the bottom shows you which prefixes are available!</Tip>
  </Step>

  <Step title="Find a file">
    With the command palette open, start typing a filename:

    ```
    main.rs
    ```

    Fresh will fuzzy-match files in your project. Press `Enter` to open the top result.
  </Step>

  <Step title="Run a command">
    Press `Ctrl+P` again, then type `>` to enter command mode:

    ```
    >theme
    ```

    You'll see commands related to themes. Try "Select Theme" to browse available color schemes!
  </Step>
</Steps>

<Tip>
  **Pro tip**: Space-separated terms match independently. Try searching for `feat group` — it will match `features/groups/view.tsx`!
</Tip>

## Basic Editing Features

Let's explore some of Fresh's powerful editing features:

### Multi-Cursor Editing

Edit multiple locations at once:

<Steps>
  <Step title="Create sample text">
    Type or paste this text:

    ```
    const name = "Alice";
    const name = "Bob";
    const name = "Charlie";
    ```
  </Step>

  <Step title="Select the first 'name'">
    Place your cursor on the first `name` and press `Ctrl+W` to select it.
  </Step>

  <Step title="Add more cursors">
    Press `Ctrl+D` twice to add cursors at the next two occurrences of `name`.

    You should see three cursors now!
  </Step>

  <Step title="Edit all at once">
    Type `username` — all three instances of `name` change to `username` simultaneously!

    Press `Esc` to return to a single cursor.
  </Step>
</Steps>

### Block Selection

Select rectangular regions:

<Steps>
  <Step title="Create a table">
    ```
    Name      Age    City
    Alice     28     NYC
    Bob       34     LA
    Charlie   42     SF
    ```
  </Step>

  <Step title="Select a column">
    Position your cursor at the 'A' in "Age".

    Hold `Alt+Shift` and press `↓` three times.

    You've selected the entire "Age" column!
  </Step>

  <Step title="Edit the selection">
    Type "Years" — the entire column header changes!
  </Step>
</Steps>

### File Explorer

Browse your project files:

<Steps>
  <Step title="Open the file explorer">
    Press `Ctrl+B` to toggle the sidebar file explorer.
  </Step>

  <Step title="Navigate files">
    Use arrow keys to move up and down the file tree.

    Press `Enter` to open a file.
  </Step>

  <Step title="Focus the editor">
    Press `Ctrl+E` to switch focus between the file explorer and the editor.
  </Step>
</Steps>

<Tip>
  The file explorer respects your `.gitignore` file automatically!
</Tip>

### Split Views

View multiple files side by side:

<Steps>
  <Step title="Open a file">
    Open any file in Fresh.
  </Step>

  <Step title="Split the view">
    Press `Ctrl+P`, type `>split`, and select "Split Vertical" or "Split Horizontal".
  </Step>

  <Step title="Navigate between splits">
    Use `Ctrl+Arrow` keys to move between split panes.
  </Step>

  <Step title="Close a split">
    Press `Ctrl+W` to close the current pane.
  </Step>
</Steps>

## Working with Code

### Syntax Highlighting

Fresh automatically detects file types and applies syntax highlighting. No configuration needed!

Try opening files with these extensions:

* `.rs` (Rust)
* `.js`, `.ts`, `.jsx`, `.tsx` (JavaScript/TypeScript)
* `.py` (Python)
* `.go` (Go)
* `.c`, `.cpp`, `.h` (C/C++)
* And many more!

### LSP (Language Server Protocol)

Fresh supports LSP for advanced IDE features:

<Steps>
  <Step title="Install a language server">
    For Rust, install rust-analyzer:

    ```bash theme={null}
    rustup component add rust-analyzer
    ```

    For TypeScript/JavaScript:

    ```bash theme={null}
    npm install -g typescript typescript-language-server
    ```
  </Step>

  <Step title="Open a code file">
    ```bash theme={null}
    fresh src/main.rs
    ```

    Fresh automatically detects and starts the language server.
  </Step>

  <Step title="Use LSP features">
    * **Go to definition**: `Ctrl+Click` on a symbol (or use the command palette)
    * **Hover documentation**: Mouse over a symbol
    * **Autocomplete**: Start typing — suggestions appear automatically
    * **Diagnostics**: Errors and warnings appear inline and in the diagnostics panel
    * **Code actions**: Press `Ctrl+P` and search for "code action"
  </Step>
</Steps>

See [LSP Integration](/features/lsp) for complete configuration details.

### Search and Replace

Find and replace text with ease:

<Steps>
  <Step title="Open search">
    Press `Ctrl+F` to open the search bar.
  </Step>

  <Step title="Search for text">
    Type your search query. Matches are highlighted immediately.

    Press `F3` to jump to the next match, `Shift+F3` for previous.
  </Step>

  <Step title="Replace text">
    Press `Ctrl+R` to open find and replace.

    Enter your replacement text and:

    * Press `Enter` to replace the current match
    * Use `Ctrl+Alt+R` for interactive replace (y/n/!/q for each match)
  </Step>
</Steps>

## Customization

### Change the Theme

<Steps>
  <Step title="Open theme selector">
    Press `Ctrl+P`, type `>theme`, and select "Select Theme".
  </Step>

  <Step title="Browse themes">
    Use arrow keys to preview different themes instantly.
  </Step>

  <Step title="Apply a theme">
    Press `Enter` to apply your chosen theme.

    The theme is automatically saved to your config!
  </Step>
</Steps>

Popular themes include:

* Dracula
* Monokai
* Solarized Dark/Light
* One Dark
* Gruvbox

### Edit Settings

Fresh stores settings in a JSON file:

<Steps>
  <Step title="Open settings">
    Press `Ctrl+P`, type `>settings`, and select "Open Settings File".
  </Step>

  <Step title="Edit settings">
    The `config.json` file opens. Try changing some settings:

    ```json theme={null}
    {
      "theme": "dracula",
      "tab_width": 4,
      "insert_spaces": true,
      "line_numbers": true,
      "auto_save_enabled": true,
      "trim_trailing_whitespace_on_save": true
    }
    ```
  </Step>

  <Step title="Save settings">
    Press `Ctrl+S`. Changes apply immediately!
  </Step>
</Steps>

See [Configuration](/configuration/overview) for all available settings.

## Advanced Features

Once you're comfortable with the basics, explore these powerful features:

<CardGroup cols={2}>
  <Card title="Integrated Terminal" icon="terminal" href="/features/terminal">
    Run shell commands without leaving Fresh
  </Card>

  <Card title="Keyboard Macros" icon="keyboard" href="/features/editing#macros">
    Record and replay sequences of keystrokes
  </Card>

  <Card title="Git Integration" icon="code-branch" href="/features/file-explorer">
    Git grep, file finder, and status integration
  </Card>

  <Card title="Remote Editing" icon="cloud" href="/features/ssh">
    Edit files on remote servers via SSH
  </Card>

  <Card title="Bookmarks" icon="bookmark" href="/features/editing#bookmarks">
    Jump quickly between code locations
  </Card>

  <Card title="Plugins" icon="puzzle-piece" href="/plugins/overview">
    Extend Fresh with TypeScript plugins
  </Card>
</CardGroup>

## Getting Help

<AccordionGroup>
  <Accordion title="Where can I find all keyboard shortcuts?">
    Press `Ctrl+P`, type `>keybindings`, and select "Open Keybinding Editor" to browse all available shortcuts interactively.

    Or see the [Keybindings Reference](/reference/keybindings).
  </Accordion>

  <Accordion title="Why isn't a keyboard shortcut working?">
    Some keybindings may not work on all systems due to:

    * Terminal emulator limitations
    * OS-level keyboard shortcuts that intercept keys
    * Keyboard layout differences

    Use the Command Palette (`Ctrl+P`) to access any command. See the [Keyboard Configuration](/configuration/keyboard) guide for customizing keybindings.
  </Accordion>

  <Accordion title="How do I configure Fresh?">
    Press `Ctrl+P`, type `>settings`, and select "Open Settings File" to edit `config.json` directly.

    See [Configuration](/configuration/overview) for all available options.
  </Accordion>

  <Accordion title="Where are my files saved?">
    Fresh stores configuration and data in:

    * **Config**: `~/.config/fresh/config.json` (Linux/macOS)
    * **Windows**: `%APPDATA%\fresh\config.json`
    * **Crash recovery**: `~/.local/share/fresh/recovery/`
  </Accordion>

  <Accordion title="Can I use Fresh for large files?">
    Yes! Fresh is designed to handle multi-gigabyte files with minimal memory overhead. See the [blog post on large file handling](https://noamlewis.com/blog/2025/12/09/how-fresh-loads-huge-files-fast) for details.
  </Accordion>
</AccordionGroup>

## Next Steps

Now that you know the basics, dive deeper:

<CardGroup cols={2}>
  <Card title="Editing Features" icon="pen-to-square" href="/features/editing">
    Master multi-cursor editing, block selection, and more
  </Card>

  <Card title="Command Palette" icon="terminal" href="/features/command-palette">
    Learn all command palette modes and shortcuts
  </Card>

  <Card title="LSP Integration" icon="code" href="/features/lsp">
    Configure language servers for your languages
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration/overview">
    Customize Fresh to match your workflow
  </Card>
</CardGroup>

<Tip>
  Join the [Fresh Discord](https://discord.gg/gqGh3K4uW3) to ask questions, share tips, and connect with the community!
</Tip>