18 KiB
Both the keyboard and (starting with the most recently nightly builds) the mouse bindings are configurable.
The assignments are based around a triggering event, such as a keypress or mouse button click, which is combined with a set of modifier keys to produce an action.
A full list of possible keys, mouse events and actions are included below, after these tables describing the default assignments.
Default 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 |
ALT |
9 |
ShowTabNavigator |
SUPER |
r |
ReloadConfiguration |
CTRL+SHIFT |
R |
ReloadConfiguration |
SUPER |
h |
HideApplication (macOS only) |
SUPER |
k |
ClearScrollback |
CTRL+SHIFT |
K |
ClearScrollback |
SUPER |
f |
Search={CaseSensitiveString=""} |
CTRL+SHIFT |
F |
Search={CaseSensitiveString=""} |
CTRL+SHIFT |
X |
ActivateCopyMode |
Default Mouse Assignments
In the table below, Triple Left Down
means that the left mouse button is
being triple clicked and that the event matches the downstroke of the third
quick consecutive press. Triple Left Up
matches the subsequent release event
of that triple click, so for a triple click both
SelectTextAtMouseCursor="Line"
and CompleteSelection
will be triggered in
that order.
Event | Modifiers | Action |
---|---|---|
Triple Left Down | NONE |
SelectTextAtMouseCursor="Line" |
Double Left Down | NONE |
SelectTextAtMouseCursor="Word" |
Single Left Down | NONE |
SelectTextAtMouseCursor="Cell" |
Single Left Down | SHIFT |
ExtendSelectionToMouseCursor=nil |
Single Left Up | NONE |
CompleteSelectionOrOpenLinkAtMouseCursor |
Double Left Up | NONE |
CompleteSelection |
Triple Left Up | NONE |
CompleteSelection |
Single Left Drag | NONE |
ExtendSelectionToMouseCursor="Cell" |
Double Left Drag | NONE |
ExtendSelectionToMouseCursor="Word" |
Triple Left Drag | NONE |
ExtendSelectionToMouseCursor="Line" |
Single Middle Down | NONE |
Paste |
Configuring Mouse Assignments
available in the most recent nightly
You can define mouse actions using the mouse_bindings
configuration section:
local wezterm = require 'wezterm';
return {
mouse_bindings = {
-- Right click sends "woot" to the terminal
{
event={Down={streak=1, button="Right"}},
mods="NONE",
action=wezterm.action{SendString="woot"}
},
-- Change the default click behavior so that it only selects
-- text and doesn't open hyperlinks
{
event={Up={streak=1, button="Left"}},
mods="NONE",
action="CompleteSelection",
},
-- and make CTRL-Click open hyperlinks
{
event={Up={streak=1, button="Left"}},
mods="CTRL",
action="OpenLinkAtMouseCursor",
},
},
}
The action
and mods
portions are described in more detail in the key assignment
information below.
The event
portion has three components;
- Whether it is a
Down
,Up
orDrag
event - The number of consecutive clicks within the click threshold (the click streak)
- The mouse button;
Left
,Right
, orMiddle
.
A double click is a down-up-down
sequence where either the second button down
is held for long enough or is released and no subsequent down event occurs
within the click threshold. When recognized, it emits a Down
event with
streak=2
. If the mouse is moved while the button is held, a Drag
event
with streak=2
is generated. When the mouse button is released an Up
event
with streak=2
is generated.
The mouse event recognizer supports an arbitrary click streak, so if
you wanted quadruple-click bindings you can specify streak=4
.
Event | Lua Representation |
---|---|
Triple Left Down | event={Down={streak=3, button="Left"}} |
Double Left Up | event={Up={streak=2, button="Left"}} |
Single Left Drag | event={Drag={streak=1, button="Left"}} |
Configuring Key Assignments
These can be overridden using the keys
section in your ~/.wezterm.lua
config file.
For example, you can disable a default assignment like this:
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 theCommand
key, on Windows theWindows
key, on Linux this can also be theSuper
orHyper
key. Left and right are equivalent.SHIFT
- The shift key. Left and right are equivalent.ALT
,OPT
,META
- these are all equivalent: on macOS theOption
key, on other systems theAlt
orMeta
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:
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.
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 environmentdomain
- specifies the domain into which the tab will be spawned. SeeSpawnTab
for examples.
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)
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.
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
.
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
.
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.
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.
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%
local wezterm = require 'wezterm';
return {
keys = {
{key="=", mods="CTRL", action="IncreaseFontSize"},
}
}
DecreaseFontSize
Decreases the font size of the current window by 10%
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
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.
local wezterm = require 'wezterm';
return {
keys = {
{key="m", mods="CMD", action=wezterm.action{SendString="Hello"}},
}
}
DisableDefaultAssignment
Has no special meaning of its own; this action will undo the registration of a default assignment if that key/mouse/modifier combination is one of the default assignments and cause the key press to be propagated through to the tab for processing.
return {
keys = {
-- Turn off the default CMD-m Hide action, allowing CMD-m to
-- be potentially recognized and handled by the tab
{key="m", mods="CMD", action="DisableDefaultAssignment"},
}
}
Nop
Causes the key press to have no effect; it behaves as though those keys were not pressed.
return {
keys = {
-- Turn off any side effects from pressing CMD-m
{key="m", mods="CMD", action="Nop"},
}
}
Hide
Hides the current window
return {
keys = {
{key="h", mods="CMD", action="Hide"},
}
}
HideApplication
On macOS, hide the WezTerm application.
return {
keys = {
{key="h", mods="CMD", action="HideApplication"},
}
}
QuitApplication
Terminate the WezTerm application, killing all tabs.
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.
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.
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.
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.
local wezterm = require 'wezterm';
return {
keys = {
{key="PageUp", mods="SHIFT", action=wezterm.action{ScrollByPage=-1}},
{key="PageDown", mods="SHIFT", action=wezterm.action{ScrollByPage=1}},
}
}
ClearScrollback
Clears the lines that have scrolled off the top of the viewport, resetting the scrollbar thumb to the full height of the window.
return {
keys = {
{key="K", mods="CTRL|SHIFT", action="ClearScrollback"}
}
}
ReloadConfiguration
Explicitly reload the configuration.
return {
keys = {
{key="r", mods="CMD|SHIFT", action="ReloadConfiguration"},
}
}
ShowLauncher
Activate the Launcher Menu in the current tab.
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.
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 though 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.
Search
since: latest nightly
This action will trigger the search overlay for the current tab.
It accepts a typed pattern string as its parameter, allowing for
Regex
, CaseSensitiveString
and CaseInSensitiveString
as
pattern matching types.
The supported regular expression syntax is described here.
local wezterm = require 'wezterm';
return {
keys = {
-- search for things that look like git hashes
{key="H", mods="SHIFT|CTRL", action=wezterm.action{Search={Regex="[a-f0-9]{6,}"}}},
-- search for the lowercase string "hash" matching the case exactly
{key="H", mods="SHIFT|CTRL", action=wezterm.action{Search={CaseSensitiveString="hash"}}},
-- search for the string "hash" matching regardless of case
{key="H", mods="SHIFT|CTRL", action=wezterm.action{Search={CaseInSensitiveString="hash"}}},
},
}
ActivateCopyMode
since: latest nightly
Activates copy mode!