CLI Reference

tuios [flags]              # start or attach to TUIOS
tuios <command> [flags]    # run a command

Every command accepts --help, and its output always matches your build. tuios help <command> does the same.

Conventions

Most commands that act on a running session share these flags:

• -s, --session <name>: the target session. The default is the most recently active one.
• -w, --window <target>: the target window. The default is the focused one.
• --json: print JSON instead of a table.

A window target is matched in this order, and the first match wins:

1. The full window ID
2. The index list-windows prints
3. A unique ID prefix, such as the 8 characters list-windows shows
4. The custom name, then the window title

An index or ID therefore beats a window that happens to be named 2.

Commands that talk to the daemon exit 3 when no daemon is running. See Exit codes.

Global flags

Three flags work on every command:

• --debug: enable debug logging.
• --cpuprofile <file>: write a CPU profile.
• --pprof <addr>: serve net/http/pprof on this address, for example localhost:6060. The server has no authentication, so bind it to localhost.

These work only on a bare tuios:

• --standalone: run a session without the daemon, for this run. TUIOS_NO_DAEMON=1 does the same for a whole shell.
• --skill: print the agent skill for driving TUIOS from a pane, then exit.
• --list-themes: print every theme id, then exit.
• --preview-theme <name>: print a theme's 16 ANSI colours, then exit.
• -v, --version: print the version, the VT backend (pure-Go or ghostty), commit, build date and builder. There is no version subcommand.

tuios --theme $(tuios --list-themes | fzf --preview 'tuios --preview-theme {}')
tuios --skill > ~/.claude/skills/tuios/SKILL.md

A bare tuios attaches to a daemon session, because startup.daemon defaults to true. See The startup table.

Interface flags

These flags change how the TUI looks for one run. They are accepted by tuios, new, attach, ssh and tape play. Any other command rejects them. Each one overrides a config option.

Commands

Aliases: attach is a, new is n, ls is list-sessions, resurrect is restore, keybinds is keys or kb, and hosts remove is hosts rm.

Sessions

A session lives in the daemon and keeps running after you detach (Ctrl+B d). The daemon starts on its own when a command needs it. See Sessions.

new

Create a session and attach to it. Alias: n.

tuios new [session-name] [flags]

• -d, --detach: create the session without attaching.
• --host <name>: create the session on a machine from the [hosts] table.
• --ssh: with --host, run ssh to the host and use its own tuios instead of attaching here.
• --global: create a global session, which can hold panes from more than one machine.
• --hold: after a failure, wait for Enter before exiting.
• The interface flags.

tuios new                          # auto-generated name
tuios new work --theme dracula
tuios new build --detach           # headless, for scripting
tuios new --host buildbox ci -d    # on another machine

A detached session gets one window and works at once with send-keys, run-command and capture-pane. It is 80x24 until a client attaches. See Headless Sessions.

attach

Attach to a session. Alias: a.

tuios attach [session-name] [flags]

• -c, --create: create the session if it does not exist.
• --host <name>: attach to a session on a machine from the [hosts] table.
• --ssh: with --host, run ssh to the host and use its own tuios. Press the prefix twice to send it to the remote client.
• --hold: after a failure, wait for Enter before exiting.
• The interface flags.

tuios attach                  # the most recent session
tuios attach work -c          # attach, or create it
tuios attach --host build api # the session api on the machine build

With no name, attach opens the most recent session. If the daemon is not running, it starts, restores the sessions saved on disk, and opens one of them. With nothing saved, it opens a new session. A name that matches no session is an error unless you pass -c.

ls

List sessions. Alias: list-sessions.

tuios ls [flags]

• --json: print JSON.
• --all-hosts: also list every machine in the [hosts] table.
• --host <name>: list one machine. local means this one.

The table shows name, window count, status, creation time and last activity. --json prints a bare array:

[
  {
    "name": "work",
    "id": "04623592-051c-49d5-9a29-69a2e2ccdb33",
    "created": 1790101795,
    "last_active": 1790101795,
    "window_count": 1,
    "attached": false,
    "width": 80,
    "height": 24,
    "windows": [
      { "id": "bef3bdc3-2b99-4bf5-9499-b1d3aabb7f9c", "title": "Terminal bef3bdc3", "workspace": 1 }
    ],
    "current_workspace": 1,
    "dir": "tuios",
    "branch": "main"
  }
]

• created and last_active are Unix seconds.
• dir is the base name of the focused pane's directory (~ for home). branch is its git branch. Both are omitted when unknown.
• display_name, accent and restored appear only when set.

With no daemon running, ls lists the sessions saved on disk, marks each saved ("saved": true in JSON), and exits 3.

With --all-hosts or --host, the JSON is an object with a hosts array. Each entry has host, status and sessions. A host that does not answer gets a row saying so and does not fail the command.

resurrect

Restore a session saved on disk. Alias: restore.

tuios resurrect               # list what can be restored
tuios resurrect work          # restore it and attach

The daemon restores saved sessions when it starts, so you need this only after tuios daemon --no-restore, or to bring back one session on demand. Each window gets a fresh shell in its saved directory. Running programs and scrollback are not restored. See Session Resurrection.

kill-session

Close every window in a session and disconnect its clients.

tuios kill-session <session-name>

kill-server

Stop the daemon and every session in it.

tuios kill-server

The command waits until the daemon has saved every session and removed its socket, so you can start a new daemon as soon as it returns. It fails if the daemon has not stopped within 10 seconds. Sessions are restored when the next daemon starts. To start clean, use tuios daemon --no-restore. With no daemon running, it removes a stale socket if there is one and exits 0.

daemon

Run the daemon in the foreground, for debugging.

tuios daemon [flags]

• --log-level <level>: off (default), errors, basic, messages (all protocol messages except PTY I/O), verbose (including PTY I/O), or trace (full hex dumps).
• --no-restore: do not restore saved sessions on start.

tuios daemon --log-level messages

tuios start-server starts the daemon in the background with no session. It is hidden from --help because commands start the daemon on their own.

logs

Print the daemon's log.

tuios logs [flags]

• -n, --lines <n>: entries to show. Default 50. 0 shows all.
• --all: show every stored entry.
• -f, --follow: keep printing new entries.
• --clear: empty the log after printing it.

The daemon keeps the last 1000 entries in memory. It also appends errors and basic events to $XDG_STATE_HOME/tuios/daemon.log, so a crash leaves a record. To log more, run tuios set-config daemon.log_level messages. The levels verbose and trace also record pane content, titles and paths.

Worktrees

worktree

Run a session in a git worktree. The rail groups these sessions under their repository and labels each with its branch.

tuios worktree new <branch> [flags]
tuios worktree ls [flags]
tuios worktree rm <session> [flags]
tuios worktree diff <session> [--stat]

worktree new creates a worktree and a session in it. A branch that does not exist is created from --base, or from HEAD. The session is named <repo>-<branch>, with slashes turned into hyphens. Worktrees go under $XDG_DATA_HOME/tuios/worktrees/<repo>/<branch>.

• --repo <dir>: a directory inside the repository. Default: the current directory.
• --base <ref>: the ref a new branch starts from. Default: HEAD.
• --name <session>: the session name.
• --agent <cli>: start an agent CLI instead of a shell, such as claude, codex or gemini.
• -d, --detach: do not attach.
• --json: print JSON.

worktree ls lists worktree sessions with their repository, branch, agent state, uncommitted changes and fan prompt status. A row marked gone is a session whose worktree was deleted. Filter with --repo <name> or --group <stem>.

worktree rm runs git worktree remove and kills the session. It refuses a worktree with uncommitted changes and removes nothing. --stash keeps the changes in git stash, and --force discards them. --keep-session leaves the session running. The branch is never deleted.

worktree diff prints the commits the session made on top of its base, then its uncommitted changes, then its untracked files. --stat prints the summary form.

tuios worktree new feat/retry --base main --agent claude --detach
tuios worktree ls
tuios worktree rm api-feat-retry --stash

fan

Start the same prompt in several agents, each in its own worktree.

tuios fan <count> <prompt> --agent <cli> [flags]
tuios fan keep <session> [--stash | --force]

• --agent <cli>: the agent to run: claude, codex or gemini. Required.
• --base <ref>: the ref every branch starts from. Default: HEAD.
• --name <stem>: the branch stem. Default: fan/ and the first words of the prompt.
• --repo <dir>: a directory inside the repository.
• --wait: return only when every prompt is sent or given up on.
• --json: print JSON.

The branches are the stem, then stem-2, stem-3 and so on. Each prompt is typed once its agent is ready. tuios worktree ls --group <stem> shows whether each one was sent.

fan keep keeps one session and removes the others with the same stem, the way worktree rm does. A sibling with uncommitted changes is left in place unless you pass --stash or --force.

tuios fan 3 --agent claude 'Add a retry with backoff to the HTTP client.'
tuios worktree diff api-fan-add-a-retry-with-2
tuios fan keep api-fan-add-a-retry-with-2 --stash

Remote control commands

The commands below drive a running session from a script or another pane. They are a thin layer over the daemon's JSON control protocol. For more than a few calls, or to get structured errors and blocking waits, use the protocol directly. tuios --skill prints a guide to this surface for agents.

Most of them work on a detached session. The ones that need an attached client say so.

Windows and workspaces

new-window

Open a window and print its ID and name.

tuios new-window [name] [command...] [flags]

• --workspace <n>: the workspace to open it on. Default: the current one.
• --cwd <dir>: the starting directory. Default: the daemon's.
• --no-focus: leave the focus where it is.
• --host <name>: run the window's process on a machine from the [hosts] table. The window still belongs to this session.
• --json: print JSON.

Words after the name are a command the window runs instead of a shell. They are passed as they are, with no shell in between. Put -- before a command that has flags of its own, or tuios reads them as its own flags. The window closes when the command exits.

tuios new-window build                      # prints: e0657732  build
tuios new-window top htop                   # run htop with no shell
tuios new-window logs -- tail -f /var/log/system.log
tuios new-window tests --workspace 2 --cwd /src/api --no-focus
tuios new-window --json | jq -r .window_id

split-window

Split a pane and print the new pane's ID. Needs an attached client with tiling on.

tuios split-window <horizontal|vertical> [flags]

• -w, --window <target>: the pane to split.
• --name <name>: a name for the new pane.
• --json: print JSON.

popup

Run a command in a floating pane over the layout. The pane closes when the command exits. Needs an attached client.

tuios popup [flags] -- <command> [args...]

• --width <size>: cells, or a percentage of the pane area. Default 80%.
• --height <size>: cells or a percentage. Default 60%.
• --name <name>, --cwd <dir>, --workspace <n>, --json.

The size flags have no short form, because -w means window and -h means help. The popup draws on its own screen, so its output does not come back to this command. To keep a result, write it to a file or send it to another pane.

tuios popup -- sh -c 'ls | fzf > /tmp/pick'
tuios popup -- sh -c 'tuios send-text -w main "$(ls | fzf)"'
tuios popup --width 90% --height 80% -- htop

focus-window

Move the focus and print the pane that has it. Pass exactly one of a window, --relative or --direction.

tuios focus-window build
tuios focus-window --relative next     # next or prev on this workspace
tuios focus-window --direction left    # left, right, up or down

Naming a window switches to its workspace. --direction needs an attached client.

move-window

Move a window to another workspace.

tuios move-window <workspace> [-w <target>] [--follow] [--json]

--follow switches to that workspace after the move.

set-window

Rename, minimize or restore a window. Pass only the flags you want to change.

tuios set-window --name "api tests"
tuios set-window -w build --name ""      # clear the custom name
tuios set-window -w build --minimize
tuios set-window -w build --restore

set-layout

Turn tiling on or off, reset split ratios, or flip the focused split. Needs an attached client.

tuios set-layout --tiling true
tuios set-layout --equalize
tuios set-layout --rotate

Workspaces and labels

tuios set-workspace-name 2 review
tuios list-workspaces --json | jq '.workspaces[] | select(.window_count == 0)'

Input and output

send-keys

Send keystrokes to a session.

tuios send-keys <keys> [flags]

• -w, --window <target>: the target window.
• -l, --literal: write the text to the pane's PTY with no key parsing.
• -r, --raw: send each character as a key. Do not split on spaces or commas.

Without --literal, keys go to TUIOS first, so window-mode bindings and the prefix work.

• Single keys: i, Enter, Escape, Space, Tab, Backspace, Delete, arrows (Up and so on), Home, End, PageUp, PageDown, F1 to F12.
• Chords: ctrl+b, alt+1, shift+Enter. Not case sensitive. Modifiers are ctrl, alt, shift, super and meta.
• Sequences: separate keys with a space or a comma: "ctrl+b q" or "ctrl+b,q".
• PREFIX and $PREFIX expand to your leader key. In bash and zsh, use single quotes so the shell does not expand $PREFIX first: tuios send-keys 'PREFIX q'.

tuios send-keys i                          # enter terminal mode
tuios send-keys 'PREFIX d'                 # detach the attached client
tuios send-keys -w build --literal --raw "make test"
tuios send-keys -w build Enter

send-text

Write text to a pane exactly as given. Nothing is parsed. End the text with a newline to run it.

tuios send-text -w build 'go build ./...
'
tuios send-text -w build 'partial input'         # type without running
printf 'go test ./...\n' | xargs -0 tuios send-text -w build

capture-pane

Print a pane's content.

tuios capture-pane [flags]

• -w, --window <target>: the pane.
• -S, --scrollback: include the scrollback, not only the screen.
• --lines <n>: keep only the last n lines. 0 keeps all.
• --ansi: keep colour and style escape codes.
• --resolved: rewrite indexed colours to 24-bit RGB, so the capture matches what a themed client draws.
• --palette <colours>: 16 comma-separated #rrggbb colours for --resolved. Default: the xterm colours.

tuios capture-pane -w build --scrollback --lines 40   # the tail of a build
tuios capture-pane --ansi > pane.txt

--lines counts from the last line with content, so blank rows below the cursor do not count.

screenshot

Render a pane to an image file and print its path. The daemon renders it, so this works on a detached session.

tuios screenshot [flags]

• -w, --window <target>: the pane.
• -f, --format <fmt>: png, svg, ansi, html or txt.
• --frame <style>: window, plain or none.
• --theme <name>: render in this theme instead of the session's.
• -o, --out <path>: write here instead of a generated name under screenshot.directory.
• -S, --scrollback: put the scrollback above the screen.
• --lines <n>: limit the scrollback to the last n rows.
• --cursor: draw the cursor.
• --copy, --no-copy: try, or do not try, to copy the image to the clipboard.
• --json: print JSON with path, host, format, cols, rows, bytes, copied and warnings.

tuios screenshot -s work -w build
tuios screenshot --format svg --out demo.svg
tuios screenshot --theme catppuccin_mocha

The picture is drawn from the pane's cells, so colours, styles and links are exact. png and svg include the frame. ansi and txt do not. The [screenshot] config table sets the defaults.

With no theme set, basic colours use the xterm defaults, because only your terminal knows its real palette. The result warns about this. Pass --theme to render in a named palette.

Region and full-screen captures need an attached client: press Ctrl+B C in the TUI.

wait-for

Block until a condition matches, then exit 0. The daemon watches its own events, so there is no polling.

tuios wait-for <condition> [flags]

• --pattern <regexp>: required by window-output.
• --until <states>: comma-separated states, required by agent-state.
• --idle <ms>: silence that counts as idle. Default 500.
• --thread <id>: for agent-message, only this thread.
• --timeout <ms>: give up after this long and exit non-zero. Default 30000.
• --json: print JSON.

tuios wait-for window-output -w build --pattern 'BUILD_OK' --timeout 120000
tuios wait-for window-idle -w build --idle 2000
tuios wait-for agent-state -s work --until needs_input

Inspection

These commands read the daemon's state and work with no client attached.

list-windows

List the windows in a session.

tuios list-windows [--json]

The table shows index, ID prefix, name, workspace, size and agent state. * marks the focused window. The index and the ID prefix both work with -w.

{
  "success": true,
  "message": "command executed",
  "windows": [
    {
      "window_id": "15ff15b6-472e-4b22-b5e6-a709d82ded31",
      "index": 1,
      "title": "dev",
      "custom_name": "dev",
      "display_name": "dev",
      "workspace": 1,
      "focused": false,
      "minimized": false,
      "x": 0,
      "y": 0,
      "width": 80,
      "height": 24,
      "pty_id": "3f42acd9-5c9f-4f93-a2dd-c7af358cae33",
      "agent_state": "none"
    }
  ],
  "total": 3,
  "focused_index": 2,
  "focused_window_id": "e0657732-bf81-4636-8b24-6052f7ad76fe",
  "current_workspace": 1,
  "workspace_windows": [3, 0, 0, 0, 0, 0, 0, 0, 0]
}

• The ID field is window_id, and the focused window is focused_window_id.
• custom_name appears only on renamed windows. display_name is always present.
• cwd appears when the shell has reported its directory.
• workspace_windows counts windows per workspace, starting with workspace 1.

get-window

Print one window. With no argument, the focused window.

tuios get-window [id-or-name] [--json]

The JSON is the same window object as in list-windows, merged into the top level next to success and message. There is no cursor position, shell PID or scrollback size. To read the screen, use capture-pane.

session-info

Print the session's state.

tuios session-info [--json]

{
  "success": true,
  "message": "command executed",
  "session_name": "work",
  "session_id": "04623592-051c-49d5-9a29-69a2e2ccdb33",
  "display_name": "",
  "accent": "",
  "mode": "unknown",
  "current_workspace": 1,
  "num_workspaces": 9,
  "workspace_names": {},
  "workspace_order": null,
  "window_count": 3,
  "tiling_mode": "floating",
  "layout_mode": "unknown",
  "master_ratio": 0.5,
  "width": 80,
  "height": 24,
  "tui_attached": false
}

• tiling_mode is only tiling or floating. The layout name, such as bsp, is layout_mode, which is unknown when none is set.
• mode is always unknown. Do not use it.
• The theme and other options are not here. Read them with get-config.

list-verbs

List the control protocol's verbs, with parameters, examples, error codes and the protocol version.

tuios list-verbs                 # every verb
tuios list-verbs capture-pane    # one verb
tuios list-verbs --json

These are kebab-case protocol verbs. They are a different set from the PascalCase run-command verbs. See Control Protocol.

run-command

Run one tape command in a session. Tape commands use PascalCase names.

tuios run-command <command> [args...] [flags]

• --list: print every command.
• --json: print the result as JSON.

Some commands need an attached client, such as SetDockbarPosition. On a detached session they fail with a message saying so.

--json merges the command's result into the top level:

{ "success": true, "message": "command executed", "window_id": "459a7fc9-a1fd-4770-86ac-0bc60b9598b9", "name": "dev2" }

On failure the object is {"success": false, "message": "..."} and the exit code is 1. Check .success, not the message text.

tuios run-command --json NewWindow dev | jq -r .window_id
tuios run-command EnableTiling
tuios run-command -s work SwitchWorkspace 2

In scripts, prefer EnableTiling over ToggleTiling, so running the script twice gives the same result.

Configuration

config

tuios config path     # print the config file path
tuios config edit     # open it in $EDITOR
tuios config reset    # overwrite it with the defaults

config edit uses $EDITOR, then $VISUAL, then the first of vim, vi, nano and emacs it finds. config reset asks first, and replaces the file including your keybindings.

set-config

Change an option in a running session. The config file is not changed.

tuios set-config <path> <value>

tuios set-config appearance.border_style thick
tuios set-config appearance.sidebar.enabled true
tuios set-config daemon.log_level messages

A path is the option's dotted name, such as screenshot.format. An [appearance] option also answers to its bare name, so border_style works. An unknown path or value is refused, and the error lists what is accepted. Use list-options to find paths.

set-config cannot change [keybindings], [hooks], [hosts], [tailscale] or the [dock] lists. Edit the file for those.

get-config

Read an option from a running session.

tuios get-config border_style
tuios get-config appearance.sidebar.position --json

An option with no session override reads as its default. --json adds source (session or default) and default.

list-options

List every path set-config accepts, with type, default, accepted values and a description.

tuios list-options                        # everything
tuios list-options --section sidebar      # one group
tuios list-options appearance.sidebar.    # a path prefix
tuios list-options --json | jq -r '.options[].path'

A session override is shown next to the default. Each JSON row has path, type, section, description and default, plus accepted, min, max, deprecated and session_value when they apply.

list-themes

List themes, or show one theme's colours and their contrast against its background.

tuios list-themes --filter catppuccin
tuios list-themes catppuccin_mocha
tuios list-themes --json | jq -r .active

It reads the themes directory again on every call, so a new theme file shows up at once.

import-theme

Convert a kitty, Ghostty, Alacritty or WezTerm colour scheme into a TUIOS theme file.

tuios import-theme ~/.config/kitty/current-theme.conf
tuios import-theme ~/gruvbox.toml --name gruvbox
tuios set-config appearance.theme gruvbox

The format is detected from the content. Colours the scheme does not set use the xterm defaults. --name sets the theme id. The theme can be selected at once.

list-glyphs

List glyph sets, or show what one set draws, role by role.

tuios list-glyphs
tuios list-glyphs heavy
tuios list-glyphs mine --json | jq -r '.problems[]?'

See Glyph sets.

keybinds

Inspect and change keybindings. Aliases: keys, kb.

doctor and explain take --json and --guest <program>. Each finding in doctor has an evidence tier: certain (TUIOS routing), observed (read from a pane) or reference (a list of common program defaults).

unbind and free write the action as an empty list, so the default does not come back at the next load. free cannot take the leader key, which you move with keybindings.leader_key, or the few keys the input path reads directly. It says so instead of reporting success.

tuios keybinds explain alt+left
tuios keybinds free alt+left
tuios keybinds unbind close_window w

See Keybindings.

Dock and hooks

list-dock-components

List the dock's components in draw order: side, source (builtin or custom), refresh mode, current text, and what the command last did. Needs an attached client.

tuios list-dock-components
tuios list-dock-components --json | jq '.components[] | select(.source=="custom")'

A component whose command fails is hidden from the dock. This command shows its exit code and error.

refresh-dock

Run a dock component again now, whatever its refresh mode. With no name, run every component. It also clears a component that gave up after repeated failures.

tuios refresh-dock agents

Call it from a hook to update a cell when something changes:

[hooks]
after-agent-state = "tuios refresh-dock agents"

list-hooks

List every hook in your config and what it last did: run count, last exit code, last run time and last error.

tuios list-hooks
tuios list-hooks --event after-agent-state
tuios list-hooks --json | jq '.hooks[] | select(.last_error != "")'

Zero runs means the event never happened. Check the event name. The SIDE column says which process runs the hook. Client-side hooks are listed only while a client is attached. See Hooks.

Agents

Panes running a coding agent can find each other, report state and exchange messages.

list-agents

List the panes identified as agents: state, harness, how it was detected, unread mail, and whether each is ready for a question.

tuios list-agents [flags]

• --all: list every window, not only agents.
• --all-hosts: also list agents on every machine in the [hosts] table.
• --host <name>: list one machine. local means this one.
• --json: print JSON.

tuios list-agents --json | jq -r '.agents[] | select(.state=="needs_input") | .window_id'

The states are needs_input, errored, done, idle and working. The ID and NAME columns work with -w. --session cannot be combined with --all-hosts or --host.

get-agent-state and set-agent-state

Read or report a pane's agent state.

tuios get-agent-state -w build --json
tuios set-agent-state working
tuios set-agent-state needs_input -w build -m "awaiting approval"
tuios set-agent-state none                  # clear it

set-agent-state takes none, working, needs_input, idle, done or errored, and these flags:

• -m, --message <text>: a short note shown with the state.
• --source <source>: report (default), osc, screen or stall.
• --harness <id>: the harness the state is about, such as claude-code.

Sources are ranked in that order, highest first. A source cannot overwrite a state set by a higher-ranked source. A refused report prints why on stderr and changes nothing.

send-agent-message

Leave a message in another pane's inbox, or post a notice to the whole session. It does not type into the pane.

tuios send-agent-message <text> [flags]

• -w, --window <target>: the recipient. Omit it to post a session-wide notice.
• --from <id>: the sending window, normally "$TUIOS_PANE_ID".
• --subject <text>: a one-line summary, up to 120 characters.
• --attach <path>: an absolute path to a file. Repeat up to 8 times.
• --reply-to <id>: answer a message. The reply joins its thread.
• --json: print JSON.

tuios send-agent-message -w build --from "$TUIOS_PANE_ID" 'rebased onto main, please retest'
tuios send-agent-message -w build --from "$TUIOS_PANE_ID" --reply-to 12 'retested, still green'

The recipient has to read its inbox. For an agent that does not, use ask-agent. Messages are kept in memory: they are lost when the daemon stops, and the oldest are dropped when the queue is full.

read-agent-messages

Read messages.

tuios read-agent-messages -w "$TUIOS_PANE_ID" --unread
tuios read-agent-messages --limit 50
tuios read-agent-messages --thread 12

• -w, --window <target>: read this pane's inbox and mark what it returns as read.
• --unread: only unread messages.
• --notices: include session-wide notices in an inbox read.
• --peek: do not mark anything read.
• --thread <id>: one conversation. Any message ID in the thread works.
• --limit <n>: at most this many, newest last. Default 20.

Without -w, it reads every message and marks nothing.

ask-agent

Wait until an agent is not busy, type a question into its pane, wait for it to finish, and print what the pane showed.

tuios ask-agent -w review --from "$TUIOS_PANE_ID" 'does the retry path look right to you?'

• --from <id>: the asking window. Without it there is no loop detection.
• --ready-timeout <ms>: how long to wait for the target to be ready. Default 30000.
• --settle <ms>: for a pane that reports no state, silence that counts as done. Default 2000.
• --timeout <ms>: how long to wait for the answer. Default 300000.
• --lines <n>: cap the reply. Default 200.
• --force: send without waiting for the target to be ready.

It refuses to ask an agent that is already waiting on you, so two agents cannot deadlock on each other.

Diagnosing detection

tuios explain-agent-detect -w build          # what the process detector saw
tuios explain-agent-screen --harness codex   # what a harness's screen rules make of the pane

explain-agent-screen --lines <n> reads that many lines from the bottom.

stash

Copy a file into the session's store, so another agent can read it after you delete yours.

path=$(tuios stash put /tmp/flame.png)
tuios send-agent-message -w review --attach "$path" 'the hot path is in decode'
tuios stash list
tuios stash get -s build:api <stored-path> flame.png

• stash put <file>: the path must be absolute and readable by the daemon's user. Files are stored by content, so the same bytes return the same path. The limits are 16 MB per file and 256 MB per session. When a session is full, the oldest files that no message points at are removed.
• stash list: list stored files, oldest first. USED marks files a message still points at.
• stash get <stored-path> [file]: copy a file from a session on another machine. Up to 8 MB. On this machine, open the stored path directly.

Stored files last until the session is killed or the daemon stops.

Remote hosts

hosts

List the machines in the [hosts] table and the state of each link.

tuios hosts [--json]
tuios hosts add <name> <addr> [flags]
tuios hosts remove <name>
tuios hosts test <name>
tuios hosts tailnet [--json]

The daemon keeps one ssh link to each host.

hosts add writes the host to the config file and tests the link. The daemon opens it at once. Options:

• --command <path>: the tuios binary on the host. By default the link looks on the PATH, then the usual install paths, then a login shell.
• --connect-timeout <s>: seconds one dial may take. Default 10.
• --ssh-option <arg>: one extra ssh argument. Repeat for more.
• --tailnet: take the address from the tailnet machine with that name.

hosts remove (alias rm) removes the host and closes its link. hosts test dials once by itself, with no daemon, and prints what ssh said or where it looked for tuios. hosts tailnet lists the machines on your tailnet and which ones hosts add would offer.

tuios hosts add build gaurav@buildbox
tuios hosts add lab lab-01 --ssh-option -J --ssh-option bastion
tuios hosts test build

The daemon runs ssh with BatchMode on, so it never asks for a password or about a host key. Run ssh to the host once by hand to accept its key.

With a host configured:

• tuios ls --all-hosts and tuios list-agents --host build list it.
• tuios attach --host build api and tuios new --host build open sessions on it in this client, with your local theme, config and prefix. If the link drops, the client reconnects on its own for up to three minutes.
• tuios new-window --host build opens a pane in a local session whose process runs on the host.

See the hosts table.

Tapes and layouts

tape

Run and manage tape scripts.

tape exec

tape exec sends each command of the file to a running daemon session. See Remote Execution. For one command, use run-command.

layout

Manage saved layout templates. Save a layout in the TUI with Ctrl+B L s.

tuios layout export dev > dev.tape
tuios tape exec dev.tape

Other commands

ssh

Serve TUIOS over SSH.

tuios ssh [flags]

• --host <addr>: the address to listen on. Default localhost.
• --port <port>: default 2222.
• --key-path <path>: the host key. Generated if not given.
• --authorized-keys <path>: public keys allowed to connect. Default ~/.config/tuios/authorized_keys, then ~/.ssh/authorized_keys.
• --no-auth: accept every connection without checking keys. Use only on a trusted network.
• --default-session <name>: put every connection in this session.
• --ephemeral: run without the daemon. Nothing persists.
• The interface flags.

Every connection gets a shell on this machine, so the server checks keys:

• With keys, only their holders connect. A key added while the server runs works on the next connection.
• With no keys, on localhost, every connection is accepted with a warning.
• With no keys, on any other address, the server refuses to start unless you pass --no-auth.

A client picks its session in this order: --default-session, then the SSH user name unless it is generic (tuios, root, anonymous), then a command argument (ssh -p 2222 host attach work), then the first session, or a new one.

cat ~/.ssh/id_ed25519.pub >> ~/.config/tuios/authorized_keys
tuios ssh --host 0.0.0.0 --port 2222
ssh -p 2222 work@server

The settings page on an SSH client changes only that session. It never writes the server's config file. The web terminal is a separate binary, tuios-web. See Web Terminal.

update

Replace this binary with the newest release.

tuios update --check        # show what would be installed
tuios update                # install it
tuios update --check --pre  # include prereleases

It only updates a binary installed from a release archive, which is what the install script uses. For Homebrew, a system package, Nix or go install, it refuses and prints the command that updates that install. It also updates tuios-web when it sits next to tuios. Every download is checked against the release checksums.

The running daemon keeps the old version. To switch, detach, run tuios kill-server, and start TUIOS again. Set GITHUB_TOKEN or GH_TOKEN to raise the GitHub API rate limit.

completion

Print a shell completion script.

tuios completion bash > /etc/bash_completion.d/tuios
tuios completion zsh > "${fpath[1]}/_tuios"
tuios completion fish > ~/.config/fish/completions/tuios.fish
tuios completion powershell | Out-String | Invoke-Expression

--no-descriptions leaves out the descriptions.

Scripting examples

Open a build pane and wait for it

#!/bin/bash
set -euo pipefail

tuios new-window build
# printf builds the marker, so the command's echo cannot match it.
tuios send-text -w build 'go build ./... && printf "BUILD_%s\n" OK
'

if tuios wait-for window-output -w build --pattern 'BUILD_OK' --timeout 120000; then
  tuios capture-pane -w build --scrollback --lines 5
else
  tuios capture-pane -w build --scrollback --lines 40
  exit 1
fi

Lay out a workspace

#!/bin/bash
set -euo pipefail

tuios run-command EnableTiling
tuios new-window editor nvim .
tuios new-window logs -- tail -f /var/log/system.log
tuios new-window shell
tuios focus-window editor

Pick a window with fzf

#!/bin/bash
id=$(tuios list-windows --json |
  jq -r '.windows[] | "\(.display_name)\t\(.window_id)"' |
  fzf --with-nth=1 | cut -f2)

[ -n "$id" ] && tuios focus-window "$id"

Each command opens a new connection to the daemon. For long-running scripts, use the control protocol directly. It has structured error codes, blocking waits and an event stream.

Environment variables

Variables TUIOS reads:

Variables TUIOS sets in every pane:

Exit codes

Every command that needs the daemon exits 3 without one. tuios ls then lists the sessions saved on disk, so a script can tell a stopped daemon (3) from a running daemon with no sessions (0 and an empty list):

tuios ls --json > sessions.json
case $? in
  0) echo "daemon up" ;;
  3) echo "daemon down; the list is from disk" ;;
  *) echo "failed" ;;
esac

ls is the only command that prints JSON when there is no daemon. The others print an explanation on stderr.

A tuios attach that ends because the session was killed or the daemon was lost exits 1. A normal detach exits 0.

The CLI does not tell failure types apart by exit code. For that, use the control protocol's error codes.

Related