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

# Keybindings Reference

> Default keyboard shortcuts and keybinding customization for Fresh

Fresh uses context-aware keybindings that adapt based on what part of the editor you're using.

## Viewing Keybindings

There are several ways to discover keybindings in Fresh:

### Command Palette

Press `Ctrl+P` (or `⌘+P` on macOS) to open the command palette. Type any command name to see its assigned keybinding.

### Keyboard Shortcuts View

Open **Help → Keyboard Shortcuts** from the menu to view the complete list of all keybindings organized by category.

### Keybinding Editor

Open **Edit → Keybinding Editor** to customize keybindings interactively.

## Keybinding Maps

Fresh supports multiple keybinding maps (styles) that you can switch between:

* **default** - Fresh's native keybindings (optimized for terminal use)
* **emacs** - Emacs-style keybindings
* **vscode** - VS Code-compatible shortcuts
* **vim** - Vim-style modal editing

Switch between maps using **View → Keybinding Style** or via configuration:

```json theme={null}
{
  "active_keybinding_map": "emacs"
}
```

## Key Contexts

Keybindings are context-sensitive. The same key can perform different actions depending on where you are:

* **Normal** - Default editing context
* **Prompt** - When entering text in prompts (file open, search, etc.)
* **Popup** - When viewing popups (completions, hover info, etc.)
* **FileExplorer** - When the file explorer has focus
* **Menu** - When navigating the menu bar

## Common Keybindings (Default Map)

<Note>
  This section shows common keybindings from the default map. For platform-specific variations and complete listings, use the in-app **Help → Keyboard Shortcuts** view.
</Note>

### File Operations

| Keybinding     | Action  | Description          |
| -------------- | ------- | -------------------- |
| `Ctrl+N`       | New     | Create new buffer    |
| `Ctrl+O`       | Open    | Open file            |
| `Ctrl+S`       | Save    | Save current buffer  |
| `Ctrl+Shift+S` | Save As | Save with new name   |
| `Ctrl+W`       | Close   | Close current buffer |
| `Ctrl+Q`       | Quit    | Quit editor          |

### Editing

| Keybinding                | Action         | Description              |
| ------------------------- | -------------- | ------------------------ |
| `Ctrl+Z`                  | Undo           | Undo last change         |
| `Ctrl+Y` / `Ctrl+Shift+Z` | Redo           | Redo last undone change  |
| `Ctrl+X`                  | Cut            | Cut selection            |
| `Ctrl+C`                  | Copy           | Copy selection           |
| `Ctrl+V`                  | Paste          | Paste from clipboard     |
| `Ctrl+A`                  | Select All     | Select entire buffer     |
| `Ctrl+D`                  | Add Cursor     | Add cursor at next match |
| `Ctrl+/`                  | Toggle Comment | Comment/uncomment lines  |

### Navigation

| Keybinding               | Action           | Description                     |
| ------------------------ | ---------------- | ------------------------------- |
| `Ctrl+P`                 | Command Palette  | Open command palette            |
| `Ctrl+Shift+O`           | Quick Open       | Quick file open                 |
| `Ctrl+G`                 | Go to Line       | Jump to specific line           |
| `Ctrl+]`                 | Go to Definition | Jump to symbol definition       |
| `Ctrl+[`                 | Go Back          | Navigate backward               |
| `Alt+Left` / `Alt+Right` | Navigate History | Move through navigation history |

### Search & Replace

| Keybinding       | Action             | Description                 |
| ---------------- | ------------------ | --------------------------- |
| `Ctrl+F`         | Find               | Open search                 |
| `Ctrl+H`         | Replace            | Open find & replace         |
| `F3` / `Ctrl+F3` | Find Next/Previous | Jump to next/previous match |
| `Ctrl+Shift+F`   | Find in Selection  | Search within selection     |

### Multi-Cursor

| Keybinding       | Action                   | Description                      |
| ---------------- | ------------------------ | -------------------------------- |
| `Ctrl+D`         | Add Cursor Next Match    | Add cursor at next occurrence    |
| `Ctrl+Shift+L`   | Add Cursor to Lines      | Add cursor to all selected lines |
| `Alt+Shift+Up`   | Add Cursor Above         | Add cursor on line above         |
| `Alt+Shift+Down` | Add Cursor Below         | Add cursor on line below         |
| `Esc`            | Remove Secondary Cursors | Keep only primary cursor         |

### Splits & Tabs

| Keybinding       | Action           | Description               |
| ---------------- | ---------------- | ------------------------- |
| `Ctrl+\`         | Split Horizontal | Split editor horizontally |
| `Ctrl+Shift+\`   | Split Vertical   | Split editor vertically   |
| `Ctrl+Tab`       | Next Buffer      | Switch to next tab        |
| `Ctrl+Shift+Tab` | Previous Buffer  | Switch to previous tab    |
| `Ctrl+1..9`      | Switch to Tab    | Switch to tab by number   |

### View

| Keybinding     | Action               | Description            |
| -------------- | -------------------- | ---------------------- |
| `Ctrl+B`       | Toggle File Explorer | Show/hide file sidebar |
| `Ctrl+Shift+P` | Command Palette      | Open command palette   |
| `F1`           | Show Help            | Open help menu         |

### LSP (Language Server)

| Keybinding   | Action             | Description                    |
| ------------ | ------------------ | ------------------------------ |
| `Ctrl+Space` | Trigger Completion | Show code completions          |
| `Alt+K`      | Hover Info         | Show symbol documentation      |
| `F2`         | Rename Symbol      | Rename symbol across workspace |
| `Shift+F12`  | Find References    | Find all references            |
| `Ctrl+.`     | Code Actions       | Show available code actions    |

### File Explorer (when focused)

| Keybinding | Action          | Description                |
| ---------- | --------------- | -------------------------- |
| `Up/Down`  | Navigate        | Move selection             |
| `Enter`    | Open            | Open file/expand directory |
| `Space`    | Expand/Collapse | Toggle directory           |
| `n`        | New File        | Create new file            |
| `N`        | New Directory   | Create new directory       |
| `d`        | Delete          | Delete selected item       |
| `r`        | Rename          | Rename selected item       |
| `h`        | Toggle Hidden   | Show/hide hidden files     |
| `Esc`      | Focus Editor    | Return focus to editor     |

## Customizing Keybindings

### Using the Keybinding Editor

The easiest way to customize keybindings:

1. Open **Edit → Keybinding Editor**
2. Search for the action you want to rebind
3. Click on the keybinding or "Add Binding"
4. Press the desired key combination
5. Save changes

### Manual Configuration

Edit `~/.config/fresh/config.json`:

```json theme={null}
{
  "keybindings": [
    {
      "key": "F5",
      "modifiers": [],
      "action": "format_buffer"
    },
    {
      "key": "s",
      "modifiers": ["ctrl", "shift"],
      "action": "save_as"
    },
    {
      "key": "tab",
      "modifiers": ["ctrl"],
      "action": "next_buffer",
      "when": "normal"
    }
  ]
}
```

### Keybinding Schema

<ParamField path="key" type="string" required>
  The key to bind. Examples: `"a"`, `"enter"`, `"f1"`, `"space"`, `"tab"`, `"escape"`
</ParamField>

<ParamField path="modifiers" type="string[]" required>
  Modifier keys. Can include: `"ctrl"`, `"shift"`, `"alt"`, `"super"` (or `"cmd"` on macOS)
</ParamField>

<ParamField path="action" type="string" required>
  The action to execute. See [available actions](#available-actions) below.
</ParamField>

<ParamField path="when" type="string" optional>
  Context condition. Values: `"normal"`, `"prompt"`, `"popup"`, `"file_explorer"`, `"menu"`

  If omitted, defaults to `"normal"`.
</ParamField>

<ParamField path="args" type="object" optional>
  Additional arguments for actions that require parameters.
</ParamField>

### Creating Custom Keybinding Maps

You can create your own keybinding map:

```json theme={null}
{
  "keybinding_maps": {
    "my-custom-map": [
      {
        "key": "s",
        "modifiers": ["ctrl"],
        "action": "save"
      },
      {
        "key": "o",
        "modifiers": ["ctrl"],
        "action": "open"
      }
    ]
  },
  "active_keybinding_map": "my-custom-map"
}
```

## Available Actions

To see all available actions, open the **Keybinding Editor** and browse the action dropdown, or use the **Command Palette** (`Ctrl+P`).

Some commonly used actions:

* `save`, `save_as`, `open`, `new`, `close`, `quit`
* `undo`, `redo`, `copy`, `cut`, `paste`
* `search`, `replace`, `find_next`, `find_previous`
* `goto_line`, `lsp_goto_definition`, `lsp_references`
* `add_cursor_above`, `add_cursor_below`, `add_cursor_next_match`
* `toggle_comment`, `format_buffer`, `delete_line`
* `split_horizontal`, `split_vertical`, `next_split`, `prev_split`
* `toggle_file_explorer`, `toggle_line_numbers`, `toggle_line_wrap`

## Debugging Keybindings

If a keybinding isn't working as expected:

### Debug Keyboard Events

Use **Help → Debug Keyboard Events** to see exactly what key codes your terminal sends to Fresh. This helps diagnose:

* Missing modifier keys
* Terminal or OS intercepting keys
* Incorrect escape sequences

Press any key to see its code, modifiers, and event type. Press `c` to clear history, `q` or `Esc` to close.

### Input Calibration

Some terminals send non-standard escape sequences. Use **View → Calibrate Input** to teach Fresh your terminal's specific key mappings.

## Platform Differences

### macOS

* `Cmd` (⌘) is used instead of `Ctrl` for many system-wide shortcuts
* The default macOS keymap automatically adjusts for platform conventions
* Native menu bar integration provides standard macOS shortcuts

### Windows

* `Alt` key behavior may differ in Windows Terminal vs other terminals
* Some `Ctrl+Shift` combinations may be intercepted by the OS

### Linux

* Terminal emulator differences are most prominent on Linux
* Use input calibration if your terminal sends unusual sequences
* GPM (console mouse) is supported on the Linux console

## See Also

* [Troubleshooting](/reference/troubleshooting) - Debug keyboard issues
* [CLI Commands](/reference/cli-commands) - Command-line options