Control Protocol

The TUIOS daemon speaks a line-oriented JSON protocol on its Unix socket. It is meant for scripts, automation, and programs that drive TUIOS without a terminal attached. Every request is one line of JSON, and every response is one line of JSON.

This is a separate surface from the remote control CLI commands. Those commands are convenient for shell one-liners; the verb protocol is what you want when you need structured errors, blocking waits, or an event stream.

Connecting

The verb protocol shares the daemon socket with the binary client protocol. The daemon decides which one you are speaking by looking at the first byte you send: a line beginning with { (or leading whitespace) is a verb-protocol client, and a binary client's first byte is the high byte of a length prefix, which is never {.

That means there is no separate port, no handshake negotiation, and no special socket. Connect to the socket and write JSON.

# Linux, when XDG_RUNTIME_DIR is set
echo '{"id":1,"verb":"list-sessions"}' | socat - UNIX-CONNECT:"$XDG_RUNTIME_DIR/tuios/tuios.sock"

See Sessions for the socket path on each platform.

Discovering the protocol

You do not have to read this page to use the protocol. The daemon describes itself:

# Every verb, its parameters, and example requests
tuios list-verbs

# Just one verb
tuios list-verbs capture-pane

list-verbs reports the protocol version, every verb and parameter, the accepted values for each constrained parameter, the stable error codes, and the request and response envelope shapes. The same information is available over the socket as the list-verbs verb.

Envelopes

A request carries an id, a verb, and optional params:

{"id":1,"verb":"send-keys","params":{"session":"work","keys":"ls,Enter"}}

A successful response echoes the id and carries a result. An error response carries an error object with a stable code, a human-readable message, and often a hint naming what would resolve the failure: the closest verb spelling, the parameter that was wrong, or the set of values that do exist.

Existing consumers that read only code and message are unaffected by hints, which are all optional.

Verbs

Seventeen verbs are implemented.

Discovery and handshake

Sessions and windows

Input and output

Options

Events and waiting

Capturing panes

capture-pane reads one of two buffers, named by source:

• visible (default) captures the visible screen.
• recent captures recent scrollback.

Set styled to include ANSI styling. Restrict the output with lines to keep the last N lines, or with start and end for a 1-based inclusive range. When start or end is given, lines is ignored.

{"id":1,"verb":"capture-pane","params":{"session":"work","source":"recent","lines":50}}

Waiting for conditions

wait-for replaces the poll-and-capture loops that scripts otherwise write. It blocks until the condition matches or the timeout expires.

idle defaults to 500 ms and timeout defaults to 30000 ms. pattern is required by window-output. A wait that expires fails with the timeout error code rather than returning a non-match result.

{"id":1,"verb":"wait-for","params":{"condition":"window-output","session":"work","pattern":"done","timeout":10000}}

Event stream

subscribe turns the connection into an event stream. Events are delivered from the moment of subscription and there is no backfill, so subscribe before you trigger the thing you want to observe.

Filter with types to receive only some events, and set queue to change how many events buffer before the stream marks a gap (default 256). If a consumer falls behind far enough to overflow that buffer, the stream emits a gap event rather than silently dropping events.

The event types are:

window-created, window-closed, window-exit, window-retitled, window-focused, window-moved, window-minimized, window-restored, workspace-switched, output, bell, mode-changed, session-created, session-closed, and gap.

{"id":1,"verb":"subscribe","params":{"session":"work","types":["window-created","window-closed"]}}

Error codes

Codes are stable and safe to branch on.

Verbs that need an attached client

Some work cannot happen without a renderer. A verb that routes to the attached TUI returns needs_client when the session is headless, rather than appearing to succeed. If you are driving a session created with tuios new --detach, expect this for anything that depends on the client's view of the world, and attach a client if you need it.

Known gaps

Written plainly, because scripting against a wrong schema is expensive:

• capture-pane accepts scrollback and ansi as aliases for convenience, but neither alias is declared in the schema list-verbs reports. A caller generating code from the schema will not discover them.
• wait-for accepts a source parameter that is likewise absent from its advertised schema.
• Both mean the advertised parameter lists are narrower than what the daemon accepts. Nothing the schema advertises is wrong, so code written from list-verbs works; it just does not cover everything.

Related