> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wezterm/wezterm/llms.txt
> Use this file to discover all available pages before exploring further.

# Tab Key Actions

> Key assignments for creating, navigating, and managing tabs in WezTerm

## 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:

```lua theme={null}
local wezterm = require 'wezterm'
local act = wezterm.action
local config = {}

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

return config
```

<ParamField path="domain" type="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
</ParamField>

### SpawnCommandInNewTab

Create a new tab and run a specific command:

```lua theme={null}
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',
    },
  },
}
```

<ParamField path="args" type="string[]">
  Command and arguments to run in the new tab
</ParamField>

<ParamField path="cwd" type="string">
  Working directory for the command
</ParamField>

<ParamField path="label" type="string">
  Optional descriptive label for the command
</ParamField>

<ParamField path="domain" type="SpawnTabDomain">
  Which domain to spawn the tab in
</ParamField>

## Navigating Tabs

### ActivateTab

Activate a specific tab by index (0-based):

```lua theme={null}
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
```

<Note>
  Negative indices are supported: `-1` activates the rightmost tab, `-2` the second from right, etc.
</Note>

### ActivateTabRelative

Move to a tab relative to the current one:

```lua theme={null}
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),
  },
}
```

<ParamField path="offset" type="integer" required>
  Number of tabs to move. Positive values move right, negative move left. Wraps around at the ends.
</ParamField>

### ActivateTabRelativeNoWrap

Same as `ActivateTabRelative`, but doesn't wrap around:

```lua theme={null}
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:

```lua theme={null}
config.keys = {
  {
    key = '9',
    mods = 'ALT',
    action = act.ActivateLastTab,
  },
}
```

## Managing Tabs

### CloseCurrentTab

Close the currently active tab:

```lua theme={null}
config.keys = {
  {
    key = 'w',
    mods = 'CTRL|SHIFT',
    action = act.CloseCurrentTab { confirm = true },
  },
}
```

<ParamField path="confirm" type="boolean" default="false">
  When `true`, shows a confirmation overlay before closing the tab
</ParamField>

<Tip>
  Use `confirm = true` to prevent accidentally closing tabs with unsaved work
</Tip>

### MoveTab

Move the current tab to a specific position:

```lua theme={null}
config.keys = {
  -- Move current tab to the first position
  {
    key = 'Home',
    mods = 'CTRL|SHIFT',
    action = act.MoveTab(0),
  },
}
```

<ParamField path="position" type="integer" required>
  The target position (0-based index) for the tab
</ParamField>

### MoveTabRelative

Move the current tab relative to its current position:

```lua theme={null}
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),
  },
}
```

<ParamField path="offset" type="integer" required>
  Number of positions to move. Positive values move right, negative move left.
</ParamField>

## Tab Navigation UI

### ShowTabNavigator

Display a visual tab navigator overlay:

```lua theme={null}
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:

<CodeGroup>
  ```lua Basic Tab Navigation theme={null}
  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
  ```

  ```lua Advanced Tab Management theme={null}
  local wezterm = require 'wezterm'
  local act = wezterm.action
  local config = {}

  config.keys = {
    -- Create tabs
    { key = 't', mods = 'CTRL|SHIFT', action = act.SpawnTab 'CurrentPaneDomain' },
    
    -- Close tab
    { key = 'w', mods = 'CTRL|SHIFT', action = act.CloseCurrentTab { confirm = true } },
    
    -- Move tabs
    { key = 'PageUp', mods = 'CTRL|SHIFT', action = act.MoveTabRelative(-1) },
    { key = 'PageDown', mods = 'CTRL|SHIFT', action = act.MoveTabRelative(1) },
    
    -- Navigate with wrapping
    { key = 'Tab', mods = 'CTRL', action = act.ActivateTabRelative(1) },
    { key = 'Tab', mods = 'CTRL|SHIFT', action = act.ActivateTabRelative(-1) },
    
    -- Navigate without wrapping
    { key = 'RightArrow', mods = 'CTRL|SHIFT', action = act.ActivateTabRelativeNoWrap(1) },
    { key = 'LeftArrow', mods = 'CTRL|SHIFT', action = act.ActivateTabRelativeNoWrap(-1) },
    
    -- Jump to last tab
    { key = '9', mods = 'ALT', action = act.ActivateLastTab },
    
    -- Tab navigator
    { key = 'Tab', mods = 'ALT', action = act.ShowTabNavigator },
  }

  -- Direct tab access with Alt+1 through Alt+8
  for i = 1, 8 do
    table.insert(config.keys, {
      key = tostring(i),
      mods = 'ALT',
      action = act.ActivateTab(i - 1),
    })
  end

  return config
  ```

  ```lua Custom Tab Commands theme={null}
  local wezterm = require 'wezterm'
  local act = wezterm.action
  local config = {}

  config.keys = {
    -- Spawn specific commands in new tabs
    {
      key = 'h',
      mods = 'CTRL|SHIFT',
      action = act.SpawnCommandInNewTab {
        label = 'htop',
        args = { 'htop' },
      },
    },
    {
      key = 'l',
      mods = 'CTRL|SHIFT',
      action = act.SpawnCommandInNewTab {
        label = 'Logs',
        args = { 'bash', '-c', 'tail -f /var/log/syslog' },
        cwd = '/var/log',
      },
    },
  }

  return config
  ```
</CodeGroup>

## Related Actions

* [Pane Actions](/lua/keyassignment/panes) - Split tabs into multiple panes
* [Workspaces](/lua/keyassignment/overview#workspaces) - Organize multiple windows into workspaces