Skip to main content

​
Introduction

Key assignments in WezTerm allow you to bind keyboard shortcuts to specific actions. The key assignment system is highly flexible, supporting modifiers, key tables, and complex action sequences.

​
Basic Key Binding

Key bindings are configured through the keys table in your configuration file: 
local wezterm = require 'wezterm'
local act = wezterm.action
local config = {}

config.keys = {
  {
    key = 't',
    mods = 'CTRL|SHIFT',
    action = act.SpawnTab 'CurrentPaneDomain',
  },
}

return config

​
Key Assignment Structure

Each key binding consists of three components:
​
key
string
required
The key to bind. Can be a letter, number, function key (F1-F24), or special key name
​
mods
string
Modifier keys to require. Common modifiers include:
  • CTRL - Control key
  • SHIFT - Shift key
  • ALT - Alt/Option key
  • SUPER or CMD - Windows/Command key
Combine multiple modifiers with |, e.g., CTRL|SHIFT
​
action
KeyAssignment
required
The action to perform when the key combination is pressed

​
Key Assignment Categories

Key assignments are organized into several categories:

​
Tab Management

Actions for creating, closing, and navigating between tabs:
  • SpawnTab - Create new tabs
  • ActivateTab - Switch to specific tabs
  • CloseCurrentTab - Close tabs
  • MoveTab - Reorder tabs
Learn more about tab actions →

​
Pane Management

Actions for splitting, resizing, and navigating panes:
  • SplitHorizontal / SplitVertical - Split panes
  • ActivatePaneDirection - Navigate between panes
  • AdjustPaneSize - Resize panes
  • CloseCurrentPane - Close panes
Learn more about pane actions →

​
Copy and Paste

Actions for clipboard operations:
  • CopyTo - Copy selection to clipboard
  • PasteFrom - Paste from clipboard
  • SelectTextAtMouseCursor - Start text selection
Learn more about copy/paste actions →

​
Scrolling

Actions for scrolling through terminal output:
  • ScrollByPage - Scroll by pages
  • ScrollByLine - Scroll by lines
  • ScrollToTop / ScrollToBottom - Jump to extremes
  • ScrollToPrompt - Navigate by shell prompts
Learn more about scrolling actions → Actions for searching terminal content:
  • Search - Open search overlay
  • ActivateCopyMode - Enter copy mode for keyboard navigation
Learn more about search actions →

​
Multiple Actions

You can bind a single key combination to multiple actions using the Multiple action: 
config.keys = {
  {
    key = 'E',
    mods = 'CTRL|SHIFT',
    action = act.Multiple {
      act.CopyTo 'Clipboard',
      act.ClearSelection,
    },
  },
}

​
Disabling Default Bindings

To disable a default key binding without assigning a new action: 
config.keys = {
  {
    key = 'Enter',
    mods = 'ALT',
    action = act.DisableDefaultAssignment,
  },
}

​
Key Tables

Key tables allow you to create modal key binding modes, similar to vim: 
config.leader = { key = 'a', mods = 'CTRL', timeout_milliseconds = 1000 }

config.keys = {
  {
    key = 'r',
    mods = 'LEADER',
    action = act.ActivateKeyTable {
      name = 'resize_pane',
      one_shot = false,
    },
  },
}

config.key_tables = {
  resize_pane = {
    { key = 'LeftArrow', action = act.AdjustPaneSize { 'Left', 1 } },
    { key = 'RightArrow', action = act.AdjustPaneSize { 'Right', 1 } },
    { key = 'UpArrow', action = act.AdjustPaneSize { 'Up', 1 } },
    { key = 'DownArrow', action = act.AdjustPaneSize { 'Down', 1 } },
    { key = 'Escape', action = 'PopKeyTable' },
  },
}

​
Special Keys

WezTerm supports a wide range of special keys:
  • Function keys: F1 through F24
  • Navigation: UpArrow, DownArrow, LeftArrow, RightArrow, PageUp, PageDown, Home, End
  • Editing: Insert, Delete, Backspace, Enter, Tab, Escape
  • Media keys: VolumeUp, VolumeDown, VolumeMute, Play, Pause

​
Best Practices

Use the act alias for wezterm.action to make your configuration more concise and readable
Be careful when overriding default key bindings. Some applications rely on specific key combinations being passed through to the terminal
You can view all active key bindings by pressing CTRL+SHIFT+L (or your configured key) to open the command palette, then selecting “Show Launcher” → “Key Assignments”