Keybindings

Copy mode and screenshots

Copy mode and screenshots: part of the Keybindings of TUIOS.

This page is one part of docs/KEYBINDINGS.md of the tuios repository. The Keybindings page lists every part.

Copy mode

Ctrl+B [ starts copy mode on the focused pane. The copy cursor starts on the terminal cursor, which is usually the prompt line. tmux does the same. To start in the middle row, set appearance.selection.copy_entry to center.

KeyAction
/Search forward, down to the newest output
?Search backward, up into the scrollback
nGo to the next match in the direction of the last search
NGo to the next match in the opposite direction
Esc in the search promptCancel the search and move the cursor back
vStart a character selection
VStart a line selection
Ctrl+VStart a block selection. In a block selection, end the selection
oGo to the other end of the selection. In a block selection, go to the opposite corner
q or EscLeave copy mode. In a selection, Esc and q only end the selection
EnterLeave copy mode. In a selection, copy the selection, then leave. In the search prompt, Enter runs the search. The action is copy_mode_exit in the copy_mode section
Ctrl+CLeave copy mode from normal mode, a selection, the search prompt or f/t. Nothing is copied

A block selection is a rectangle. The cursor is one corner, and every motion moves that corner. y writes one line for each row, with a newline between rows. A row stops at its last printed character, so a short row is not padded to the right edge. Blanks inside a row stay when the row has text after them. A wide character on an edge of the block is copied whole. A wrapped line copies as one line for each row on the screen. copy_command and the copy pipe keys get the same text.

The prompt shows / or ? to show the direction. The search starts at the copy cursor. When no match is found in that direction, the search continues from the other end of the buffer. n and N start at the copy cursor, so they find the nearest match after you move the cursor.

Two actions start copy mode and open the search prompt with one key:

ActionKey
copy_mode_search_forwardNone
copy_mode_search_backwardNone

They are the same as tmux bind-key b copy-mode \; send-keys ?. They have no default key. Bind one in any section. This example uses Ctrl+B /:

[keybindings.prefix_mode]
copy_mode_search_backward = ["/"]

The command palette also has the entries "Copy mode: search forward" and "Copy mode: search backward". If the pane is already in copy mode, the action opens the prompt and does not move the cursor. In multi copy mode, the prompt opens in each pane of the mode.

In copy mode, a key in the global, terminal_mode or window_management section starts the action. A key under the leader does not start it, because copy mode uses Ctrl+B for page up. In copy mode, / and ? open the same prompts.

When a search finds more than 1000 matches, the prompt shows 1000+.

Focus keys in copy mode

The terminal_focus_left, terminal_focus_right, focus_up and focus_down keys also work in copy mode. In window mode, the window-mode focus keys work. Focus moves to the next pane. The old pane stays in copy mode, as in tmux. When you go back to it, the copy cursor is where you left it.

A focus key that copy mode also uses keeps its copy mode action. For example, h moves the copy cursor, and alt+left moves focus. This example binds alt+h and alt+l as in tmux:

[keybindings.terminal_mode]
terminal_focus_left = ["alt+h"]
terminal_focus_right = ["alt+l"]

A key under the leader does not work in copy mode, because copy mode uses Ctrl+B for page up. Ctrl+B and then an arrow key does not move focus there.

Motions

The cursor motions are bindings in the copy_mode section. In a v, V or Ctrl+V selection they move the end of the selection. A count typed before the key repeats a motion that steps, such as 3j, in a selection too. 10G goes to line 10.

ActionDefault key
copy_mode_left, copy_mode_down, copy_mode_up, copy_mode_righth Left, j Down, k Up, l Right
copy_mode_word_ende
copy_mode_big_word_forward, copy_mode_big_word_backward, copy_mode_big_word_endW, B, E
copy_mode_half_page_up, copy_mode_half_page_downCtrl+U, Ctrl+D
copy_mode_page_up, copy_mode_page_downPgUp, Ctrl+F PgDown
copy_mode_bottomG
copy_mode_screen_top, copy_mode_screen_middle, copy_mode_screen_bottomH, M, L
copy_mode_paragraph_up, copy_mode_paragraph_down{, }
copy_mode_matching_bracket%
copy_mode_repeat_char_search, copy_mode_repeat_char_search_back;, ,

0, ^, $, w, b, Ctrl+B and gg are fixed keys. They do what copy_mode_line_start, copy_mode_first_nonblank, copy_mode_line_end, copy_mode_word_forward, copy_mode_word_backward, copy_mode_page_up and the top of the scrollback do, and you cannot rebind them.

Line start and line end

Home moves the copy cursor to column zero of the line, as 0 does. End moves it to the last nonblank character of the line, as $ does, and not to the blank cells up to the pane edge. copy_mode_first_nonblank moves it to the first nonblank character, as ^ does, and has no default key. On a blank line all three go to column zero. The keys also move the end of a v or V selection.

ActionDefault key
copy_mode_line_startHome
copy_mode_first_nonblanknone
copy_mode_line_endEnd
copy_mode_exitEnter

The keys are in the copy_mode section. They work only in copy mode. In the search prompt, they do not move the cursor. 0, ^ and $ are fixed keys, and you cannot rebind them.

Do not bind a key here that copy mode already uses, such as y or v, or a key of a [[keybindings.copy_pipe]] entry. tuios keybinds doctor and the config check warn about such a key. A copy pipe key runs the pipe, and the binding does not run. A key that copy mode uses loses its copy mode action.

copy_mode_exit leaves copy mode, as q does, and gives the pane the keyboard back. From a v, V or Ctrl+V selection it copies the selection first, as y does, then leaves, as tmux does with Enter. In multi-pane copy mode it copies every selection, as y does there. In the search prompt Enter still runs the search. For the old behaviour, where Enter does nothing in copy mode, set it to no key:

[keybindings.copy_mode]
copy_mode_exit = []

Ctrl+A and Ctrl+E are not defaults. Ctrl+A is a common leader key, and Ctrl+E scrolls one line in tmux copy mode. To use them, add them to the section:

[keybindings.copy_mode]
copy_mode_line_start = ["home", "ctrl+a"]
copy_mode_line_end = ["end", "ctrl+e"]

tuios cannot put two actions on one key. tuios send-keys cannot do it either, because a key from send-keys does not go to copy mode.

Word movement

Shift+Left and Shift+Right move by word as b and w do, including counts and visual selections.

ActionDefault key
copy_mode_word_backwardShift+Left
copy_mode_word_forwardShift+Right

Rebind or disable them in copy mode:

[keybindings.copy_mode]
copy_mode_word_backward = []
copy_mode_word_forward = ["alt+right"]

The fixed b and w keys remain available. Terminal emulators must send shifted arrow keys to tuios for the defaults to work.

Hints in copy mode

s in copy mode puts hint labels on the text in view, so you can copy text that you scrolled back to. See docs/HINTS.md.

KeyWhereAction
sCopy modehints
Ctrl+B FWindow and terminal modehints

Open the scrollback in the editor

Ctrl+G in copy mode opens the scrollback of the pane in your editor. The file has all the scrollback and the screen, as plain text. zellij does the same with e.

KeyWhereAction
Ctrl+GCopy modeedit_scrollback
Ctrl+B EAny modeedit_scrollback

The command palette entry is "Edit the scrollback in the editor".

  • tuios uses the File editor setting first. Then it uses $EDITOR, then $VISUAL, then vi.
  • vi, vim, nvim, nano, emacs, kakoune and helix open at the line of the copy cursor. Outside copy mode, they open at the top of the screen. Other editors open at the start of the file.
  • In a session with a daemon, the text comes from the daemon. It has the full scrollback, also when your client has only part of it.
  • The editor uses the terminal that tuios runs in. tuios comes back when the editor exits.
  • The file is in a private folder. tuios removes the file when the editor exits, and when the client stops.
  • A browser client or an SSH client from another machine cannot open the editor. tuios shows a message.

In copy mode, e and E move to the end of a word, as in vim. For this reason, the editor key is Ctrl+G. Ctrl+G also opens a reply in the editor. To use another key, set it in the copy_mode section:

[keybindings.copy_mode]
edit_scrollback = ["ctrl+o"]

The tmux preset uses Ctrl+B E to make the splits equal. With that preset, the editor key is Ctrl+B Ctrl+T E.

Other end of a selection

In a v or V selection, o moves the copy cursor to the other end of the selection. The selected text does not change. The next motion moves the end that the cursor is on now. Press o again to go back. If the other end is outside the pane, the pane scrolls to show it. tmux and vim use o the same way.

Clear the scrollback

The clear_scrollback action clears the scrollback of the focused pane. It also removes the rows above the prompt, and the prompt row moves to the top of the pane. Ghostty, iTerm2 and Terminal.app do the same on Cmd+K.

ActionDefault key
clear_scrollbackNone

The command palette entry is "Clear the scrollback".

  • tuios sends no key to the program, so the shell does not redraw.
  • When the shell marks its prompt with OSC 133, tuios keeps all the lines of the prompt.
  • In a session with a daemon, the daemon clears the pane. Each client of the session shows the clear. An attach later does not bring the old rows back.
  • The key also works in copy mode. tuios leaves copy mode.
  • tuios clears nothing while a full-screen program, such as vim or less, uses the pane. tuios shows a message.

tuios clear-history clears the scrollback from the command line, as tmux clear-history does. It keeps the screen. With --screen, it does the same as the key. See CLI_REFERENCE.md.

The action has no default key, because the host terminal usually keeps Cmd+K for itself. To use Cmd+K, bind super+k in the global section. A key in the global section works in terminal mode and in window mode.

[keybindings.global]
clear_scrollback = ["super+k"]

Then tell the host terminal to send Cmd+K to tuios. In Ghostty, add this line to the Ghostty config:

keybind = cmd+k=unbind

In iTerm2 and Terminal.app, Cmd+K is a menu item. Remove or change its shortcut in the settings of the terminal. A terminal that does not send the Super key cannot send super+k. Bind another key, such as Ctrl+B K:

[keybindings.prefix_mode]
clear_scrollback = ["K"]

Pipe a yank through a command

A yank can go through a command before it goes to the clipboard. tmux calls this copy-command and copy-pipe. tuios has two parts:

  • appearance.selection.copy_command runs one command on every yank in copy mode.
  • A [[keybindings.copy_pipe]] entry binds a key in copy mode to its own command.
[appearance.selection]
copy_command = "tmux-copy-it"

[[keybindings.copy_pipe]]
key = "p"
command = "tr '\n' ' '"
cancel = true
description = "flatten"

The command runs with sh -c. It gets the selection on stdin. The clipboard gets what the command writes to stdout. When the selection does not end with a new line, tuios removes one new line from the end of the output.

When the command stops with exit code 0 and writes nothing, tuios does not change the clipboard or the paste buffers. The dock shows a message. Use this for a command that sets the clipboard itself, such as tmux-copy-it, or that sends the text to a socket or a file. tmux does the same: the write of the command stays.

The clipboard gets the selection itself in these cases:

  • The command stops with an exit code that is not 0. The dock shows the exit code and the first line of stderr.
  • The command runs for more than 10 seconds. tuios stops the command and the processes that it started.

tuios waits until the command closes its stdout. xclip starts a process that stays open after xclip stops, and keeps stdout open. tuios then waits 1 second more. To prevent the wait, send the stdout of xclip to /dev/null. This example puts each yank in the X primary selection. The command writes nothing, so the clipboard does not change:

[appearance.selection]
copy_command = "xclip -selection primary >/dev/null"

The fields of a [[keybindings.copy_pipe]] entry:

  • key is the key in copy mode. Write it as in the other sections.
  • command gets the selection on stdin.
  • cancel says what happens after the yank. With false, the default, copy mode stays on and the cursor stays where it is. tuios clears the selection. This is tmux copy-pipe. With true, copy mode stops, as with q. This is tmux copy-pipe-and-cancel.
  • description names the entry in the dock messages. It is optional.

The entry takes its key from copy mode. An entry on y replaces the plain yank. Copy mode does not use p or P. When an entry takes q, Esc, Ctrl+C, v, V, /, ? or a digit, tuios shows a warning when it loads the config. When no text is selected, the key shows a message and runs nothing. While you type a search, the key goes into the search.

Without copy_command, y copies the selection as it is. With copy_command, y and c pipe the selection through that command. A [[keybindings.copy_pipe]] key always uses its own command. A mouse selection that copies on release does not use copy_command. A drag does not run a command.

In multi copy mode, the command gets the text that y copies: the selection of each pane, joined in the current format. It runs one time for all panes. Use the json format to process each pane separately, for example with jq. With cancel = true, multi copy mode stops in every pane.

The command runs on the machine that runs the tuios client. That is the same machine as for a shell command key. For the SSH and web clients, it is the server. The command starts in the folder of the focused pane and gets the variables of a command key: TUIOS_SESSION, TUIOS_SOCKET, TUIOS_ACTIVE_PANE_ID and TUIOS_ACTIVE_PANE_CWD. You can use tuios while the command runs.

Paste buffers

tuios keeps your recent yanks as paste buffers, as tmux does. A yank in copy mode adds a buffer, and so does a mouse selection that you copy. The yank also goes to the clipboard, as before.

KeyActionWhat it does
Ctrl+B ]paste_bufferPaste the newest buffer into the focused pane
Ctrl+B #choose_bufferShow the buffers, newest first, to choose one

Ctrl+B ] takes the newest of your own buffers: what you copied, or set yourself. A buffer that a program in a pane without admin set is never your newest, so no such program can set what the key pastes. The paste goes to the pane that was focused when you pressed the key, also when the focus moves before the text arrives. Each line feed becomes a carriage return, as in tmux.

In the list, Enter or a click pastes the buffer, d deletes it, and Esc or q closes the list. The list shows "from pane" and the pane's name on a buffer that a program in a pane set, because you did not copy that text. A paste goes in the bracketed paste marks when the program in the pane asks for them, as a clipboard paste does.

tmux shows the list on =. In tuios, Ctrl+B = makes the splits equal, so the list is on #, the tmux key for list-buffers. To use the tmux keys, move the splits key and give = to the list:

[keybindings.prefix_mode]
equalize_splits = ["E"]
choose_buffer = ["="]

The daemon keeps the buffers, so every client and every session shares them. A client with no daemon keeps its own. The buffers are in memory only, and they go when the daemon stops. [paste_buffers] in config.toml sets how many to keep. The commands tuios list-buffers, show-buffer, set-buffer, delete-buffer and paste-buffer read and change the same buffers, and so does tmux under the tmux shim.

Copies between machines

Ctrl+B u opens the Copies panel. It shows one row for each copy between machines, the newest first. The dock item transfers opens it too, with a click. The command palette row is "Copies between machines".

KeyActionWhat it does
j k Down Uptransfers_down transfers_upMove the cursor
ptransfers_pausePause the copy, or go on with it
xtransfers_cancelCancel the copy. tuios asks first
rtransfers_retryTry a failed copy again from where it stopped
ctransfers_clearRemove the copies that ended
Entertransfers_answerAnswer a copy that waits for an answer
Esc qtransfers_closeClose the panel

The keys are in [keybindings.transfers]. The panel key is prefix_transfers in [keybindings.prefix_mode].

A copy waits for an answer when a file is there on the other machine and the copy was started with conflict = "ask". The dock says 1 copy asks. Press Enter on the row to choose Replace, Keep both or Skip. Press Space to use the answer for the other files of the copy. tuios does not open this question by itself, because tuios cp in a pane asks the same question there.

When you drop files on a pane whose program runs on another machine, the terminal pastes their paths. tuios asks whether to send the files to that machine. Send copies them to a private drop folder there. When the copy is checked, tuios pastes the path on that machine. Paste the text pastes the paths as they are. A paste into a pane on this machine is not changed.

Screenshots over a panel

Ctrl+B C opens capture mode over any panel or overlay too: the agents view, the review, the palette, settings, a menu or a dialog. The panel stays open and is part of the capture. The panes are under it, so capture mode does not offer one: enter, f or a click takes the whole screen, and a drag takes a region of it.

While a panel is open, the leader is held for one key. If that key is not the screenshot key, the panel gets the leader and then the key, in that order, as it did before. Copy mode and the scrollback browser keep the leader at once, because both page up on ctrl+b.

Settings

, in window-management mode, or ctrl+b ,, opens the settings page. It reopens on the tab, row and search it was left on.

KeysWhat it does
left, right, h, lChange the row's value
enter, spaceToggle, cycle, or open the row's picker or editor
tab, shift+tab, [, ]Next or previous tab, wrapping
1 to 9Go to that tab
/, or a letter the page does not useSearch every tab
backspace, deleteReset the row to its default
ctrl+zUndo the last change made on the page
esc, qClose

A row changed from its default carries a dot after its name, and its description says what the default is.

The search ranks every row of every tab by its name, its config key, its value and its description, with the letters that matched lit, and each result names its tab. In the search, up and down move through the results, left, right and enter act on the row where it is, tab goes to the row on its own tab, delete resets it, and esc clears the search and puts the page back where it was; a second esc closes it. The command palette reaches the same rows by name (settings: pane background), and tuios list-options --search runs the same search from a shell.

tuios lives only at tuios.dev and github.com/Gaurav-Gosain/tuios. tuios has no X or Twitter account. An account that offers a tuios token or presale is not this project.

On this page