wezterm/docs/config/keys.markdown

### Shortcut / Key Binding Assignments

The default key bindings are:

| Modifiers | Key | Action |
| --------- | --- | ------ |
| `SUPER`     | `c`   | `Copy`  |
| `SUPER`     | `v`   | `Paste`  |
| `CTRL+SHIFT`     | `c`   | `Copy`  |
| `CTRL+SHIFT`     | `v`   | `Paste`  |
| `SHIFT`     | `Insert` | `Paste` |
| `SUPER`     | `m`      | `Hide`  |
| `SUPER`     | `n`      | `SpawnWindow` |
| `CTRL+SHIFT`     | `n`      | `SpawnWindow` |
| `ALT`       | `Enter`  | `ToggleFullScreen` |
| `SUPER`     | `-`      | `DecreaseFontSize` |
| `CTRL`      | `-`      | `DecreaseFontSize` |
| `SUPER`     | `=`      | `IncreaseFontSize` |
| `CTRL`      | `=`      | `IncreaseFontSize` |
| `SUPER`     | `0`      | `ResetFontSize` |
| `CTRL`      | `0`      | `ResetFontSize` |
| `SUPER`     | `t`      | `SpawnTab="CurrentTabDomain"` |
| `CTRL+SHIFT`     | `t`      | `SpawnTab="CurrentTabDomain"` |
| `SUPER+SHIFT` | `T`    | `SpawnTab="DefaultDomain"` |
| `SUPER`     | `w`      | `CloseCurrentTab` |
| `SUPER`     | `1`      | `ActivateTab=0` |
| `SUPER`     | `2`      | `ActivateTab=1` |
| `SUPER`     | `3`      | `ActivateTab=2` |
| `SUPER`     | `4`      | `ActivateTab=3` |
| `SUPER`     | `5`      | `ActivateTab=4` |
| `SUPER`     | `6`      | `ActivateTab=5` |
| `SUPER`     | `7`      | `ActivateTab=6` |
| `SUPER`     | `8`      | `ActivateTab=7` |
| `SUPER`     | `9`      | `ActivateTab=8` |
| `CTRL+SHIFT`     | `w`      | `CloseCurrentTab` |
| `CTRL+SHIFT`     | `1`      | `ActivateTab=0` |
| `CTRL+SHIFT`     | `2`      | `ActivateTab=1` |
| `CTRL+SHIFT`     | `3`      | `ActivateTab=2` |
| `CTRL+SHIFT`     | `4`      | `ActivateTab=3` |
| `CTRL+SHIFT`     | `5`      | `ActivateTab=4` |
| `CTRL+SHIFT`     | `6`      | `ActivateTab=5` |
| `CTRL+SHIFT`     | `7`      | `ActivateTab=6` |
| `CTRL+SHIFT`     | `8`      | `ActivateTab=7` |
| `CTRL+SHIFT`     | `9`      | `ActivateTab=8` |
| `SUPER+SHIFT` | `[` | `ActivateTabRelative=-1` |
| `SUPER+SHIFT` | `]` | `ActivateTabRelative=1` |
| `CTRL+SHIFT`     | `PAGEUP`      | `MoveTabRelative=-1` |
| `CTRL+SHIFT`     | `PAGEDOWN`      | `MoveTabRelative=1` |
| `SHIFT`          | `PAGEUP`      | `ScrollByPage=-1` |
| `SHIFT`          | `PAGEDOWN`    | `ScrollByPage=1` |

These can be overridden using the `keys` section in your `~/.wezterm.lua` config file.
For example, you can disable a default assignment like this:

```lua
local wezterm = require 'wezterm';

return {
  keys = {
    -- Turn off the default CMD-m Hide action on macOS by making it
    -- send the empty string instead of hiding the window
    {key="m", mods="CMD", action="Nop"}
  }
}
```

The `key` value can be one of the following keycode identifiers.  Note that not
all of these are meaningful on all platforms:

`Hyper`, `Super`, `Meta`, `Cancel`, `Backspace`, `Tab`, `Clear`, `Enter`,
`Shift`, `Escape`, `LeftShift`, `RightShift`, `Control`, `LeftControl`,
`RightControl`, `Alt`, `LeftAlt`, `RightAlt`, `Menu`, `LeftMenu`, `RightMenu`,
`Pause`, `CapsLock`, `PageUp`, `PageDown`, `End`, `Home`, `LeftArrow`,
`RightArrow`, `UpArrow`, `DownArrow`, `Select`, `Print`, `Execute`,
`PrintScreen`, `Insert`, `Delete`, `Help`, `LeftWindows`, `RightWindows`,
`Applications`, `Sleep`, `Numpad0`, `Numpad1`, `Numpad2`, `Numpad3`,
`Numpad4`, `Numpad5`, `Numpad6`, `Numpad7`, `Numpad8`, `Numpad9`, `Multiply`,
`Add`, `Separator`, `Subtract`, `Decimal`, `Divide`, `NumLock`, `ScrollLock`,
`BrowserBack`, `BrowserForward`, `BrowserRefresh`, `BrowserStop`,
`BrowserSearch`, `BrowserFavorites`, `BrowserHome`, `VolumeMute`,
`VolumeDown`, `VolumeUp`, `MediaNextTrack`, `MediaPrevTrack`, `MediaStop`,
`MediaPlayPause`, `ApplicationLeftArrow`, `ApplicationRightArrow`,
`ApplicationUpArrow`, `ApplicationDownArrow`.

Alternatively, a single unicode character can be specified to indicate
pressing the corresponding key.

Possible Modifier labels are:

 * `SUPER`, `CMD`, `WIN` - these are all equivalent: on macOS the `Command` key,
   on Windows the `Windows` key, on Linux this can also be the `Super` or `Hyper`
   key.  Left and right are equivalent.
 * `SHIFT` - The shift key.  Left and right are equivalent.
 * `ALT`, `OPT`, `META` - these are all equivalent: on macOS the `Option` key,
   on other systems the `Alt` or `Meta` key.  Left and right are equivalent.

You can combine modifiers using the `|` symbol (eg: `"CMD|CTRL"`).

# Possible Actions

Possible actions are listed below.

## SpawnTab

Create a new tab in the current window.  The argument defines to which *domain* the tab belongs:

```lua
local wezterm = require 'wezterm';
return {
  keys = {
    -- Create a new tab in the default domain
    {key="t", mods="SHIFT|ALT", action=wezterm.action{SpawnTab="DefaultDomain"}},
    -- Create a new tab in the same domain as the current tab
    {key="t", mods="SHIFT|ALT", action=wezterm.action{SpawnTab="CurrentTabDomain"}},
    -- Create a tab in a named domain
    {key="t", mods="SHIFT|ALT", action=wezterm.action{SpawnTab={DomainName="unix"}}},
  }
}
```

## SpawnWindow

Create a new window containing a tab from the default tab domain.

```lua
local wezterm = require 'wezterm';
return {
  keys = {
    {key="n", mods="SHIFT|CTRL", action="SpawnWindow"},
  }
}
```

## SpawnCommandInNewWindow / SpawnCommandInNewTab

Spawn a new tab either into the current window or into a brand new window.
The argument controls which command is run in the tab; it is a lua table
with the following fields:

* `args` - the argument array specifying the command and its arguments.
  If omitted, the default program will be run.
* `cwd` - the current working directory to set for the command.
* `set_environment_variables` - a table specifying key/value pairs to
  set in the environment
* `domain` - specifies the domain into which the tab will be spawned.
  See `SpawnTab` for examples.

```lua
local wezterm = require 'wezterm';

return {
  keys = {
    -- CMD-y starts `top` in a new window
    {key="y", mods="CMD", action=wezterm.action{SpawnCommandInNewWindow={
      args={"top"}
    }}},
  }
}
```

## ToggleFullScreen

Toggles full screen mode for the current window.  (But see:
<https://github.com/wez/wezterm/issues/177>)

```lua
return {
  keys = {
    {key="n", mods="SHIFT|CTRL", action="ToggleFullScreen"},
  }
}
```

## Copy

Copy the selection to the clipboard.  On X11 systems, this populates both the
Clipboard and the Primary Selection.

```lua
local wezterm = require 'wezterm';
return {
  keys = {
    {key="c", mods="SHIFT|CTRL", action="Copy"},
  }
}
```

## Paste

Paste the clipboard to the current tab.  On X11 systems, this copies from the
Clipboard rather than the Primary Selection.  See also `PastePrimarySelection`.

```lua
local wezterm = require 'wezterm';
return {
  keys = {
    {key="v", mods="SHIFT|CTRL", action="Paste"},
  }
}
```

## PastePrimarySelection

X11: Paste the Primary Selection to the current tab.
On other systems, this behaves identically to `Paste`.

```lua
local wezterm = require 'wezterm';
return {
  keys = {
    {key="v", mods="SHIFT|CTRL", action="PastePrimarySelection"},
  }
}
```

## ActivateTabRelative

Activate a tab relative to the current tab.  The argument value specifies an
offset. eg: `-1` activates the tab to the left of the current tab, while `1`
activates the tab to the right.

```lua
local wezterm = require 'wezterm';
return {
  keys = {
    {key="{", mods="SHIFT|ALT", action=wezterm.action{ActivateTabRelative=-1}},
    {key="}", mods="SHIFT|ALT", action=wezterm.action{ActivateTabRelative=1}},
  }
}
```

## ActivateTab

Activate the tab specified by the argument value. eg: `0` activates the
leftmost tab, while `1` activates the second tab from the left, and so on.

```lua
local wezterm = require 'wezterm';

local mykeys = {}
for i = 1, 8 do
  -- CTRL+ALT + number to activate that tab
  table.insert(mykeys, {
    key=tostring(i),
    mods="CTRL|ALT",
    action=wezterm.action{ActivateTab=i-1},
  })
  -- F1 through F8 to activate that tab
  table.insert(mykeys, {
    key="F" .. tostring(i),
    action=wezterm.action{ActivateTab=i-1},
  })
end

return {
  keys = mykeys,
}
```

## IncreaseFontSize

Increases the font size of the current window by 10%

```lua
local wezterm = require 'wezterm';
return {
  keys = {
    {key="=", mods="CTRL", action="IncreaseFontSize"},
  }
}
```
  
## DecreaseFontSize

Decreases the font size of the current window by 10%

```lua
local wezterm = require 'wezterm';
return {
  keys = {
    {key="-", mods="CTRL", action="DecreaseFontSize"},
  }
}
```

## ResetFontSize

Reset the font size for the current window to the value in your configuration

```lua
local wezterm = require 'wezterm';
return {
  keys = {
    {key="0", mods="CTRL", action="ResetFontSize"},
  }
}
```

## SendString

Sends the string specified argument to the terminal in the current tab, as
though that text were literally typed into the terminal.

```lua
local wezterm = require 'wezterm';

return {
  keys = {
    {key="m", mods="CMD", action=wezterm.action{SendString="Hello"}},
  }
}
```

## Nop

Does nothing.  This is useful to disable a default key assignment.

```lua
local wezterm = require 'wezterm';

return {
  keys = {
    -- Turn off the default CMD-m Hide action
    {key="m", mods="CMD", action="Nop"},
  }
}
```

## Hide

Hides the current window

```lua
return {
  keys = {
    {key="h", mods="CMD", action="Hide"},
  }
}
```

## HideApplication

On macOS, hide the WezTerm application.

```lua
return {
  keys = {
    {key="h", mods="CMD", action="HideApplication"},
  }
}
```

## QuitApplication

Terminate the WezTerm application, killing all tabs.

```lua
return {
  keys = {
    {key="q", mods="CMD", action="QuitApplication"},
  }
}
```

## Show

Shows the current window.

## CloseCurrentTab

Equivalent to clicking the `x` on the window title bar to close it: Closes the
current tab.  If that was the last tab, closes that window.  If that was the
last window, wezterm terminates.

```lua
return {
  keys = {
    {key="w", mods="CMD", action="CloseCurrentTab"},
  }
}
```

## MoveTabRelative

Move the current tab relative to its peers.  The argument specifies an
offset. eg: `-1` moves the tab to the left of the current tab, while `1` moves
the tab to the right.

```lua
local wezterm = require 'wezterm';
return {
  keys = {
    {key="{", mods="SHIFT|ALT", action=wezterm.action{MoveTabRelative=-1}},
    {key="}", mods="SHIFT|ALT", action=wezterm.action{MoveTabRelative=1}},
  }
}
```

## MoveTab

Move the tab so that it has the index specified by the argument. eg: `0`
moves the tab to be  leftmost, while `1` moves the tab so that it is second tab
from the left, and so on.

```lua
local wezterm = require 'wezterm';

local mykeys = {}
for i = 1, 8 do
  -- CTRL+ALT + number to move to that position
  table.insert(mykeys, {
    key=tostring(i),
    mods="CTRL|ALT",
    action=wezterm.action{Move=i-1},
  })
end

return {
  keys = mykeys,
}
```

## ScrollByPage

Adjusts the scroll position by the number of pages specified by the argument.
Negative values scroll upwards, while positive values scroll downwards.

```lua
local wezterm = require 'wezterm';

return {
  keys = {
    {key="PageUp", mods="SHIFT", action=wezterm.action{ScrollByPage=-1}},
    {key="PageDown", mods="SHIFT", action=wezterm.action{ScrollByPage=1}},
  }
}
```

## ReloadConfiguration

Explicitly reload the configuration.

```lua
return {
  keys = {
    {key="r", mods="CMD|SHIFT", action="ReloadConfiguration"},
  }
}
```

## ShowLauncher

Activate the [Launcher Menu](launch.html#the-launcher-menu)
in the current tab.

```lua
return {
  keys = {
    {key="l", mods="ALT", action="ShowLauncher"},
  }
}
```

## ShowTabNavigator

Activate the tab navigator UI in the current tab.  The tab
navigator displays a list of tabs and allows you to select
and activate a tab from that list.

```lua
return {
  keys = {
    {key="F9", mods="ALT", action="ShowTabNavigator"},
  }
}
```

## SelectTextAtMouseCursor

Initiates selection of text at the current mouse cursor position.
The mode argument can be one of `Cell`, `Word` or `Line` to control
the scope of the selection.

## ExtendSelectionToMouseCursor

Extends the current text selection to the current mouse cursor position.
The mode argument can be one of `Cell`, `Word` or `Line` to control
the scope of the selection.

## OpenLinkAtMouseCursor

If the current mouse cursor position is over a cell that contains
a hyperlink, this action causes that link to be opened.

## CompleteSelection

Completes an active text selection process; the selection range is
marked closed and then the selected text is copied as thought the
`Copy` action was executed.

## CompleteSelectionOrOpenLinkAtMouseCursor

If a selection is in progress, acts as though `CompleteSelection` was
triggered.  Otherwise acts as though `OpenLinkAtMouseCursor` was
triggered.