Skip to main content
The wezterm.action module provides constructors for defining key assignment actions in your configuration file. It offers an ergonomic way to express keyboard shortcuts, mouse bindings, and other input actions.

​
Overview

wezterm.action is a special enum constructor type that makes it easier to define actions compared to the older table-based syntax. It provides:
  • Type-safe action constructors
  • Autocomplete-friendly syntax
  • Clear error messages for typos
  • Backward compatibility with older configs

​
Constructor Syntax

Indexing wezterm.action with a valid KeyAssignment name acts as a constructor for that action type. 
wezterm.action.QuickSelectArgs  -- Constructor for QuickSelectArgs
wezterm.action.Copy             -- Constructor for Copy action
wezterm.action.ActivateTab      -- Constructor for ActivateTab

​
Action Types

​
Unit Variants (No Parameters)

Actions that don’t require parameters can be referenced directly: 
local wezterm = require 'wezterm'

return {
  keys = {
    {
      key = 'c',
      mods = 'CTRL|SHIFT',
      action = wezterm.action.Copy,
    },
    {
      key = 'v',
      mods = 'CTRL|SHIFT',
      action = wezterm.action.Paste,
    },
  },
}

​
Actions with Default Parameters

Some actions have optional parameters and can be used with or without arguments: 
local wezterm = require 'wezterm'

return {
  keys = {
    -- Use with defaults
    {
      key = ' ',
      mods = 'CTRL|SHIFT',
      action = wezterm.action.QuickSelectArgs,
    },
    -- Or with custom parameters
    {
      key = 'y',
      mods = 'CTRL|SHIFT',
      action = wezterm.action.QuickSelectArgs {
        alphabet = 'abc',
        patterns = { 'https?://\\S+' },
      },
    },
  },
}

​
Tuple Variants (Positional Parameters)

Actions with positional parameters are called like functions: 
local wezterm = require 'wezterm'
local act = wezterm.action  -- Shortcut alias

return {
  keys = {
    { key = 'F1', mods = 'ALT', action = act.ActivatePaneByIndex(0) },
    { key = 'F2', mods = 'ALT', action = act.ActivatePaneByIndex(1) },
    { key = 'F3', mods = 'ALT', action = act.ActivatePaneByIndex(2) },
    
    { key = '{', mods = 'CTRL', action = act.ActivateTabRelative(-1) },
    { key = '}', mods = 'CTRL', action = act.ActivateTabRelative(1) },
  },
}

​
Common Actions

​
Tab Management

{
  key = 't',
  mods = 'CTRL|SHIFT',
  action = wezterm.action.SpawnTab('CurrentPaneDomain'),
}

​
Pane Management

{
  key = '\"',
  mods = 'CTRL|SHIFT',
  action = wezterm.action.SplitHorizontal { domain = 'CurrentPaneDomain' },
}

​
Font Size

{
  key = '+',
  mods = 'CTRL',
  action = wezterm.action.IncreaseFontSize,
}

​
Scrollback

{
  key = 'PageUp',
  mods = 'SHIFT',
  action = wezterm.action.ScrollByPage(-1),
}

​
Copy and Paste

local wezterm = require 'wezterm'

return {
  keys = {
    {
      key = 'c',
      mods = 'CTRL|SHIFT',
      action = wezterm.action.CopyTo('Clipboard'),
    },
    {
      key = 'v',
      mods = 'CTRL|SHIFT',
      action = wezterm.action.PasteFrom('Clipboard'),
    },
  },
}

​
Search and Selection

local wezterm = require 'wezterm'

return {
  keys = {
    {
      key = 'f',
      mods = 'CTRL|SHIFT',
      action = wezterm.action.Search { CaseSensitiveString = '' },
    },
    {
      key = 'Space',
      mods = 'CTRL|SHIFT',
      action = wezterm.action.QuickSelect,
    },
    {
      key = 'X',
      mods = 'CTRL|SHIFT',
      action = wezterm.action.ActivateCopyMode,
    },
  },
}

​
Multiple Actions

Execute multiple actions with a single key press: 
{
  key = 'E',
  mods = 'CTRL|SHIFT',
  action = wezterm.action.Multiple {
    wezterm.action.ClearScrollback('ScrollbackAndViewport'),
    wezterm.action.SendKey { key = 'L', mods = 'CTRL' },
  },
}

​
Workspace Management

local wezterm = require 'wezterm'

return {
  keys = {
    {
      key = 's',
      mods = 'CTRL|SHIFT',
      action = wezterm.action.SwitchToWorkspace {
        name = 'default',
      },
    },
    {
      key = 'n',
      mods = 'CTRL|SHIFT',
      action = wezterm.action.SwitchToWorkspace {
        name = 'monitoring',
        spawn = {
          args = { 'htop' },
        },
      },
    },
  },
}

​
Key Tables

Activate custom key tables for modal key bindings: 
{
  key = 'r',
  mods = 'LEADER',
  action = wezterm.action.ActivateKeyTable {
    name = 'resize_pane',
    one_shot = false,
    timeout_milliseconds = 1000,
  },
}

​
Custom Events

Emit custom events that can be handled with event handlers: 
{
  key = 'u',
  mods = 'CTRL|SHIFT',
  action = wezterm.action.EmitEvent('trigger-my-event'),
}

​
Checking Action Availability

You can check if an action exists before using it: 
local wezterm = require 'wezterm'

if wezterm.has_action('QuickSelectArgs') then
  wezterm.log_info('QuickSelectArgs is available')
end

​
Older Syntax (Pre-20220624)

For backward compatibility, the older table syntax is still supported: 
local wezterm = require 'wezterm'

return {
  keys = {
    {
      key = '{',
      mods = 'CTRL',
      action = wezterm.action {
        ActivateTabRelative = -1,
      },
    },
  },
}
The new constructor syntax is recommended for all new configurations as it provides better type checking and clearer syntax.

​
Using Aliases

For brevity, create a shortcut alias: 
local wezterm = require 'wezterm'
local act = wezterm.action

return {
  keys = {
    { key = 't', mods = 'CTRL', action = act.SpawnTab('CurrentPaneDomain') },
    { key = 'w', mods = 'CTRL', action = act.CloseCurrentTab { confirm = false } },
  },
}

​
Key Assignment Categories

Actions are available for:
  • Tabs: Spawn, close, activate, move tabs
  • Panes: Split, close, navigate, resize panes
  • Scrollback: Scroll by page/line, search, clear
  • Copy/Paste: Copy to clipboard, paste from clipboard
  • Font: Increase, decrease, reset font size
  • Window: Toggle fullscreen, hide, quit
  • Workspaces: Switch, create workspaces
  • Launchers: Show launcher, tab navigator
  • Custom: Emit events, run callbacks

​
Source Reference

Implementation: config/src/lua.rs:345