# How to Configure Custom Hotkeys and Keybindings in Superfile: The Complete TOML Guide

> Learn how to configure custom hotkeys and keybindings in Superfile with this complete TOML guide. Easily personalize your workflow and boost productivity.

- Repository: [Yorukot/superfile](https://github.com/yorukot/superfile)
- Tags: how-to-guide
- Published: 2026-07-26

---

**Superfile stores all keyboard shortcuts in a TOML file called [`hotkeys.toml`](https://github.com/yorukot/superfile/blob/main/hotkeys.toml) that you can edit directly or override via the `--hotkey-file` CLI flag, with the `LoadHotkeysFile` function in [`src/internal/common/load_config.go`](https://github.com/yorukot/superfile/blob/main/src/internal/common/load_config.go) handling validation and automatic repair.**

Superfile is a modern terminal file manager written in Go. Learning how to configure custom hotkeys and keybindings in Superfile allows you to replace default vim-style navigation with your own preferred shortcuts. The configuration system reads from a single TOML file that the application validates at startup using reflection-based checks in the source code.

## Locating the Default hotkeys.toml File

On first run, Superfile copies the default template from [`src/superfile_config/hotkeys.toml`](https://github.com/yorukot/superfile/blob/main/src/superfile_config/hotkeys.toml) into your system's user configuration directory. The exact location depends on your operating system:

- **Linux**: `~/.config/superfile/hotkeys.toml`
- **macOS**: `~/Library/Application Support/superfile/hotkeys.toml`
- **Windows**: `%LOCALAPPDATA%\superfile\hotkeys.toml`

The global variable `HotkeysFile` in [`src/config/fixed_variable.go`](https://github.com/yorukot/superfile/blob/main/src/config/fixed_variable.go) stores the resolved path to this file at runtime. If you need to use an alternative location, the CLI flag `--hotkey-file` (short form `-hf`) defined in [`src/cmd/main.go`](https://github.com/yorukot/superfile/blob/main/src/cmd/main.go) overrides this default.

## Structure of the Hotkey Configuration

The [`hotkeys.toml`](https://github.com/yorukot/superfile/blob/main/hotkeys.toml) file organizes shortcuts into three distinct categories, each with different conflict-resolution rules.

### Global Hotkeys

Global hotkeys form the backbone of the UI and **cannot conflict** with other global bindings. These control panel navigation, file operations, and application-wide actions. Each entry is defined as a slice of strings where the first element is the primary key and the second is an optional alternative.

```toml

# ---------------------------------------------

# Global hotkeys (cannot conflict with other hotkeys)

# ---------------------------------------------

confirm = ['enter', 'right', 'l']
quit    = ['q', 'esc']
open_file = ['enter', 'l']

```

Attempting to assign the same key to two different global actions causes a runtime panic during validation.

### Typing Hotkeys

Typing hotkeys are active only when the input bar is focused. These bindings **can override** any other mapping, including global hotkeys, ensuring you can always cancel or confirm text input.

```toml

# ---------------------------------------------

# Typing hotkeys (can override all hotkeys)

# ---------------------------------------------

confirm_typing = ['enter', '']
cancel_typing  = ['ctrl+c', 'esc']

```

Note that an empty string `''` as the second element explicitly indicates "no alternative binding."

### Mode-Specific Hotkeys

Mode-specific hotkeys apply only within particular UI states (normal, selection, renaming, etc.). These **may conflict** with hotkeys from other modes but never with global keys.

```toml

# ---------------------------------------------

# Mode-Specific Hotkeys (may conflict with other modes)

# ---------------------------------------------

parent_directory = ['h', 'left', 'backspace']
list_down        = ['j', 'down']
list_up          = ['k', 'up']
file_panel_select_mode_items_select_down = ['shift+down', 'J']

```

## Customizing Your Keybindings

To configure custom hotkeys and keybindings in Superfile, edit the [`hotkeys.toml`](https://github.com/yorukot/superfile/blob/main/hotkeys.toml) file directly with any text editor. Changes take effect the next time you launch the application.

1. Open your [`hotkeys.toml`](https://github.com/yorukot/superfile/blob/main/hotkeys.toml) file in the appropriate directory for your OS.
2. Locate the action you want to remap within the relevant section (Global, Typing, or Mode-Specific).
3. Modify the string values inside the brackets. For example, to remap quit to `Ctrl+Q`:
   ```toml
   quit = ['ctrl+q', 'esc']
   ```

4. To add a third alternative, extend the slice:
   ```toml
   quit = ['ctrl+q', 'q', 'esc']
   ```

5. Save the file and restart Superfile.

### Example: Vim-Style Navigation

Replace arrow keys with vim-style letters in normal mode by editing the Mode-Specific section:

```toml
parent_directory = ['h', 'left']
list_down        = ['j', 'down']
list_up          = ['k', 'up']
next_file_panel  = ['l', 'right']

```

### Example: Custom Help Menu Shortcut

Add a second shortcut for opening the help menu:

```toml
open_help_menu = ['?', 'h']

```

## Using Custom Hotkey File Paths

For per-project configurations or testing different layouts, use the `--hotkey-file` flag to point Superfile to an alternative TOML file without modifying your main configuration.

```bash
spf --hotkey-file "$HOME/.config/superfile/hotkeys_work.toml"

```

The `InitConfigFile()` function ensures that even when using a custom path, the application can still reference default values on first run. The global variable `HotkeysFile` in [`src/config/fixed_variable.go`](https://github.com/yorukot/superfile/blob/main/src/config/fixed_variable.go) is updated to reflect the custom path when the `-hf` flag is present.

## Validation and Automatic Repair

Superfile validates every entry in [`hotkeys.toml`](https://github.com/yorukot/superfile/blob/main/hotkeys.toml) at startup through the `LoadHotkeysFile(ignoreMissingFields bool)` function in [`src/internal/common/load_config.go`](https://github.com/yorukot/superfile/blob/main/src/internal/common/load_config.go). The loader uses reflection to iterate over each struct field, confirming that every hotkey is a non-empty slice of strings.

If your configuration file is missing required entries due to version upgrades, run Superfile with the `--fix-hotkeys` flag:

```bash
spf --fix-hotkeys

```

When `FixHotkeys` is true, the loader automatically injects missing default entries back into your [`hotkeys.toml`](https://github.com/yorukot/superfile/blob/main/hotkeys.toml) file before completing initialization. You can verify your current bindings by running `spf --debug-info` to print the loaded hotkey map.

## Summary

- Superfile configures custom hotkeys and keybindings through a single [`hotkeys.toml`](https://github.com/yorukot/superfile/blob/main/hotkeys.toml) file located in your system’s user config directory.
- The file contains three sections: **Global** (no conflicts allowed), **Typing** (overrides all), and **Mode-Specific** (intra-mode conflicts only).
- Use the `--hotkey-file` (`-hf`) CLI flag to specify alternative configuration paths for different projects.
- The `LoadHotkeysFile` function in [`src/internal/common/load_config.go`](https://github.com/yorukot/superfile/blob/main/src/internal/common/load_config.go) validates entries using reflection and can auto-repair missing fields when you pass `--fix-hotkeys`.
- Each hotkey is defined as a TOML array of strings, supporting up to two alternative bindings per action.

## Frequently Asked Questions

### What happens if I assign the same key to two global actions?

Superfile enforces uniqueness for global hotkeys during the validation phase in `LoadHotkeysFile`. Assigning the same key to multiple global actions triggers a runtime panic. The application will refuse to start until you resolve the conflict in [`hotkeys.toml`](https://github.com/yorukot/superfile/blob/main/hotkeys.toml).

### Can I use multiple hotkey profiles for different projects?

Yes. Copy your default [`hotkeys.toml`](https://github.com/yorukot/superfile/blob/main/hotkeys.toml) to a project-specific location, edit the bindings, and launch Superfile with the `--hotkey-file` flag: `spf --hotkey-file ./project/hotkeys.toml`. This keeps your global defaults intact while allowing context-specific shortcuts.

### How do I reset broken or missing hotkeys to the defaults?

Run `spf --fix-hotkeys`. This flag tells the configuration loader to compare your current [`hotkeys.toml`](https://github.com/yorukot/superfile/blob/main/hotkeys.toml) against the default template in [`src/superfile_config/hotkeys.toml`](https://github.com/yorukot/superfile/blob/main/src/superfile_config/hotkeys.toml) and inject any missing entries automatically.

### Where does Superfile store the hotkeys.toml file on Windows?

On Windows, the default path is `%LOCALAPPDATA%\superfile\hotkeys.toml`, which typically resolves to `C:\Users\<Username>\AppData\Local\superfile\hotkeys.toml`. You can override this location using the `--hotkey-file` flag or by setting the appropriate environment variable before launch.