Skip to main content

​
Overview

Tab-related key assignments allow you to manage multiple terminal sessions within a single window. WezTerm provides actions for creating tabs, switching between them, closing them, and rearranging their order.

​
Creating Tabs

​
SpawnTab

Create a new tab in the current window: 
local wezterm = require 'wezterm'
local act = wezterm.action
local config = {}

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

return config
​
domain
SpawnTabDomain
Specifies which domain to use for the new tab:
  • 'CurrentPaneDomain' - Use the domain of the current pane (default)
  • 'DefaultDomain' - Use the default domain
  • { DomainName = 'name' } - Use a specific domain by name

​
SpawnCommandInNewTab

Create a new tab and run a specific command: 
config.keys = {
  {
    key = 'n',
    mods = 'CTRL|SHIFT',
    action = act.SpawnCommandInNewTab {
      args = { 'htop' },
    },
  },
  {
    key = 'm',
    mods = 'CTRL|SHIFT',
    action = act.SpawnCommandInNewTab {
      label = 'Monitoring',
      args = { 'bash', '-c', 'htop' },
      cwd = '/var/log',
    },
  },
}
​
args
string[]
Command and arguments to run in the new tab
​
cwd
string
Working directory for the command
​
label
string
Optional descriptive label for the command
​
domain
SpawnTabDomain
Which domain to spawn the tab in

​
ActivateTab

Activate a specific tab by index (0-based): 
config.keys = {}

-- Bind Alt+1 through Alt+9 to switch to tabs 1-9
for i = 1, 9 do
  table.insert(config.keys, {
    key = tostring(i),
    mods = 'ALT',
    action = act.ActivateTab(i - 1),
  })
end
Negative indices are supported: -1 activates the rightmost tab, -2 the second from right, etc.

​
ActivateTabRelative

Move to a tab relative to the current one: 
config.keys = {
  -- Move to next tab
  {
    key = 'Tab',
    mods = 'CTRL',
    action = act.ActivateTabRelative(1),
  },
  -- Move to previous tab
  {
    key = 'Tab',
    mods = 'CTRL|SHIFT',
    action = act.ActivateTabRelative(-1),
  },
}
​
offset
integer
required
Number of tabs to move. Positive values move right, negative move left. Wraps around at the ends.

​
ActivateTabRelativeNoWrap

Same as ActivateTabRelative, but doesn’t wrap around: 
config.keys = {
  {
    key = 'RightArrow',
    mods = 'CTRL|SHIFT',
    action = act.ActivateTabRelativeNoWrap(1),
  },
  {
    key = 'LeftArrow',
    mods = 'CTRL|SHIFT',
    action = act.ActivateTabRelativeNoWrap(-1),
  },
}

​
ActivateLastTab

Switch to the most recently active tab: 
config.keys = {
  {
    key = '9',
    mods = 'ALT',
    action = act.ActivateLastTab,
  },
}

​
Managing Tabs

​
CloseCurrentTab

Close the currently active tab: 
config.keys = {
  {
    key = 'w',
    mods = 'CTRL|SHIFT',
    action = act.CloseCurrentTab { confirm = true },
  },
}
​
confirm
boolean
default:"false"
When true, shows a confirmation overlay before closing the tab
Use confirm = true to prevent accidentally closing tabs with unsaved work

​
MoveTab

Move the current tab to a specific position: 
config.keys = {
  -- Move current tab to the first position
  {
    key = 'Home',
    mods = 'CTRL|SHIFT',
    action = act.MoveTab(0),
  },
}
​
position
integer
required
The target position (0-based index) for the tab

​
MoveTabRelative

Move the current tab relative to its current position: 
config.keys = {
  -- Move current tab one position to the left
  {
    key = 'PageUp',
    mods = 'CTRL|SHIFT',
    action = act.MoveTabRelative(-1),
  },
  -- Move current tab one position to the right
  {
    key = 'PageDown',
    mods = 'CTRL|SHIFT',
    action = act.MoveTabRelative(1),
  },
}
​
offset
integer
required
Number of positions to move. Positive values move right, negative move left.

​
Tab Navigation UI

​
ShowTabNavigator

Display a visual tab navigator overlay: 
config.keys = {
  {
    key = 'Tab',
    mods = 'ALT',
    action = act.ShowTabNavigator,
  },
}
The tab navigator shows thumbnails of all open tabs, allowing you to quickly identify and switch to a specific tab.

​
Complete Example

Here’s a comprehensive tab management configuration: 
local wezterm = require 'wezterm'
local act = wezterm.action
local config = {}

config.keys = {
  -- Create new tab
  { key = 't', mods = 'CTRL|SHIFT', action = act.SpawnTab 'CurrentPaneDomain' },
  
  -- Close current tab
  { key = 'w', mods = 'CTRL|SHIFT', action = act.CloseCurrentTab { confirm = true } },
  
  -- Navigate tabs
  { key = 'Tab', mods = 'CTRL', action = act.ActivateTabRelative(1) },
  { key = 'Tab', mods = 'CTRL|SHIFT', action = act.ActivateTabRelative(-1) },
  
  -- Show tab navigator
  { key = 'Tab', mods = 'ALT', action = act.ShowTabNavigator },
}

return config