wezterm show-keys

Display key bindings and assignments configured in WezTerm

The show-keys command displays the key assignments configured in your WezTerm instance, making it easy to discover and document your keyboard shortcuts.

Synopsis

wezterm show-keys [OPTIONS]

Description

Displays all key bindings configured in your WezTerm configuration. This is useful for:

• Discovering what key bindings are available
• Debugging key binding conflicts
• Generating documentation for your configuration
• Exporting key bindings in Lua format

Options

--lua · flag

Show the keys as Lua config statements.

Instead of a human-readable table, outputs valid Lua code that can be used in your wezterm.lua configuration file.

Example:

wezterm show-keys --lua

--key-table · string

In Lua mode, show only the named key table.

WezTerm supports multiple key tables for different modes (like tmux’s prefix key). Use this option to show bindings for a specific table.

Requires: --lua flag

Example:

wezterm show-keys --lua --key-table copy_mode

Examples

Show all key bindings

wezterm show-keys

Output will show a table like:

Key Assignments:

CTRL+SHIFT+T  -> SpawnTab(CurrentPaneDomain)
CTRL+SHIFT+N  -> SpawnWindow
CTRL+SHIFT+W  -> CloseCurrentTab{confirm=true}
...

Export key bindings as Lua

wezterm show-keys --lua

Output will be valid Lua code:

return {
  keys = {
    {
      key = 't',
      mods = 'CTRL|SHIFT',
      action = wezterm.action.SpawnTab 'CurrentPaneDomain',
    },
    {
      key = 'n',
      mods = 'CTRL|SHIFT',
      action = wezterm.action.SpawnWindow,
    },
    -- ...
  },
}

Show specific key table

wezterm show-keys --lua --key-table copy_mode

This shows only the key bindings for copy mode.

Save key bindings to a file

wezterm show-keys --lua > my-keys.lua

Check for specific binding

wezterm show-keys | grep "CTRL+SHIFT+C"

Compare key bindings between configs

# Save current bindings
wezterm show-keys > keys-current.txt

# Modify config, then compare
wezterm show-keys > keys-new.txt
diff keys-current.txt keys-new.txt

Understanding Key Tables

WezTerm supports multiple key tables for modal key bindings. Common key tables include:

• Default table: Active by default
• copy_mode: Active when in copy/search mode
• search_mode: Active when searching
• Custom tables: You can define your own

Example with key tables in wezterm.lua:

local wezterm = require 'wezterm'
local act = wezterm.action

return {
  leader = { key = 'a', mods = 'CTRL', timeout_milliseconds = 1000 },
  
  keys = {
    -- Default key table
    {
      key = 'c',
      mods = 'LEADER',
      action = act.ActivateKeyTable {
        name = 'copy_mode',
        one_shot = false,
      },
    },
  },
  
  key_tables = {
    copy_mode = {
      { key = 'Escape', action = act.CopyMode 'Close' },
      { key = 'q', action = act.CopyMode 'Close' },
      { key = 'h', action = act.CopyMode 'MoveLeft' },
      { key = 'j', action = act.CopyMode 'MoveDown' },
      { key = 'k', action = act.CopyMode 'MoveUp' },
      { key = 'l', action = act.CopyMode 'MoveRight' },
    },
  },
}

Then inspect just the copy_mode table:

wezterm show-keys --lua --key-table copy_mode

Common Key Binding Modifiers

• CTRL - Control key
• SHIFT - Shift key
• ALT - Alt/Option key
• SUPER - Windows/Command key
• LEADER - Leader key (if configured)

Modifiers can be combined with |:

• CTRL|SHIFT
• CTRL|ALT
• SUPER|SHIFT

Use Cases

Documentation

Generate documentation for your team:

wezterm show-keys > team-shortcuts.txt

Debugging Conflicts

If a key binding isn’t working:

wezterm show-keys | grep -i "ctrl.*t"

This helps identify if the key is bound to something else.

Configuration Backup

Before making changes:

wezterm show-keys --lua > backup-keys.lua

Learning Default Bindings

If you haven’t customized your config yet:

wezterm show-keys

This shows all default WezTerm key bindings.

Sharing Configuration

Export your key bindings to share with others:

wezterm show-keys --lua | grep -A 10 "my custom bindings"

Default Key Bindings

WezTerm comes with sensible defaults. Some common ones include:

• CTRL+SHIFT+T - New tab
• CTRL+SHIFT+N - New window
• CTRL+SHIFT+W - Close tab
• CTRL+SHIFT+C - Copy (when text is selected)
• CTRL+SHIFT+V - Paste
• CTRL+SHIFT+F - Search
• CTRL+SHIFT+L - Show launcher
• CTRL+Tab - Next tab
• CTRL+SHIFT+Tab - Previous tab

Run wezterm show-keys to see the complete list for your configuration.

Customizing Key Bindings

To customize key bindings, edit your wezterm.lua:

local wezterm = require 'wezterm'
local act = wezterm.action

return {
  keys = {
    -- Disable default binding
    { key = 't', mods = 'CTRL|SHIFT', action = act.DisableDefaultAssignment },
    
    -- Add custom binding
    { key = 't', mods = 'ALT', action = act.SpawnTab 'CurrentPaneDomain' },
    
    -- Custom action
    {
      key = 'r',
      mods = 'CTRL|SHIFT',
      action = act.ReloadConfiguration,
    },
  },
}

Then verify with:

wezterm show-keys | grep -E "CTRL.*SHIFT.*[TR]"

Related

• wezterm ls-fonts - Display font information
• WezTerm Key Binding Configuration Documentation