Keyboard and Commands
Documentation in progress
Some sections are still incomplete.
ThinkTerm adds very few keyboard shortcuts of its own. The keymap is WezTerm's, apart from the number keys described below, and most of what ThinkTerm adds around the terminal — Spaces, Threads, the Live Overview, Remote Hosts — is reached with the mouse, the command palette or, on macOS, the menu bar. Any of those commands can be given a key on the Keymap page in Settings or in the config file.
The shortcuts ThinkTerm adds
| Action | macOS | Linux and Windows |
|---|---|---|
| Open Settings | ⌘, | Ctrl+Shift+, |
| Open or close the command palette | ⌘⇧P | Ctrl+Shift+P |
| Find Thread | ⌘P | — |
| Open the 1st to 9th Thread in the sidebar | ⌘1 to ⌘9 | Ctrl+Shift+1 to 9 |
| Go to the 1st to 8th tab, or with 9 the last one | Ctrl+1 to Ctrl+9 | Ctrl+1 to Ctrl+9 |
Everything else is WezTerm's default keymap, listed on WezTerm's Default Key Assignments page: ⌘T for a new tab, ⌘W to close one, ⌘C and ⌘V, the font-size keys, and the rest. Ctrl+Shift+P opens the palette on macOS too, as it does in WezTerm. ⌘P opens the palette already inside its Find Thread group; off macOS Ctrl+P belongs to the shell, so there is no default key for it.
The number keys
⌘1 to ⌘9 (Ctrl+Shift+1 to 9 elsewhere) open the first nine Threads of the sidebar, counting from the top and only the rows that have a Thread on them. Hold ⌘ (Ctrl+Shift elsewhere) for about half a second and each of those rows shows the chord that reaches it. Anything else pressed meanwhile ends the hold until the keys come up, so a shortcut of your own never flashes the numbers. Both follow the Keymap page: change a chord there and the keys to hold and the numbers change with it.
The tabs moved to Ctrl+1 to Ctrl+8, and Ctrl+9 for the last tab, on every system; in WezTerm they were ⌘1 to ⌘9 on macOS and Ctrl+Shift+1 to 9 elsewhere. A plain Ctrl and a digit therefore no longer reaches the program in the terminal, such as Ctrl-6 in vim or Ctrl-7 as undo in Emacs and readline. Bind the chord to DisableDefaultAssignment to hand it back.
thinkterm show-keys prints the keymap actually in force, with any keys of your own folded in, those set on the Keymap page included. Setting disable_default_key_bindings = true removes ThinkTerm's shortcuts along with WezTerm's — except that the palette keeps its default chords unless a chord of your own already opens it, or you have bound or freed those chords yourself. Shortcuts set on the Keymap page are not affected by it.
What has no shortcut
Apart from ⌘P for Find Thread on macOS and the number keys for the first nine Threads, there are no default keys for switching Spaces or Projects, for a new Thread, for the sidebars, for the Live Overview or for the Library. They are reached this way instead:
| To | Use |
|---|---|
| Go to any Thread, in any Space | The number keys above for the first nine of the sidebar, or Find Thread at the bottom of the sidebar, Shell › Find Thread on macOS, or the palette's Find Thread group |
| Switch Space | The Space menu at the top of the sidebar, the palette's Switch Space group, or Previous Space and Next Space (Window menu on macOS, or the palette) |
| Make a new Space | The Space menu › New Space |
| Add a Thread to the Project you are in | New Thread at the top of the sidebar, Shell › New Thread on macOS, or New Thread in the palette |
| Open the Live Overview | Its button at the bottom of the sidebar, Shell › Live Overview on macOS, or Live Overview in the palette |
| Show the Library, every Space as a card in place of the left sidebar | Its button at the bottom of the sidebar, Shell › ThinkTerm Library on macOS, or ThinkTerm Library in the palette |
| Open Remote Hosts | Its button at the bottom of the sidebar, Shell › Remote Hosts... on macOS, or the palette |
| Show or hide a sidebar | The sidebar buttons in the tab row, View › Toggle Left Sidebar and View › Toggle Right Sidebar on macOS, or the palette |
| Rename a tab | Rename Tab… on the tab's right-click menu |
Each of these has an action you can bind to a key — see Binding ThinkTerm's actions. All but a new Space and renaming a tab can be bound on the Keymap page too; its list holds only the actions the palette has by default. Going to a particular Thread or Space has no action of its own, but the palette gets there from the keyboard: open it and type a few letters of the name, and with Search Inside Groups on, as it is by default, the search reaches into the Find Thread and Switch Space groups.
The command palette
⌘⇧P (Ctrl+Shift+P on Linux and Windows) opens the command palette, and so does Edit › Activate Command Palette on macOS. It lists every command ThinkTerm and WezTerm have, with its key if it has one, and narrows as you type. Pressing the shortcut again, Escape, Ctrl+G or a click outside closes it.
The palette is a narrow card with a footer. At the top of the list come Find Thread and a few commands people reach for most: a new Thread, tab and window, splitting the pane, closing the tab, searching and Settings. Those that you have used lately lead, the rest keep that order, and the groups and every other command follow. Each row shows the key the command is bound to now, one set on the Keymap page included, and Find Thread shows its own. Keys that only work inside copy mode are left out. The selection follows the pointer as it moves over the rows.
The footer names two keys: Change Keymap with ⌘↵ (Ctrl+Enter on Linux and Windows), and Action with Enter. Change Keymap opens Settings › Keymap with the selected command's name already in Search actions, so its shortcut can be changed from where you found it; clicking the footer button does the same. If the Keymap page has no such command, as for a group or a Thread, it opens with an empty search.
Two other places open it part-way in. The Find Thread button at the bottom of the sidebar, and ⌘P on macOS, open it inside the Find Thread group, and clicking Effective Color Scheme in Settings › Appearance opens it inside Change Theme. Backing out of either lands in the full list.
Choosing its shortcut
Settings › Command Palette has four rows:
| Setting | What it does |
|---|---|
Shortcut | The chord that opens and closes the palette: ⌘ ⇧ P (the default), ⌘ P, ⌘ K or ⌃ ⇧ P |
Visible Rows | How many results show before the list scrolls. Auto, the default, fits the window; otherwise 1 to 30 |
Font Size | The palette's text size, 8 to 32 points. Reset goes back to command_palette_font_size from the config, which is 13 unless you set it |
Search Inside Groups | Whether a search at the top level also shows a few matches from inside the groups. On by default |
Off macOS, ⌘ in those labels means the Super key, except in the default: ⌘ ⇧ P is Ctrl+Shift+P there, because the desktop usually keeps Super for itself.
The chord picked here is added to the shortcuts set on the Keymap page, bound to the palette, so it wins over whatever the chord did before. ⌘ K is the case to know: in WezTerm's keymap ⌘K clears the scrollback, and with ⌘ K picked it opens the palette instead. Clearing the scrollback stays in the palette, as Clear scrollback. On macOS, picking ⌘ P likewise takes ⌘P from Find Thread. The default chords are part of the keymap rather than this setting, so ⌘⇧P and Ctrl+Shift+P go on working whichever chord you pick. thinkterm show-keys lists the chord you picked.
The two settings share their chords. Picking a chord clears it from anything the Keymap page had set on it, and setting that chord on the Keymap page for another action replaces the pick. When none of the four chords in the menu opens the palette any more — the default was removed or given to another action on the Keymap page, say — the Shortcut row reads Set in Keymap.
Keys inside the palette
| Key | What it does |
|---|---|
| ↑ ↓, or Ctrl+P and Ctrl+N | Move the selection |
| Page Up, Page Down | Move the selection a page |
| Home, End | With the search empty, jump to the first or last entry; otherwise move the caret |
| Enter | Run the selected command, or open the selected group |
| Tab | Open the selected group |
| Backspace | With the search empty inside a group, go back out of it, restoring the search and selection you left |
| Ctrl+U | Clear the search |
| ⌘Enter (Ctrl+Enter on Linux and Windows) | Open Settings › Keymap, searching for the selected command |
| Escape, Ctrl+G or the palette shortcut | Close the palette |
| ⌘A, ⌘C, ⌘X, ⌘V | Select all, copy, cut and paste in the search field. Ctrl on Linux and Windows |
| ⌘← ⌘→, ⌘⌫ | Caret to the start or end, delete to the start. macOS |
| ⌥← ⌥→, ⌥⌫ | Move or delete by word. Ctrl on Linux and Windows |
Groups
Large families of commands are folded into groups, so that a thousand colour schemes do not bury the rest of the list. A group opens like a folder.
| Group | What it holds |
|---|---|
Find Thread | Every saved Thread in every Space, under its Project, with the Space it belongs to on the right. Pinned Threads come first and Threads of archived Projects last, marked (Archived). A search matches the Thread, its Project, its Space and the folder's path. Choosing one switches Space first when it has to |
Change Theme | Every colour scheme, the built-in ones and any in your config's color_schemes, with Use configured default at the top. Moving the selection previews each scheme on the window; Enter applies it to every window and remembers it. Closing the palette any other way puts the colours back |
Switch Space | The Spaces this window can show. It appears once there are three or more |
Switch Workspace | WezTerm's own multiplexer workspaces, other than the current one |
New Tab in Domain, Attach Domain, Detach Domain | The multiplexer domains, as in WezTerm |
Launch | The entries of your launch_menu |
The last five fold into a group only when they have three entries or more; with fewer, their commands sit in the main list. Once a search is two characters long, up to three matches from inside each group are listed after the direct matches, so typing a scheme's name finds it without opening Change Theme first. Search Inside Groups turns that off.
Find Thread is the only place that lists Threads outside the current Space, and archived ones; the sidebar shows one Space at a time.
Recents
The palette remembers what you run. Commands used often and recently sort to the top of the command list, below the groups and the common commands, and inside Change Theme the schemes you choose move up the same way. The record is recent-commands.json in ThinkTerm's data directory — see Configuration for where that is — and it keeps up to 200 entries, dropping the least used first.
Commands of your own can be added with WezTerm's augment-command-palette event, as in WezTerm.
The macOS menus
ThinkTerm's own commands sit in the macOS menu bar beside WezTerm's:
| Menu | Item | Key |
|---|---|---|
| ThinkTerm | About ThinkTerm | |
| ThinkTerm | Check for Updates... — opens Settings › Software Update | |
| ThinkTerm | Reload configuration | ⌘R |
| ThinkTerm | Settings... | ⌘, |
| ThinkTerm | Hide Application | ⌘H |
| ThinkTerm | Quit ThinkTerm | ⌘Q |
| ThinkTerm | Quit and Stop Session Server — quits, and ends every terminal in the background session server | |
| Shell | New Thread — adds a Thread to the Project you are in | |
| Shell | Live Overview | |
| Shell | ThinkTerm Library | |
| Shell | Remote Hosts... | |
| Shell | Add Remote Host... — opens Remote Hosts on a blank host | |
| Shell | Find Thread — opens the palette inside its Find Thread group | ⌘P |
| Edit | Activate Command Palette | ⌘⇧P |
| View | Toggle Left Sidebar | |
| View | Toggle Right Sidebar | |
| Window | Previous Space | |
| Window | Next Space | |
| Window | Select Thread, with Activate 1st Thread to Activate 9th Thread | ⌘1 to ⌘9 |
Linux and Windows have no menu bar. There, the same commands are in the command palette under the same names, apart from About ThinkTerm, Hide Application and Quit ThinkTerm.
A few commands are in the palette only, with no menu item and no key:
| Command | What it does |
|---|---|
Archive Active Workspace | Archives the Project you are in, closing its panes and keeping its Threads and layouts |
Show Archived Workspaces | Shows archived Projects at the bottom of the sidebar, until run again or the window closes |
The Find Thread, Change Theme and Switch Space groups | As above |
In those two command names "workspace" means a Project, which is what the sidebar's menus call it. The Switch Workspace group is something else: WezTerm's multiplexer workspaces. Command names in the menu bar, the palette and the Keymap page follow the interface language, and the menu bar is rebuilt as soon as you switch. The tables on this page give the names in English. The palette remembers what you run by its English name, so its recents survive a switch. Spaces, Projects and Threads covers archiving.
Binding ThinkTerm's actions
Keys are set in the config file's keys table, exactly as in WezTerm — see WezTerm's Key Binding page. ThinkTerm adds these actions to wezterm.action:
| Action | What it does |
|---|---|
OpenSettings | Opens Settings |
CheckForUpdates | Opens Settings on the Software Update page |
QuitAndStopSessionServer | Quits ThinkTerm and stops the background session server, ending every terminal in it |
ToggleLiveOverview | Opens or closes the Live Overview |
ToggleLibrary | Shows the Library in place of the left sidebar, or brings the sidebar back |
ActivateWorkspaceThreadByIndex | Opens the Thread on the sidebar's row of that number, counting from 0 and only the rows that have a Thread on them. The first nine are bound to the number keys |
OpenSshHosts | Opens or closes Remote Hosts |
AddRemoteHost | Opens Remote Hosts on a blank host |
OpenThreadSearch | Opens the command palette inside its Find Thread group, as the sidebar's Find Thread button does |
CreateWorkspaceThreadInActiveProject | Adds a Thread to the Project you are in, as New Thread in the sidebar does |
ToggleWorkspaceSidebar | Shows or hides the left sidebar |
ToggleRightSidebar | Shows or hides the right sidebar |
CreateSpace | Makes a new Space, switches the window to it and opens its name for editing |
ActivateSpaceRelative | Moves the window by that many Spaces, negative for earlier ones, in the order a swipe on the sidebar goes through them, and stops at either end. -1 and 1 are Previous Space and Next Space |
ArchiveActiveProject | Archives the Project you are in, as Archive Active Workspace does |
ToggleShowArchivedProjects | Shows or hides archived Projects in the sidebar |
PromptRenameTab | Opens the current tab's name for editing |
SpawnTabToRight | Opens a new tab just to the right of the current one, in the domain given |
SetColorScheme | Switches the terminal's colour scheme by name, as Change Theme does, and remembers it |
FocusPluginPanel | Opens the right sidebar on the panel of the plugin whose id it is given and gives that panel the keyboard; pressed again while the panel has it, the keyboard goes back to the terminal. See Plugins |
local wezterm = require 'wezterm'
local act = wezterm.action
local config = wezterm.config_builder()
config.keys = {
{ key = 'o', mods = 'CMD|SHIFT', action = act.ToggleLiveOverview },
{ key = 'LeftArrow', mods = 'CMD|ALT', action = act.ActivateSpaceRelative(-1) },
{ key = 'RightArrow', mods = 'CMD|ALT', action = act.ActivateSpaceRelative(1) },
{ key = 'b', mods = 'CMD|ALT', action = act.ToggleRightSidebar },
{ key = 'n', mods = 'CMD|ALT', action = act.CreateSpace },
{ key = 'r', mods = 'CMD|ALT', action = act.PromptRenameTab },
{ key = 't', mods = 'CMD|ALT', action = act.SpawnTabToRight 'CurrentPaneDomain' },
{ key = 'd', mods = 'CMD|ALT', action = act.SetColorScheme 'Dracula' },
}
return configAn action you bind also shows its key in the palette, and one that is not in the palette by default, such as PromptRenameTab, joins it once it has a key. FocusPluginPanel is the exception: a plugin's panel is reached from the sidebar, so the action stays out of the palette whatever key it has.
Escape and Enter
In the Library, Escape brings the sidebar back, unless something else has the keyboard first: a dialog, copy mode, the Live Overview or a field in the right sidebar. Every other key still goes to the terminal beside it.
In the Live Overview, Escape closes it. When a card is asking whether to close its terminal, Escape answers no first, and a second press closes the overview.
When renaming in place — a Space, Project, Thread or tab, or a file in the Files panel — the name opens with all of it selected. Enter keeps the new name and Escape abandons it. Clicking anywhere else, or switching to another app, keeps it too, as Enter would. Inside the name, the copy, paste and caret keys are the same as in the palette's search field.
The Keymap page
Settings › Keymap changes shortcuts without touching the config file. It draws a keyboard — the Mac layout on macOS, a PC layout elsewhere — and each key shows the action it runs under the modifiers switched on above it.
Above the keyboard sit a Search actions box and four modifier switches: ⌘ Command, ⇧ Shift, ⌥ Option and ⌃ Control on macOS, Ctrl, Shift, Alt and Super (Win on Windows) elsewhere. The modifier keys drawn on the keyboard flip the same switches. They start on ⌘ on macOS and Ctrl+Shift elsewhere, the modifiers the platform's own shortcuts start with. Click a key to see its chord, the action it runs and where the shortcut comes from; the buttons under it depend on what the key is:
| The key | It means | Buttons |
|---|---|---|
The action's name, Default | A shortcut built into ThinkTerm or WezTerm | Change…, Remove |
The action's name, Config file | A shortcut from keys in the config file | Change…, Remove |
The action's name, Changed | A shortcut set on this page. When it replaces a different one from the config file, the detail names that action | Change…, Remove, Reset |
Removed | A default or config file shortcut taken off the key on this page | Reset, Assign… |
Free, drawn blank | Nothing is bound to it | Assign… |
System | The operating system takes the chord before ThinkTerm sees it, such as ⌘Tab on macOS or Alt+Tab on Linux and Windows | None |
Shell | Free to bind, but the shell and the programs in the terminal use it: a key such as Enter, an arrow or a letter pressed alone or with Shift, or a printable key with Ctrl or Alt. Binding it takes it from them | Assign Anyway… |
Remove frees the chord. Reset takes back what was set on this page, so the key returns to what the config file or the defaults give it.
Changing a shortcut
Change… on a key, or Add Shortcut beside an action in the search list, asks for the new chord: Press the new shortcut for the action, and Esc cancels. Pressing modifiers alone does nothing, and neither does a key pressed alone or with Shift that is not a function key, since it would only type or move. A chord the system takes is refused and the page keeps listening. On macOS the menu shortcuts are held back while it listens, so ⌘W is recorded rather than closing the tab.
If the chord already runs another action, the page says so and offers Replace or Cancel; if the shell and its programs use it, it offers Use Anyway or Cancel. Changing a key moves the action off its old chord, which is freed — or goes back to the config file's or the default action if it had been set on this page.
Assign… on a free key lists the actions under Pick the action for the chord, each with an Assign button that gives the key to that action. Typing in Search actions narrows that list; with no key being assigned, it lists the actions whose names match, each with its current shortcuts and an Add Shortcut button that asks for a chord as above. Either list shows 50 at most, then n more — narrow the search to see them.
An action that runs a function made with wezterm.action_callback cannot be changed or given another chord here: only thinkterm.lua can keep the function, so the page leaves it and says so.
Your changes
Once anything is set, Your changes lists each shortcut that differs from the config file and the defaults, with its tag — Added, Changed or Removed — and a button: Remove for an added one, Reset for the others. Clicking a row shows its key on the keyboard. Reset All Shortcuts below forgets every shortcut set on this page, and the palette Shortcut pick with them.
Where they are kept
Shortcuts set here are saved in settings.json under keymap.keys, in the { key, mods, action } form of the config file's keys, and the config file itself is never rewritten. A shortcut set here wins over keys in the config file, which win over the defaults. A default or config file shortcut that was removed is kept as DisableDefaultAssignment on its chord. Only the default key table is covered here, not named key_tables.
A change reaches every open window at once, without reloading the configuration, and the macOS menu bar shows the new keys.
Keys elsewhere
- The TUI has a keymap of its own, behind a Ctrl-b prefix — see TUI.
- The browser page has its own keys and its own search shortcut — see Web.
- The Notes editor's keys are described in Files and Notes.
- What a right click in a terminal does, and Ctrl (Control on macOS) with it to get the menu, is in Copy and paste. Dragging a pane tab onto a cell to join, split or swap is in Window tabs and pane tabs.
Related
- Spaces, Projects and Threads — what the palette's Space and Thread commands act on
- The Window — the sidebar, the Live Overview and the tab row
- Configuration — the config file the
keystable goes in - Command Line —
thinkterm show-keys