Custom Keybindings
As of September 2024, this version of Wave Terminal is deprecated. To learn more about our new version (>=v0.8.0), check out www.waveterm.dev. To find documentation for our new version, check out docs.waveterm.dev.
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.
Basics
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(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.
Usage
There are four main ways to utilize custom keybindings in Wave.
1. Edit a default keybinding
1. Edit a default keybinding
You can modify an existing keybinding to change the associated keys or behavior by editing the keys field with the desired key combination.
Note: The original keybinding for app:restartCommand was Cmd:r.
2. Add key code support to a keybinding
2. Add key code support to a keybinding
You can add JavaScript key codes to create keybindings that work consistently across different keyboards and languages.
The {KeyZ} keycode will ensure that The Z key is used for this keybinding, regardless of the user’s keyboard layout.
3. Create a custom command
3. Create a custom command
Wave allows you to create your own custom commands by modifying the command and commandStr fields.
-
In the command field, use the
custom:prefix, along with your command name, to add a custom command name. -
In the commandStr field, add a custom command using a slash command, shell command, or a combination of both.
Note: This example utilizes the /codeedit command to open my
.zshrcconfig file for quick editing.
4. Create a custom command (with multiple commands)
4. Create a custom command (with multiple commands)
Wave also allows you to string multiple commands together in the commandStr array to create powerful custom workflows that automate complex tasks with a single keybinding.
Note: This example utilizes the /sleep command, which may be necessary between other commands to ensure they execute in the correct order, as the keybinding frontend code doesn’t yet detect when commands have finished.
To better understand this example, let’s take a look at the individual commands in the commandStr array:
Extra: Here’s a complementary keybinding example that demonstrates how you would tear down the debug environment — which is as simple as deleting the workspace:
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.
Example
Example
To reassign the Cmd+b keybinding to your custom command, you would need to:
- Add the default “Open Bookmarks View” command in the
keybindings.jsonfile and assign it a different keybinding, such asCmd+Shift+b:
- Add a new entry in the
keybindings.jsonfile for your custom command, assigning it theCmd+bkeybinding that was previously occupied by the “Open Bookmarks View” command:
Now, when you press Cmd+b, it will execute your custom command. Also, the “Open Bookmarks View” command will still be available, but it will be triggered by the new keybinding Cmd+Shift+b.
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.
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.”