Custom keybindings in Wave allow you to personalize and streamline your workflow by creating shortcuts tailored to your preferences and needs. By customizing keybindings, you can execute commands, trigger actions, and navigate within the Wave terminal more efficiently.


All keyboard shortcuts in Wave can be customized by editing the keybindings.json file located in ~/.waveterm/config. User-defined shortcuts declared in this file will override the default system keybindings.

Anatomy of a Keybinding

Each keybinding rule in the keybindings.json file consists of the following fields:

  "command": "app:openBookmarksView",
  "keys": ["Cmd:b"],
  "commandStr": ["/bookmarks:show"],
  "info": "Show all bookmarks"
  • command (required): Contains the identifier of the command to execute. It is not advised to edit these commands as they are internal Wave commands. Please see the usage section for details on adding your own custom commands.
  • keys (required): An array of strings representing the keys pressed that trigger the command.
  • commandStr (optional): An array of strings that is executed when the specified keys are pressed. This field accepts Wave slash commands and shell commands.
  • info (optional): A human-readable description of the keybinding’s purpose or functionality.

Note: When choosing keys for custom keybindings, it’s important to consider potential conflicts with existing system or application shortcuts, special character input, accessibility, and cross-platform compatibility. For this reason we recommend avoiding using the Option key.

Key Code Support

Wave supports JavaScript key codes, which are numerical values that correspond to specific keys on a keyboard, regardless of the keyboard layout or locale. By using key codes, you can create custom keyboard shortcuts that work consistently across different keyboards and languages. Wave specifically uses the event.key property.

Use this utility to determine the correct event.key for specific keys.


There are four main ways to utilize custom keybindings in Wave.

Note: If you want to use a keybinding that is already occupied by a system command, you will first need to assign a new keybinding to the system command. Once you have freed up the desired keybinding, you can then assign it to your custom command in the keybindings.json file.

Getting Started

Getting started with custom keybindings in Wave is an easy and straightforward process.

1. Start by copying the default-keybindings file from our repo into your local config, or simply use it as a reference.

  curl -o ~/.waveterm/config/keybindings.json

2. Edit the keybindings to your liking or add your own keybindings for various use cases and tasks, then save the file.

3. Reload the current Wave session using Option + R to start using your custom keybindings.

Note: Currently, Wave does not automatically pick up changes in the custom keybindings file. You need to reload the current Wave session as described above or by clicking the “View” tab in the menu bar and then clicking “Reload.”