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

Superfile stores all keyboard shortcuts in a TOML file called 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 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 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 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 overrides this default.

Structure of the Hotkey Configuration

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

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

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

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

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

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

# 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 file directly with any text editor. Changes take effect the next time you launch the application.

1. Open your 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:

   quit = ['ctrl+q', 'esc']

4. To add a third alternative, extend the slice:

   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:

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:

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.

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 is updated to reflect the custom path when the -hf flag is present.

Validation and Automatic Repair

Superfile validates every entry in hotkeys.toml at startup through the LoadHotkeysFile(ignoreMissingFields bool) function in 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:

spf --fix-hotkeys

When FixHotkeys is true, the loader automatically injects missing default entries back into your 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 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 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.

Can I use multiple hotkey profiles for different projects?

Yes. Copy your default 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 against the default template in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}