keybindings.mdx

sidebar_position	2
id	keybindings
title	Key Bindings

import { Kbd, KbdChord } from "@site/src/components/kbd"; import { PlatformProvider, PlatformSelectorButton } from "@site/src/components/platformcontext";

Here's the set of default keybindings available in Wave. It is split into sections. Some keybindings are always active. Others are only active for certain types of blocks.

Note that these are the MacOS keybindings (they use "Cmd"). For Windows and Linux, replace "Cmd" with "Alt" (note that "Ctrl" is "Ctrl" on both Mac, Windows, and Linux).

Chords are shown with a + between the keys. You have 2 seconds to hit the 2nd chord key after typing the first key. Hitting Escape after an initial chord key will always be a no-op.

Global Keybindings

Key	Function
	Open a new tab
	Open a new block (defaults to a terminal block with the same connection and working directory). Switch to launcher using app:defaultnewblock setting
	Toggle WaveAI panel visibility
	Split horizontally, open a new block to the right
	Split vertically, open a new block below
<KbdChord karr={["Ctrl:Shift:s", "ArrowUp"]}/>	Split vertically, open a new block above
<KbdChord karr={["Ctrl:Shift:s", "ArrowDown"]}/>	Split vertically, open a new block below
<KbdChord karr={["Ctrl:Shift:s", "ArrowLeft"]}/>	Split horizontally, open a new block to the left
<KbdChord karr={["Ctrl:Shift:s", "ArrowRight"]}/>	Split horizontally, open a new block to the right
	Open a new window
	Close the current block
	Close the current tab
	Magnify / Un-Magnify the current block
	Open the "connection" switcher
	Refocus the current block (useful if the block has lost input focus)
	Show block numbers
	Focus WaveAI input
	Switch to block number
/	Move left, right, up, down between blocks
	Cycle block focus forward (CW)
	Cycle block focus backward (CCW)
	Replace the current block with a launcher block
	Switch to tab number
/	Switch tab left
/	Switch tab right
	Switch to workspace number
	Refresh the UI
	Toggle terminal multi-input mode

File Preview Keybindings

Key	Function
	Any regular character (e.g. "a", "b") will filter the file list
	Clears the filter
/	Change file selection up/down
	Open the currently selected file/directory
	Move "up" a directory (parent directory)
	Back, move to the previously selected file/directory
	Forward (opposite of back)
	Open a new file (accepts relative paths to the current directory)
	When file editor is open, save file
	For files that can be previewed or edited (markdown, CSVs), switches between preview and edit mode
	When file editor is open, revert changes

Web Keybindings

Key	Function
	Focus the URL input bar
	When the URL input bar is focused, will focus the web content
	Reload webpage
	Back
	Forward
	Find in webpage
	Open a bookmark

WaveAI Keybindings

Key	Function
	Toggle WaveAI panel
	Focus WaveAI input
	Clear AI Chat

Terminal Keybindings

Key	Function
	Copy
	Paste
	Paste (Windows Only)
	Clear Terminal
	Find in Terminal
	Scroll to top
	Scroll to bottom
	Scroll to top (macOS only)
	Scroll to bottom (macOS only)
	Move to beginning of line (macOS only)
	Move to end of line (macOS only)
	Scroll up one page
	Scroll down one page

Customizing Keybindings

You can override, remap, or disable any default keybinding by editing keybindings.json in the Wave config directory (~/.config/waveterm/keybindings.json). You can also edit this file from within Wave by opening the Config editor and selecting "Keybindings" in the sidebar.

The file uses a VS Code-style array format. Each entry maps a key combination to an action ID. Only overrides are needed — all defaults apply automatically.

Key Syntax

Key combinations use colon-separated format:

• Modifiers: Cmd (macOS Command / Windows-Linux Meta), Ctrl, Shift, Alt (macOS Option), Meta
• Special keys: ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Home, End, Escape, Enter, Tab, Space, Backspace, Delete
• Letters and digits: Lowercase (a–z), digits (0–9)

Examples

Rebind a key: Change "new tab" from to :

[
  { "key": "Cmd:Shift:t", "command": "tab:new" }
]

Disable a keybinding: Remove close block:

[
  { "command": "-block:close" }
]

You can also set key to null to unbind:

[
  { "key": null, "command": "block:close" }
]

Swap two keys:

[
  { "key": "Cmd:d", "command": "block:splitdown" },
  { "key": "Cmd:Shift:d", "command": "block:splitright" }
]

Action IDs

Action ID	Default Key	Description
tab:new		Open a new tab
tab:close		Close the current tab
tab:prev		Switch to previous tab
tab:next		Switch to next tab
tab:switchto1–tab:switchto9	–	Switch to tab N
block:new		Open a new block
block:close		Close the current block
block:splitright		Split right
block:splitdown		Split down
block:magnify		Magnify/unmagnify block
block:refocus		Refocus the current block
block:navup/navdown/navleft/navright		Navigate between blocks
block:navcw		Cycle block focus forward (CW)
block:navccw		Cycle block focus backward (CCW)
block:switchto1–block:switchto9	–	Switch to block N
block:switchtoai		Focus WaveAI input
block:replacewithlauncher		Replace block with launcher
app:search		Find/search
app:openconnection		Open connection switcher
app:toggleaipanel		Toggle WaveAI panel
app:togglewidgetssidebar		Toggle widgets sidebar
app:settings		Open settings
term:togglemultiinput		Toggle terminal multi-input
generic:cancel		Close modals/search
block:splitchord		Initiate split chord

Changes take effect immediately — no restart required.

Customizable Systemwide Global Hotkey

Wave allows setting a custom global hotkey to focus your most recent window from anywhere in your computer. For more information on this, see the config docs.