Protocol Verbs

Input and output

Input and output: part of the Protocol Verbs of TUIOS.

This page is one part of docs/protocol-verbs.md of the tuios repository. The Protocol Verbs page lists every part.

capture-pane Added in v0.8.0

Capture a pane's content. On a window that shows a TML surface, the content is the surface drawn at the window's size, with its state and the open tab, and the result adds surface.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
windowstringWindow id or name. Omit to target the focused window.
sourcestringvisibleWhich buffer to capture. last-command-output is what the pane's last finished command printed, read between its shell's OSC 133 marks; it is plain text, adds cmdline, exit_code, command_seq and truncated to the result, and fails with no_shell_integration when no command has finished under the marks. One of visible, recent or last-command-output.
styledboolfalseInclude ANSI styling in the captured text.
scrollbackboolfalseOlder spelling of source "recent".
ansiboolfalseOlder spelling of styled.
resolvedboolfalseRewrite ANSI index colours (30-37, 90-97, 40-47, 100-107, 38;5;n<16, 48;5;n<16) to 24-bit RGB so the capture matches what a themed client paints. Indices above 15 and true colour pass through untouched.
palette[]stringxterm defaultsThe 16 hex colours (#rrggbb) the client's theme paints indices 0-15 with, used by resolved captures. Must be exactly 16 entries when present; absent means the xterm defaults.
linesintKeep only the last N lines. Blank rows below the cursor do not count. Ignored when start or end is given. With commands, the most lines to keep in total (default 2000).
commandsintCapture the last N shell commands, found by the pane's OSC 133 marks, from the scrollback. Each command runs from its prompt to the next prompt. When the total is over lines, the longest outputs lose their middle, and one line says how many lines were left out. A pane with no marks, or on the alternate screen, gives the last lines lines instead, with command_marks false. Takes no start, end or unwrap.
startint1-based inclusive first line of the region to keep.
endint1-based inclusive last line of the region to keep.
unwrapboolfalseJoin the rows the terminal wrapped because a line was longer than the pane, so each line is one line as the program wrote it. A row that ends with a newline stays a line of its own. lines, start and end then count the joined lines.
trimboolfalseDrop the blank lines at the end of the capture, which are the empty rows below the cursor. lines, start and end then count what is left.
Result fieldTypeDescription
contentstringThe captured text, one line per row, or per line with unwrap.
unwrappedboolTrue when unwrap joined the wrapped rows. Omitted otherwise.
trimmedboolTrue when trim dropped the blank lines at the end. Omitted otherwise.
lines_omittedintWith lines: how many older lines the capture left out, 0 when it kept them all. With commands: how many lines it cut from the middle of the outputs. Omitted without lines or commands, and with start or end.
command_marksboolWith commands: true when the marks cut the capture into commands, false when it gave the last lines lines instead.
commands[]objectWith commands and command_marks true: one entry per command captured, oldest first, with lines (kept), lines_omitted, finished, and cmdline and exit_code when the shell reported them.
commands_availableintWith commands and command_marks true: how many commands the scrollback holds under marks.
sourcestringThe buffer captured. One of visible, recent or last-command-output.
styledboolWhether content carries ANSI styling.
resolvedboolWhether index colours were rewritten to 24-bit RGB.
history_rowsintHow many scrollback lines the pane holds above its screen. A recent capture of more lines than this plus the screen has nothing older to show. Not on a last-command-output capture.
revisionintA number that grows each time the pane's content can change: output reaches it, or it is resized. Two captures of one source with one revision have the same content. It counts from 0 again when the daemon restarts. Not on a last-command-output capture.
boot_idstringThe daemon start the revision belongs to, the boot_id of subscribe and list-attention. Compare revisions only when boot_id is the same.
{"id":1,"verb":"capture-pane","params":{"session":"work","source":"recent","lines":50}}
{"id":1,"verb":"capture-pane","params":{"session":"work","source":"recent","unwrap":true,"trim":true}}

list-keys Added in v0.8.3

List the send-keys key grammar: every key name with its aliases, the modifiers and their spellings, and the other kinds of token. The list is closed: a key name or modifier missing from it is refused.

No params.

Result fieldTypeDescription
keys[]objectEvery named key, as {name, aliases}. name is the canonical spelling. aliases are the other spellings, lower case, since names are matched without case, hyphens or underscores.
modifiers[]objectEvery modifier, as {name, spellings}. super reaches only an attached client's window manager, never a pane.
ctrl_characters[]stringThe characters other than letters that ctrl combines with.
escape_prefixes[]stringThe prefixes that make a token an escape sequence, sent as it is.
prefix_tokenstringThe token for the leader key.
separators[]stringThe characters keys are split on.
max_repeatintThe largest repeat send-keys takes.
{"id":1,"verb":"list-keys"}

paste-image Added in v0.8.3

Write an image the person pasted to the machine where a pane's process runs, and answer with the path there. For a pane on another machine the image crosses the link and is written there. The client pastes the path into the pane as text. Only the person's attached client may call it: it needs that client's attach nonce and is refused from inside a pane. The file is readable by its owner only and is deleted after an hour, or when the daemon stops.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
windowstringThe window to paste into. Omit for the focused window.
contentstringThe image, base64. PNG, JPEG, GIF, WebP, BMP or TIFF, at most 8 MB decoded. The type is read from the bytes.
human_noncestringThe attach nonce of the person's client, attached to this session.
Result fieldTypeDescription
pathstringThe image's path on the machine where the pane's process runs.
hoststringThe machine the image was written to, when it is not this one.
windowstringThe window the path is for.
bytesintHow many bytes were written.
{"id":1,"verb":"paste-image","params":{"session":"work","window":"a1b2","content":"iVBORw0KGgo=","human_nonce":"<from the attach reply>"}}

run Added in v0.8.0

Type one command line at a pane's shell prompt, wait for the shell to report it finished, and return its exit code and output. Needs a shell that marks its commands with OSC 133, and refuses with no_shell_integration one that marks only its prompts; refuses with not_at_prompt when a command, or another run, is already running there. From a pane, window is required.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
windowstringWindow id or name. Omit to target the focused window.
commandstringThe command line, typed as a paste and submitted with Enter. One line, no control characters: join several commands with ; or &&.
timeoutint30000Milliseconds to wait for the command to finish before failing with the timeout code. The command keeps running after a timeout.
linesintKeep only the last N lines of the output.
Result fieldTypeDescription
exit_codeintThe status the shell reported. Omitted when the shell sent none, which a bash integration does on ctrl+c.
outputstringWhat the command printed, as plain text, read from the pane between the shell's marks. At most the last 256 KiB.
truncatedboolTrue when the output was cut, or its start had already left the scrollback.
cmdlinestringThe command line as the shell showed it, cut to 512 bytes with likely secrets masked.
duration_msintHow long the command ran, from the shell's marks.
command_seqintHow many commands the pane has finished, this one included.
windowstringId of the pane the command ran in.
sessionstringThe session the pane is in.
{"id":1,"verb":"run","params":{"session":"work","window":"build","command":"go test ./...","timeout":600000}}
{"id":1,"verb":"run","params":{"session":"work","window":"build","command":"make lint","lines":40}}

send-keys Added in v0.8.0

Send keys to a window's program: Up, PageDown, ctrl+c. With a window they go to that window's terminal; without one, to an attached client (the window manager) or else the focused window. From a pane, window is required.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
windowstringWindow id or name. Omit to target the focused window.
keysstringKeys split on spaces and commas, e.g. "Down Down PageDown" or "ctrl+c". A key is a name (Enter Tab BTab Space Comma Escape Backspace Up Down Right Left Home End PageUp PageDown Insert Delete F1-F12, case-insensitive, also as arrow-up, KEY_UP, <Up>, PgDn), one character, a name or character after ctrl+, alt+ or shift+ (or tmux C-, M-, S-), an escape sequence written \e[A, or PREFIX for the leader key. list-keys returns the full list.
literalboolfalseSend the keys to the PTY without parsing them as key names.
rawboolfalseTreat every character as its own key instead of splitting on spaces and commas.
repeatint1Send the whole sequence this many times, 1 to 1000.
allow_blockedboolfalseFrom a pane, type into a pane on needs_input instead of refusing with agent_blocked. What is typed then answers its prompt, which also needs the respond grant. The person, outside every pane, is not held.
Result fieldTypeDescription
sent_tostringwindow when the keys were written to a window's terminal, client when an attached client took them as the person's keys.
window_idstringThe window the keys were written to, when sent_to is window.
windowstringThat window's name, or its title when it has no name.
keysintHow many keys were sent, counting repeats.
{"id":1,"verb":"send-keys","params":{"session":"work","window":"review","keys":"Down","repeat":5}}
{"id":1,"verb":"send-keys","params":{"session":"work","window":"build","keys":"ctrl+c"}}

send-text Added in v0.8.0

Send literal text to a window's PTY. From a pane, window is required.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
windowstringWindow id or name. Omit to target the focused window.
textstringText written verbatim to the PTY.
pasteboolfalseSend the text as a paste. Control characters other than tab, line feed and carriage return are removed. The text is wrapped in the bracketed paste delimiters when the program in the pane turned bracketed paste on.
submitboolfalsePaste the text and submit it with the Enter key of the harness in the pane, after a short wait for the paste to be taken in, as ask-agent does.
allow_blockedboolfalseFrom a pane, type into a pane on needs_input instead of refusing with agent_blocked. What is typed then answers its prompt, which also needs the respond grant. The person, outside every pane, is not held.
{"id":1,"verb":"send-text","params":{"session":"work","text":"echo hi\n"}}
{"id":1,"verb":"send-text","params":{"session":"work","window":"build","text":"line one\nline two","paste":true}}
{"id":1,"verb":"send-text","params":{"session":"work","text":"Fix the test\nthen commit","submit":true}}

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