CLI_REFERENCE.md

# CLI Reference

This document provides a complete reference for TUIOS command-line interface.

## Table of Contents

- [Overview](#overview)
- [Installation](#installation)
- [Usage](#usage)
- [Commands](#commands)
  - [tuios tutor](#tuios-tutor)
  - [Root Command](#root-command)
  - [Theming](#theming)
    - [Looks: tuios look](#looks-tuios-look)
  - [Agent Skill](#agent-skill)
  - [Daemon Mode (Session Persistence)](#daemon-mode-session-persistence)
  - [Remote Control Commands](#remote-control-commands)
  - [Inspection Commands](#inspection-commands)
  - [More Commands](#more-commands)
    - [tuios hosts test](#tuios-hosts-test)
    - [tuios cp](#tuios-cp)
    - [tuios transfers](#tuios-transfers)
  - [Scripting Examples](#scripting-examples)
  - [tuios ssh](#tuios-ssh)
  - [tuios-web (separate binary)](#tuios-web-separate-binary)
  - [tuios config](#tuios-config)
  - [tuios keybinds](#tuios-keybinds)
  - [tuios notify test](#tuios-notify-test)
  - [tuios notify push](#tuios-notify-push)
  - [tuios status](#tuios-status)
  - [tuios update](#tuios-update)
  - [tuios layout](#tuios-layout)
  - [tuios completion](#tuios-completion)
  - [tuios help](#tuios-help)
- [Global Flags](#global-flags)
- [Common Usage Examples](#common-usage-examples)
- [Environment Variables](#environment-variables)
- [When Something Goes Wrong](#when-something-goes-wrong)
- [Exit Codes](#exit-codes)
- [Version Information](#version-information)
- [Command Migration Guide](#command-migration-guide)
- [Related Documentation](#related-documentation)

## Overview

TUIOS uses a modern command-line interface built with Cobra and Fang, providing:
- Subcommand structure for better organization
- Styled help output and error messages
- Shell completion generation

## Installation

### Homebrew (macOS/Linux)

```bash
brew install tuios
```

The ghostty build (the [libghostty-vt emulator](ghostty-vt.md)) is a separate cask for Linux. It installs a binary with the same name as the `tuios` formula. Uninstall the formula first.

```bash
brew uninstall tuios
brew install gaurav-gosain/tap/tuios-ghostty
```

### Arch Linux (AUR)

```bash
# Using yay
yay -S tuios-bin

# Using paru
paru -S tuios-bin
```

### Nix

```bash
# Run a release (put the tag after the repo name)
nix run github:Gaurav-Gosain/tuios/v0.8.0#tuios

# Run the newest commit on main
nix run github:Gaurav-Gosain/tuios#tuios

# Or add to your configuration
nix-shell -p tuios
```

### Quick Install Script (Linux/macOS)

```bash
curl -fsSL https://raw.githubusercontent.com/Gaurav-Gosain/tuios/main/install.sh | bash
```

### Go Install

```bash
go install github.com/Gaurav-Gosain/tuios/cmd/tuios@latest
```

### Pre-built Binaries

Download from [GitHub Releases](https://github.com/Gaurav-Gosain/tuios/releases)

---

## Usage

```bash
tuios [command] [flags]
```

## Commands

### `tuios tutor`

Learn tuios in a few minutes, by doing it. `tuios learn` is the same
command. The tutor runs a real tuios with a practice shell in this terminal.
The shell, the files and the agents in it are pretend.

```bash
tuios tutor            # open the menu: start a track, or continue one
tuios tutor basics     # open one track at once
tuios tutor --list     # list the tracks
tuios tutor --reset    # clear your progress
```

Nothing on your computer changes:

- The tutor starts no program and does not connect to a running tuios.
- It reads none of your config, and it uses the shipped keys and theme.
- While it runs, the home, the XDG folders and TMPDIR point at a temp
  folder. The tutor removes that folder when it ends, also on SIGTERM.
- Clipboard writes stay inside the tutor.
- It keeps your progress in `$XDG_STATE_HOME/tuios/tutor.json`. That is the
  only file it writes.

In a lesson, a card under the screen shows the step, its keys and a note.
The keys light up as you press them. After 8 seconds the note turns into a
hint.

| Key | Does |
|-----|------|
| `F2` | Open the menu: continue, back one step, restart, choose a track, leave |
| `F3` | Show me: the tutor presses the rest of the keys |
| `F4` | Skip the step |
| a quit key of tuios | Open the menu |

A click works on every button. Below 80x24 the card is a 2-row strip.
Below 60x16 the tutor asks for a bigger window and keeps your place.

Run inside a tuios pane, the outer tuios takes `ctrl+b`. Press `ctrl+b`
then `enter` to give every key to the tutor. `F12` gives the keys back.

### Root Command

Run TUIOS. A plain `tuios` attaches to a daemon-backed session, because
`startup.daemon` ships on. Add `--standalone` for a local session that lives and
dies with this process:

```bash
tuios
tuios --standalone
```

With `startup.session` set, a plain `tuios` attaches to that session and makes
it if it is gone. `startup.window` also focuses one pane in it. See
[SESSIONS.md](SESSIONS.md#start-session-and-start-pane).

**Flags:**

`tuios --help` is the authoritative list. These are the flags it shows today:

- `--standalone`: Run a standalone session without the daemon, overriding `startup.daemon`. `TUIOS_NO_DAEMON=1` does the same for a whole shell
- `--theme <name>`: Color theme to use, such as dracula, nord or tokyonight. Leave it empty (the default) to use the terminal's own colors without theming
- `--list-themes`: List all available themes and exit
- `--preview-theme <name>`: Preview a theme's 16 ANSI colors and exit
- `--skill [topic]`: Print the embedded agent skill and exit: the core, one topic, or `all` (see [Agent Skill](#agent-skill))
- `--ascii-only`: Use ASCII characters instead of Nerd Font icons
- `--show-keys`: Enable showkeys overlay (screencaster-style key display)
- `--border-style <style>`: Window border style: rounded, normal, thick, double, hidden, block, ascii, outer-half-block, inner-half-block, glyphs (default: from config or rounded)
- `--dockbar-position <pos>`: Dockbar position: bottom, top, hidden (default: from config or top)
- `--hide-window-buttons`: Hide window control buttons (minimize, maximize, close)
- `--window-button-style <style>`: How the window controls are drawn: `dots` (default, macOS traffic lights) or `pill`. On the left, the pill puts close at the outer corner: close, zoom, minimize. On the right it is minimize, zoom, close
- `--window-button-position <position>`: Which end of the title bar the window controls sit on: `left` (default, macOS) or `right`
- `--window-title-position <pos>`: Window title position: bottom, top, hidden (default: from config or top)
- `--scrollback-lines <num>`: Number of lines in scrollback buffer (default: from config or 10000, 100 to 1000000)
- `--hide-scrollbar`: Hide the window scrollbar thumb on the border
- `--zoom-max-width <cells>`: Max width in cells for zoom mode (0 is fullscreen)
- `--confirm-quit`: Always show the quit confirmation dialog
- `--hide-clock`: Hide the clock overlay (deprecated, the clock is hidden by default)
- `--show-clock`: Show the clock overlay
- `--show-cpu`: Show a CPU graph in the dock. It works on Linux, macOS, Windows, FreeBSD and OpenBSD. On another platform it shows `CPU: n/a`.
- `--show-ram`: Show RAM usage in the dock
- `--no-animations`: Disable UI animations for instant transitions (`appearance.motion = none` for this run)
- `--shared-borders`: Share borders between adjacent tiled windows
- `--debug`: Enable debug logging
- `--server <name>`: Use the daemon named `<name>`. It has its own socket and saved sessions. See [Running a separate daemon](SESSIONS.md#running-a-separate-daemon)
- `--cpuprofile <file>`: Write a CPU profile to file. The profile is written by the interface (`tuios`, `attach`, `new`) and by the commands that keep running: `daemon`, `ssh`, `mcp`, `stdio-proxy`, `pair`, `agent-proto`, `tape play`, `mermaid --watch` and `--demo`, and `gui-bridge`. It is complete when the command ends, by its signal or the end of its input. `gui-bridge` writes one only when you run it by hand, as the renderer starts it with a fixed command line. `start-server` does not pass `--cpuprofile` to the daemon it starts. While a CPU profile is being written, `/debug/pprof/profile` answers 500
- `--pprof <addr>`: Serve /debug/pprof profiles on this address for live profiling, such as `:6060`. With no host, the server listens on 127.0.0.1 only. The profiles have no password. Name `0.0.0.0` only on a network you trust. Delta profiles (`?seconds=` on heap and the like) are not served. Take two and compare them with `go tool pprof -diff_base`. With `start-server`, the daemon that the command starts serves the profiles. With `ssh`, the SSH server serves the profiles. The commands that keep running serve them too: `daemon`, `gui-bridge`, `mcp`, `stdio-proxy`, `pair`, `subscribe`, `agent-proto`, `tape play` and `mermaid --watch` and `--demo`
- `-h, --help`: Show help for tuios
- `-v, --version`: Show version information

The interface flags, from `--theme` to `--shared-borders`, are also flags of
`attach`, `new`, `ssh` and `tape play`, the commands that draw the interface.
`--debug` and `--server` work on every command. `--cpuprofile` and `--pprof` are honoured by the commands that keep running (see the flags above).

**Examples:**
```bash
tuios                          # Start TUIOS normally
tuios --theme dracula          # Start with Dracula theme
tuios --ascii-only             # Start without Nerd Font icons
tuios --show-keys              # Start with showkeys overlay enabled
tuios --list-themes            # List all available themes
tuios --preview-theme nord     # Preview Nord theme colors
tuios --skill                  # Print the agent skill and exit
tuios --skill recipes          # Print one topic of it
tuios --debug                  # Start with debug logging
tuios --cpuprofile cpu.prof    # Start with CPU profiling

# Combine multiple flags
tuios --theme nord --show-keys # Use Nord theme with showkeys enabled

# Interactive theme selection with fzf
tuios --theme $(tuios --list-themes | fzf --preview 'tuios --preview-theme {}')
```

---

## Theming

TUIOS includes 300+ built-in color themes from various sources including Gogh, iTerm2, and custom themes.

### Available Themes

List all available themes:
```bash
tuios --list-themes
```

With no theme set, tuios uses the terminal's own colors.

**Popular themes include:**
- `charmtone`: Charm's CharmTone colours on a dark ground, with a Charple accent
- `charmtone-light`: CharmTone on a light ground
- `gilt`: Cool obsidian, warm parchment and a gold accent
- `tokyonight`: A clean, dark theme with vibrant colors
- `dracula`: Dark theme with purple accent
- `nord`: An arctic, north-bluish color palette
- `gruvbox_dark`: Retro groove color scheme
- `catppuccin_mocha`: Soothing pastel theme
- `monokai_pro`: Professional dark theme
- `solarized_dark`: Precision colors for machines and people
- `github`: GitHub's light theme
- `one_dark`: Atom's iconic dark theme

### Preview Themes

Preview a theme's 16 ANSI colors before using it:
```bash
tuios --preview-theme dracula
```

The preview shows all 16 colors (8 standard + 8 bright variants) with their color codes.

### Using Themes

Set a theme at startup:
```bash
tuios --theme nord
```

The theme affects:
- Terminal text colors (ANSI 0-15)
- Window borders
- UI elements (status bar, dock, overlays)
- Default foreground/background colors

**Note:** The theme only affects the 16 base ANSI colors. Applications using 256-color or true color (RGB) will display those colors unchanged.

### Interactive Theme Selection

Use `fzf` for interactive theme selection with live preview:
```bash
tuios --theme $(tuios --list-themes | fzf --preview 'tuios --preview-theme {}')
```

This allows you to browse all themes with a live color preview before selecting one.

### Theme Persistence

Themes are set via command-line flag and not currently stored in configuration. To always use a specific theme:

**Shell alias:**
```bash
# Add to ~/.bashrc, ~/.zshrc, etc.
alias tuios='tuios --theme nord'
```

**Script wrapper:**
```bash
#!/bin/bash
exec tuios --theme dracula "$@"
```

### Looks: `tuios look`

A look is a small TOML file that sets how tuios looks: theme, glyph set,
borders, gaps, dock and rail style. The [gallery](https://tuios.dev/gallery)
shares looks. [docs/THEMES.md](THEMES.md#looks) describes the file.

```bash
# Apply a look from the gallery. Each look there shows this command with its id.
tuios look apply tuios.dev/r/<id>

# Apply a look from an https URL or from a file
tuios look apply https://example.com/my.look.toml
tuios look apply ./my.look.toml

# Choose a look from the gallery list, and apply it
tuios look pick

# List the gallery looks: id, name and author
tuios look list
tuios look list --json

# Show the look in use
tuios look show

# Remove the look and the theme it installed
tuios look remove

# List the keys a look can set
tuios look keys
tuios look keys --json

# Print your look as a look file, or write it to a file
tuios look export
tuios look export -o my.look.toml --name "Neon 84"

# Share your look in the setups discussion on GitHub
tuios look share
tuios look share --print
```

`tuios look apply <source>`:

- The source is a gallery id (`tuios.dev/r/ID` or `ID`), an https URL, or a
  local file. tuios downloads only over https.
- tuios shows the changes and asks before it writes. Use `--yes` to skip the
  question. A run with no terminal needs `--yes`.
- tuios writes the look to `config.d/look.toml`. Without a take-over, it
  does not change `config.toml`.
- A theme or glyph set in the look goes into the themes or glyphs folder. Its
  name starts with `look-`.
- A running tuios reloads the config. You do not restart.
- A look can set only look keys. tuios leaves out every other key and names
  it. A value that is not correct stops the look.
- `config.toml` wins over `config.d`. tuios names each key that `config.toml`
  or a later `config.d` file sets, because the look does not change that key.
- tuios then asks: "Let the look set these keys?" A yes is a take-over. tuios
  removes the keys from those files and saves your values in
  `config.d/look.saved.json`. The comments and the order of the files stay.
- `--take-over` answers yes. `--yes` alone answers no, so a script keeps its
  config. Use `--yes --take-over` for both.
- A file that tuios cannot write keeps its keys, and so does a file that
  another file includes. tuios names the file and the keys.
- A new look replaces the look in use.
- A config folder that tuios cannot write stops the command.

`tuios look pick` shows the looks of the gallery, each with its name, its
author and the colours of its theme. `tuios look` with no command does the
same in a terminal. The command palette has it as "Choose a look", which
opens it in a new pane.

- Up and down move. Enter applies the look. Esc closes the list.
- Enter asks the same questions as `tuios look apply`, the take-over question
  too. `--take-over` answers that question yes.
- `tuios look list` prints the id, the name and the author of each look.
  `--json` adds the colours of each theme.
- The list comes from `tuios.dev/gallery/feed`. When tuios cannot get it, the
  command says so and exits with an error.

`tuios look remove` deletes `config.d/look.toml` and the theme and glyph set
that the look installed. Use `--yes` to skip the question. After a take-over,
it puts your saved values back:

- A file that you did not change since the take-over goes back byte for byte.
- In a file that you changed, tuios puts back each saved key that the file
  does not set.
- A key that you set again after the take-over keeps your newer value. tuios
  names it.
- A file that you deleted stays deleted. tuios names the keys it does not put
  back.
- When tuios cannot write a key back, the look stays and the key stays saved.
  Fix the file, then run `tuios look remove` again.
- When `config.d/look.saved.json` cannot be read, tuios asks before it removes
  the look without the saved values. It moves the file aside and does not
  delete it.
- When `config.d/look.toml` is gone, `tuios look remove` still puts the saved
  values back.

A new look applied over a take-over puts back the saved keys that the new look
does not set. tuios reads each file again before it writes it. If a file
changed while tuios asked its questions, tuios stops and changes nothing.

`tuios look export` prints the look in force as a look file.
`tuios look apply` takes the file unchanged.

- `-o FILE` writes the file instead of stdout.
- `--name` sets the name. `--author` sets the author. The author is your
  GitHub login when `gh` is signed in.
- The file sets the keys that differ from the defaults. `--all` sets every
  look key.
- A theme or glyph set from your own folder goes into the file. A built-in
  one goes in by name. tuios names on stderr each key or item it leaves out.

`tuios look share` shares your look in
[discussion #849](https://github.com/Gaurav-Gosain/tuios/discussions/849).
The command palette has it as "Share my look". The Appearance page of the
settings has it too. There the dock says "Look copied. Paste it in the browser
page." Press prefix+N to read the full message with the path of the
screenshot.

- tuios exports the look and takes a screenshot of the screen. The running
  tuios takes it, and the screenshot goes to Downloads or the cache folder.
- tuios puts the comment on the clipboard through the terminal (OSC 52), also
  over ssh. Where a clipboard tool is on this machine, tuios uses it too.
- tuios opens the discussion in the browser: `appearance.link_opener`, then
  `$BROWSER`, then the system opener. Over ssh, or with no browser, it prints
  the address.
- The command prints at most three lines: what is on the clipboard, where the
  screenshot is, and the address when no browser opened.
- `--print` writes the comment to stdout and opens nothing.
- `--name` and `--author` work as they do for `tuios look export`.
- With no tuios attached, the command writes the clipboard through its own
  terminal. The daemon then captures the focused pane, if there is one.

---

## Agent Skill

`tuios --skill` prints the agent skill embedded in the binary and exits. The
skill teaches an agent to drive TUIOS from inside a pane. It is split so an
agent loads only what it needs:

- `tuios --skill` (or `--skill core`) prints the core (about 280 lines): how to tell it is in a
  pane, what its pane may do, addressing, reading and writing panes, running
  work and waiting for it, reporting its own state, talking to other agents and
  the person safely, and a table of the topics.
- `tuios --skill TOPIC` prints one topic: `panes`, `state`, `inbox`, `mail`,
  `fleet`, `checkpoints`, `ship`, `hosts`, `events`, `clients`, `mcp`, `tmux`,
  `herdr`, `notify`, `agents-off`, `grants`, `config`, `errors` or `recipes`. `recipes` has end-to-end recipes: a fleet of agents, answering
  from the Inbox, approvals, agents on another machine, MCP setup, the tmux
  shim, scoped grants, a conductor pane and a phone alert.
- `tuios --skill all` prints the core and every topic.
- An unknown topic is an error that lists the topics.

```bash
tuios --skill
tuios --skill fleet
tuios --skill all
```

The text ships inside the binary as `skills/tuios/SKILL.md` and the other
files in `skills/tuios/`, so it always describes the TUIOS that printed it.
Nothing is fetched and no daemon is needed. `tuios --skill=TOPIC` works too.

To make an agent harness load the skill, run `tuios integration install`. It
writes a short `SKILL.md` that tells the agent to run `tuios --skill`, so the
text the agent reads always matches the TUIOS you have installed. Claude Code
gets it in `~/.claude/skills/tuios/`. Codex, opencode and Pi get it in
`~/.agents/skills/tuios/`. TUIOS leaves a `SKILL.md` alone when it did not write it, when you changed it, or when it is a symlink.

**Examples:**
```bash
# Install the hooks and the skill for Claude Code
tuios integration install claude-code

# Do not copy the whole text into a skill file. The copy goes out of date
# when you update TUIOS.
```

---

## Daemon Mode (Session Persistence)

TUIOS supports persistent sessions through a daemon process, similar to tmux or screen. Sessions continue running in the background even when you disconnect, allowing you to reattach later with all windows and content preserved.

### `tuios new`

Create a new persistent session.

**Usage:**
```bash
tuios new [session-name] [flags]
```

**Flags:**
- `--theme <name>`: Set color theme for the session
- `--ascii-only`: Use ASCII characters instead of Nerd Font icons
- `--show-keys`: Enable showkeys overlay
- `--no-animations`: Disable UI animations
- `-d, --detach`: Create the session headless without attaching a client
- `--host <name>`: Create the session on this host from the `[hosts]` table
- `--ssh`: With `--host`, run ssh to the host and its own tuios instead of attaching here
- `--global`: Create a global session, which holds panes from more than one machine
- `--hold`: After a failure, wait for enter before the command exits
- `--cwd <dir>`: Directory the session's windows start in. The default is the current directory
- `--space <name>`: File the session under a space, a named group of related sessions. It follows the session name rules and is at most 64 bytes
- The appearance flags of the root command (`tuios new --help` lists them)

The session's windows start in the directory where you run `tuios new`.
`--cwd` names a different directory. The directory applies to the first
window, and to each later window that has no pane to take a directory from.
`--cwd` does not work with `--host`.

`--space` files the session under the space as it is made, so `tuios ls` and the sidebar list it with the space's other sessions. It does not work with `--host`, and with `--global` it is refused: a global session cannot be in a space. See [`tuios set-session-space`](#tuios-set-session-space).

**Examples:**
```bash
tuios new                      # Create session with auto-generated name
tuios new mysession            # Create session named "mysession"
tuios new api --cwd ~/dev/api  # Create a session whose windows start in ~/dev/api
tuios new work --theme dracula # Create session with Dracula theme
tuios new ci --detach          # Create a headless session and return
tuios new api --space payments # Create a session in the space payments
tuios new --host build         # Create a session on the host build and attach it
tuios new deploy --global      # Create a global session
```

### `tuios attach`

Attach to an existing session.

**Usage:**
```bash
tuios attach [session-name] [flags]
```

**Flags:**
- `-c, --create`: Create session if it doesn't exist
- `--host <name>`: Attach to a session on this host from the `[hosts]` table
- `--ssh`: With `--host`, run ssh to the host and its own tuios instead of attaching here
- `--hold`: After a failure, wait for enter before the command exits
- `--terminal-mode`: Start in terminal mode, whatever `startup.start_in_terminal_mode` says
- `-d, --detach-others`: Detach every other client of the session, as `tmux attach -d` does
- Same as `tuios new` (theme, ascii-only, etc.)

**Examples:**
```bash
tuios attach                   # Attach to most recent session (or only session)
tuios attach mysession         # Attach to session named "mysession"
tuios attach -d mysession      # Attach and detach the other clients of mysession
tuios attach mysession -c      # Attach or create if doesn't exist
tuios attach mysession --theme nord  # Attach with different theme
tuios attach --host build api  # Attach the session api on the host build
```

When the session already has a client, `tuios attach` says so and names the
`window_size` policy of the session. For example: "The session uses the size of
the client that last had input (window_size latest)." See
[SESSIONS.md](SESSIONS.md#session-size-with-more-than-one-client).

With `-d`, each other client of the session detaches as this client attaches.
The session continues to run. Each detached client exits with status 0 and
prints this message:

```
Another client attached to this session.
Detached from session 'mysession'.
```

To do this on every attach, set `single_client = true` in `[daemon]`. See
[CONFIGURATION.md](CONFIGURATION.md). To detach clients without an attach,
use [`tuios detach-client`](#tuios-detach-client).

With `ssh_agent = "follow"` in `[daemon]`, `tuios attach` points the ssh
agent link of the session at the `SSH_AUTH_SOCK` of this client. See
[`tuios ssh-agent-path`](#tuios-ssh-agent-path).

With `display = "follow"` in `[daemon]`, the default, `tuios attach` sends the
display of this client. A daemon with no display of its own gives it to new
panes of the session. See [`tuios display-env`](#tuios-display-env).

Inside a tuios pane, `tuios attach` refuses to attach the session that holds
the pane. A bare `tuios attach` or `tuios` in a pane also refuses, because
it does not name a session. To show a different session in the pane, name
that session. To attach the same session, open a new terminal outside tuios.
To attach anyway, use `--force` or set `TUIOS_ALLOW_NESTED=1`.
To move the client that shows the pane to a different session, use
[`tuios switch-session`](#tuios-switch-session).

The same refusal applies when the session would show itself through a
chain. For example, session A shows session B in a pane, and a pane of B
then attaches A.

tuios finds the pane in these ways:

- The client runs on the pane's terminal.
- The client's output reaches the pane. This finds `script`, and ssh from
  the pane to the same machine or to the tuios SSH server. The attach does
  not wait for this check. If tuios finds it in the first 2 seconds after
  the attach, it detaches the client with the same message.
- A client with no terminal runs under the pane's shell or has the pane's
  `TUIOS_` variables.

A terminal window started from a pane attaches. Its output does not reach
the pane.

tuios cannot find a client behind tmux or mosh in a pane. These redraw
the screen and do not pass the output through. Such an attach goes
through, and the session shrinks to 20x6. It stays at 20x6 until the
inner client exits. A forced attach also stays at 20x6 or more.

### `tuios switch-session`

Switch an attached client to a different session, in place. This is what the
session switcher does. Nothing is nested.

**Usage:**
```bash
tuios switch-session [HOST:]NAME [flags]
```

**Flags:**
- `-s, --session <name>`: Switch the client that shows this session
- `--client <id>`: Switch the client with this id, from `tuios list-clients`
- `-c, --create`: Create the session if it does not exist
- `--cwd <dir>`: With `--create`, the directory the new session's windows start in
- `--json`: Output as JSON

The command switches one client:

1. The client that `--client` names.
2. Else the client that shows the session that `-s` names.
3. Else, from a pane or a popup, the client that shows the session of the pane.
4. Else the only client that is attached. With more than one client, name one.

`HOST` is a machine from the `[hosts]` table. Without `HOST`, the session is
on this machine. A session that `--create` makes has one window. When the
session exists, `--create` and `--cwd` do nothing, and the client switches to
it.

When the session is not arranged yet, `[startup]` applies to it, as on a first
attach. For example, `startup.tiled = true` tiles a session that
`tuios new --detach` made. A session that a person arranged keeps its layout.

From a pane, the command needs the `admin` grant.

**Examples:**
```bash
tuios switch-session api                           # From a pane: show the session api
tuios switch-session --create --cwd ~/dev/api api  # Show api, and make it in ~/dev/api if it is missing
tuios switch-session build:api                     # Show the session api on the host build
tuios switch-session -s work api                   # From outside tuios: switch the client that shows work
```

See [Sessionizer](SESSIONS.md#sessionizer) for a key that opens a project.

### `tuios ls`

List all TUIOS sessions.

**Usage:**
```bash
tuios ls [flags]
```

**Flags:**
- `--json`: Output as JSON. Saved sessions carry `"saved": true`
- `--all-hosts`: Also list the sessions on every host in the `[hosts]` table. A host that does not answer gets a row saying so and never fails the command. Its sessions from when it last answered follow, under "As of ..., when it last answered", and are not counted in the total
- `--host <name>`: List the sessions on one host (`local` means this machine)

With no daemon running, `tuios ls` lists the sessions saved on disk instead,
marked `saved`, and exits 3.

**Output:**
Shows a table with:
- Session name
- Number of windows
- Status (attached/detached)
- Creation time
- Last activity time

**Example output:**
```
╭───────────────┬─────────┬──────────┬───────────────┬─────────────────╮
│ NAME          │ WINDOWS │ STATUS   │ CREATED       │ LAST ACTIVE     │
├───────────────┼─────────┼──────────┼───────────────┼─────────────────┤
│ work          │ 3       │ detached │ 2 hours ago   │ 5 mins ago      │
│ dev           │ 2       │ attached │ 1 day ago     │ just now        │
╰───────────────┴─────────┴──────────┴───────────────┴─────────────────╯
```

When any session is in a space, the listing is one table per space, in name order, each under the space's name, and the sessions in no space follow last with no heading. With no session in a space it is the one table above. The saved listing groups the same way, by the space each saved session was in. `tuios ls --all-hosts` groups each host's sessions under that host's line, by the spaces on that host, so a space of the same name on two hosts is two groups. A host whose daemon predates spaces sends no space, and its sessions list as in none. `tuios ls --json` stays one flat list, with `space` on each row that has one, saved rows included, and `tuios ls --all-hosts --json` carries `space` on each session row the same way.

`tuios ls --json` prints one object per session. Two fields say where the session's focused pane is:

- `dir` is the base name of the shell's directory. It is `~` for the home directory.
- `branch` is the git branch checked out there. A detached HEAD reads as its short hash.

Both come from the directory the shell last reported over OSC 7, or the directory the shell started in. Both are omitted when unknown. The sidebar labels a session with a generated name (`session-0`) by `dir`, and shows `branch` after any session name.

A session whose directory is inside a linked git worktree (not a main
checkout) also carries `worktree`: the repository (`repo`, `repo_root`), the
`branch` and the worktree's `path`, `gone: true` once the directory no longer
exists, and for one tuios made, its `base`, its fan `group` and the prompt a
fan sent it. It is what the rail groups by. `global: true` marks a global session, and
`restored: true` one rebuilt from saved state that nobody has attached to yet.

### `tuios list-clients`

List every connection to the daemon with its client id, kernel peer pid, and
current session. The session is empty while the connection is detached. The
command's own short-lived connection is included. The pid is `0` on Windows and
the BSDs. An SSH or web client's pid names the local server process, not the
remote SSH process or browser.

**Usage:**
```bash
tuios list-clients [--json]
```

`--json` prints an array with one object per connection:

```json
[
  {"client_id":"client-1790941960197517900","pid":4242,"session":"work"}
]
```

`client-session-changed` carries the session a client entered or left and sets
`attached` to `true` or `false`. A session rename sends one with the new name
and `attached: true` for each client in the session.

### `tuios detach-client`

Detach attached clients from their sessions, as `tmux detach-client` does.
The sessions continue to run. Each detached client exits with status 0 and
prints "The tuios detach-client command detached this client."

**Usage:**
```bash
tuios detach-client [--client ID | --session NAME] [--all-other] [--json]
```

**Flags:**
- `--client <id>`: Detach the client with this id, from `tuios list-clients`
- `-s, --session <name>`: Detach every client of this session
- `-a, --all-other`: Keep one client and detach every other client of its session
- `--json`: Output as JSON

The command detaches:

1. The client that `--client` names.
2. Else every client of the session that `-s` names.
3. Else, from a pane, the client used last in the session of the pane.
4. Else the client used last in the only session with a client.

With `--all-other`, the command keeps the client that `--client` names, or
the client used last in the session. It detaches every other client of that
session.

From a pane, the command needs the `admin` grant. See
[`tuios pane-grants`](#tuios-pane-grants).

**Examples:**
```bash
tuios detach-client --client client-1790941960197517900
tuios detach-client -s work               # Detach every client of work
tuios detach-client -s work --all-other   # Keep the client used last in work
```

`--json` prints the ids of the detached clients:

```json
{"detached":["client-1790941960197517900"]}
```

### `tuios ssh-agent-path`

Print the ssh agent link of a session. With `ssh_agent = "follow"` in
`[daemon]`, the link points at the agent socket of the client that attached
to the session or used it last. New panes get `SSH_AUTH_SOCK` set to the link.
See [CONFIGURATION.md](CONFIGURATION.md).

**Usage:**
```bash
tuios ssh-agent-path [-s NAME] [--json]
```

**Flags:**
- `-s, --session <name>`: Session whose link to print. In a pane, the default is the session of the pane
- `--json`: Output as JSON, with `follow` and the socket the link points at (`target`)

The command fails when `ssh_agent` is not `"follow"`. A shell that started
before the option was set keeps its old `SSH_AUTH_SOCK`. Add this line to
your shell rc:

```bash
p=$(tuios ssh-agent-path 2>/dev/null) && export SSH_AUTH_SOCK="$p"
```

### `tuios display-env`

Print the display of a session as export lines. A daemon that started without
a display gives new panes the display of the local client that attached or
used the session last. This is `display = "follow"` in `[daemon]`, the
default. See [CONFIGURATION.md](CONFIGURATION.md).

**Usage:**
```bash
tuios display-env [-s NAME] [--json]
```

**Flags:**
- `-s, --session <name>`: Session whose display to print. In a pane, the default is the session of the pane
- `--json`: Output as JSON, with `follow`, `own`, the Wayland `link`, the socket it points at (`target`) and the variables (`env`)

The command prints an `export` line for each of `WAYLAND_DISPLAY`, `DISPLAY`
and `XAUTHORITY` that the session has. It prints nothing when the session has
no display to give. A shell that started before a desktop client attached
has no display. Run this line in that shell, or add it to your shell rc:

```bash
eval "$(tuios display-env 2>/dev/null)"
```

### `tuios kill-session`

Kill a specific session.

**Usage:**
```bash
tuios kill-session <session-name>
```

**Examples:**
```bash
tuios kill-session mysession   # Kill session named "mysession"
```

### `tuios worktree`

A git worktree as a session. `worktree new` makes a worktree of the repository
you are in and a session whose directory is that worktree. The rail groups these
sessions under the repository and labels each by its branch.

A worktree of a bare repository is grouped under the project's name: `api` for
`api.git`, and for a bare repository kept as `api/.bare` or `api/git` beside
its worktrees, the `api` directory. A repository whose refs are in reftable
(`git clone --ref-format=reftable`) holds no branch name in its HEAD file.
tuios asks git for its branches instead, so it needs git 2.45 or later on
`PATH`, and asks again only after a ref changes.

The same verb is reachable from the rail. Right-click a repository's group
header, or a worktree session's row, and take "New worktree...". The dialog
asks for the branch and the session name. Leave the name empty and the dialog
derives one from the repository and the branch. It does not ask for the
folder: the daemon places the worktree by `[worktree] path` (see
[Where worktrees go](CONFIGURATION.md#where-worktrees-go)), else under
`TUIOS_WORKTREE_DIR` in the daemon's environment, else under
`$XDG_DATA_HOME/tuios/worktrees`, and the notification reports where it
went. A worktree inside the repository that git does not ignore is reported
with a warning.

**Usage:**
```bash
tuios worktree new <branch> [--repo <dir>] [--base <ref>] [--name <session>] [--agent <cli>] [--host <host> [--clone]] [--detach]
tuios worktree ls [--repo <name>] [--group <stem>] [--host <host>] [--json]
tuios worktree rm [<host>:]<session> [--stash | --force] [--keep-session]
tuios worktree diff <session> [--stat]
tuios worktree pull <host>:<session> [--repo <dir>] [--branch <name>] [--name <session>] [--detach] [--json]
```

**Examples:**
```bash
tuios worktree new feat/retry                          # A new branch from HEAD, attached
tuios worktree new feat/retry --agent claude --detach  # Headless, running Claude Code
tuios worktree ls                                      # Repo, branch, agent state, changes, merged
tuios worktree rm api-feat-retry --stash               # Keep the changes in git stash
```

The session is named `<repo>-<branch>`, with every slash turned into a hyphen.
Worktrees go under `$XDG_DATA_HOME/tuios/worktrees/<repo>/<branch>`, unless
`[worktree] path` puts them elsewhere (see
[Where worktrees go](CONFIGURATION.md#where-worktrees-go)).

An `after-new-worktree` hook runs in the new worktree before its first window
starts, for example to copy `.env` from the main checkout. See
[HOOKS.md](HOOKS.md). When the hook fails, `worktree new` prints a warning
and keeps the worktree and the session.

`worktree rm` refuses a worktree with uncommitted changes and removes nothing.
`--stash` keeps the changes in git stash as `tuios: <branch>`. `--force`
discards them, and is the only option that does. The branch is never deleted.
A session whose worktree directory was removed under it shows `gone` in the
listing and is kept.

The MERGED column of `worktree ls` shows `into <ref>` when the branch is
merged. A branch is merged when it has commits of its own, and merging it into
its base changes nothing. tuios checks the base, then the upstream of the base,
such as `origin/main`. It does not fetch. A merge commit, a fast-forward, a
rebase and a squash merge all count. A new branch with no commits is not
merged. A branch that only fast-forwarded to its base is not merged. A commit
and its revert are not merged. `--json` gives `merged` and `merged_into`. tuios does not remove a
merged worktree. Use `worktree rm` to remove it.

**On another machine.** `--host` runs `worktree new` and `worktree ls` on a
machine from the `[hosts]` table, and `worktree rm` takes `HOST:SESSION`. Run
them inside your checkout: the repository is sent as its origin URL, and the
host finds its own checkout of it under `[hosts.NAME] repos_root` (set with
`tuios hosts add NAME ADDR --repos-root ~/src`), or else under `~/src`,
`~/dev`, `~/code`, `~/projects`, `~/repos`, `~/git`, `~/work` and `~/go/src`
there. `--clone` clones it there when it has none; only https, ssh and git URLs
are cloned. With `--host`, `--repo` names a directory on the host. A host whose
tuios is too old for this is named, with what to upgrade.

`worktree diff` reads files on this machine, so it refuses `HOST:SESSION` and
names `worktree pull`.

**Pulling work back.** `worktree pull HOST:SESSION` copies a worktree session's
work on another machine into a new worktree session here. Its commits cross as
a git bundle and are fetched into a new branch of the repository you are in,
named as there or by `--branch`. The branch carried is the one the worktree's
HEAD is on now, so an agent that made its own branch there has that branch
pulled. A worktree with a detached HEAD is refused. When the commits cannot be
fetched, or the branch they make does not end where the other machine said,
the new branch is removed again, so the pull can simply be run again. Its uncommitted work, untracked files
included, crosses as a patch and is applied, uncommitted, in the new worktree.
Only the commits past the worktree's base cross when this repository has the
base commit, and the whole branch otherwise. A branch that already exists here
is refused and nothing is overwritten. A repository here whose origin differs
from the one there is refused. Nothing on the other machine changes. When the
patch does not apply, it is kept under the temporary directory and the command
names it.

```bash
tuios worktree new feat/retry --host build --clone --detach
tuios worktree ls --host build
tuios worktree pull build:api-feat-retry --detach
tuios worktree rm build:api-feat-retry --stash
```

### `tuios fan`

Fan a prompt out across several agents, each in its own worktree.

**Usage:**
```bash
tuios fan <count> --agent <agent>[,<agent>...] [--env NAME[=VALUE]]... [--repo <dir>] [--base <ref>] [--name <stem>] [--host <host> [--clone]] [--wait] <prompt>
tuios fan [<count>] --agent <agent>[,<agent>...] --prompt <prompt> --prompt <prompt>... [flags]
tuios fan keep [<host>:]<session> [--stash | --force] [--merge [--squash | --ff-only] [--into <branch>]]
tuios fan compare [[<host>:]<session>] [--no-changes] [--json]
tuios fan verify [<host>:]<session> [--timeout <duration>] [--no-wait] [--json] -- <command>...
tuios fan diff <session-a> <session-b> [--stat]
tuios fan verdict [<host>:]<session> --pick <session> --summary <text> [--reason <text>]... [--note <session>=<text>]... [--json]
```

**Flags:**
- `--agent <agent>`: The agent as you would type it, arguments included: `claude`, `'codex --model o5'`, or any program. Several, comma-separated or repeated, are cycled across the sessions (required)
- `--prompt <prompt>`: One session's prompt, repeated once per session, in place of the prompt argument. The count is then how many there are
- `--env NAME` or `--env NAME=VALUE`: Pass your value of a variable, or set one, for every agent. Repeatable. `PATH` is always sent, so the agents are found where your shell finds them
- `--grants <grant>[,<grant>...]`: What every agent may do through tuios, as for `start-agent`
- `--name <stem>`: The fan's name, which its branches start with. A name that is already a fan in the repository is refused. Omitted, the name comes from the prompt and moves on to a free one
- `--join <session>`: Add the attempts to the fan of this session, on purpose, instead of starting a new fan. Your pane must reach that session
- `--task <id>`: The task card the fan works on. It gets the fan's name and holds no pane, so `tuios task claim --next` skips it while the fan lasts. With `[tasks] auto_stage` on it moves to `doing`, and `fan verify` and the attempts' pull requests then move it (see [`tuios task`](#tuios-task)). Needs what `tuios task claim` needs, and the card must be held by no pane but yours, not blocked and not done. Not with `--host`: the card is on this machine
- `--task-session <name>`: The session of `--task` (default: this pane's session, else the most recently active)
- `--repo <dir>`, `--base <ref>`, `--wait`, `--json`

**Examples:**
```bash
tuios fan 3 --agent claude 'Add a retry with backoff to the HTTP client.'
tuios fan 3 --agent 'claude,codex --model o5,gemini' 'Add a retry with backoff.'
tuios fan --agent claude --env ANTHROPIC_API_KEY --prompt 'Add a retry.' --prompt 'Add a timeout.'
tuios worktree ls --group fan/add-retry-backoff-http   # Which prompts were sent, what changed
tuios worktree diff api-fan-add-retry-backoff-http-2   # What one of them produced
tuios fan compare api-fan-add-retry-backoff-http       # Every attempt side by side
tuios fan verify api-fan-add-retry-backoff-http -- go test ./...
tuios fan diff api-fan-add-retry-backoff-http api-fan-add-retry-backoff-http-2
tuios fan keep api-fan-add-retry-backoff-http-2 --stash
```

`tuios fan verdict` records a judge's pick among the attempts: the attempt
it recommends, the verdict, its reasons and a note on each attempt. The
agents view shows it on the fan's row and in the comparison (`c` on an
attempt), where `k` keeps the recommended attempt. In that comparison, `j`
starts a judge: an agent in a session of its own that reads the attempts and
reports with this command. Only that judge's pane, or a call from outside
every pane, records a verdict. The judge can read the attempts and nothing
more: tuios refuses it typing into their panes, commands in their sessions and
agents there. It runs in the main checkout as a program with your rights to
files, and its prompt asks it to change none.

The branches are a stem, then `stem-2`, `stem-3`. The stem is `fan/` and the
first words of the prompt, or `--name`. Each prompt is typed once its agent
shows it is at its prompt, as one paste submitted with a carriage return (the
Enter key), so the command returns at once and `tuios worktree ls` shows
`pending`, `held: look at the pane`, `sent`, `not sent` or `stalled` per
session. `held` means the agent has not been ready for 30 seconds, most often
because it shows a first-run choice; the Inbox asks you to look, and the
prompt is typed once it is ready. A program no harness manifest recognises is
ready only once it reports a state (`tuios set-agent-state idle`). `stalled`
means the prompt was typed and the agent showed no sign of taking it within
five seconds: it did not turn working or needs_input. Look at the pane before
sending it again, since the text may be in the agent's input box. `--wait`
blocks until every prompt is sent or given up on.

The agent string is split into words the way a shell splits them and exec'd
directly: nothing in it is expanded. `TUIOS_` variables, `TMUX` and
`TMUX_PANE` cannot be passed with `--env`.

`fan compare` prints one line per attempt of the fan the session belongs to:
its agent and state, the files and lines it changed against the fan's base
(committed or not, untracked files included, ignored files left out), and its
last check. The check is the last `fan verify` result, or else the last
command a shell in the session finished, from its OSC 133 marks. The counts
run from where each attempt left the base, so a base that moves on after the
fan started (a fetch, or one attempt merged into it) does not change them.
They run git in every worktree, at most 10 seconds each; `--no-changes` skips
them. The worktrees are read
through a temporary index, so nothing in them changes.

```
fan/retry in api, 3 attempts against main
  api-fan-retry    claude  done     4 files  +120 -31  go test ./... passed 14m ago
  api-fan-retry-2  codex   working  2 files    +40 -3  no check yet
  api-fan-retry-3  claude  errored  0 files     +0 -0  last command exited 1 (make lint)
Keep one with 'tuios fan keep <session>'. Compare two with 'tuios fan diff A B'.
```

`fan verify` runs the command after `--` in every attempt, in a window named
`verify` in each session, with `sh -c` in the worktree and your `PATH`. One
word after `--` is a shell line, so `'make lint && make test'` keeps its `&&`.
Several words are one command and its arguments: each is quoted for the shell
as you gave it, so `-- go test -run 'TestA|TestB' ./...` passes the pattern
as one argument. The command is always yours: tuios never reads one from the repository. The
window holds no grants, so the check cannot drive tuios. A window whose check
passed closes; one whose check failed stays open with the output until you
press enter in it. The command waits for every check, prints one line each,
and exits 1 when any failed. `--timeout` fails a check that runs longer and
closes its window. `--no-wait` returns once the checks are started. A check
still running in an attempt is stopped first, and the window an earlier
failed check left open is closed.

`fan diff A B` shows what B's files hold that A's do not, committed or not,
untracked files included. git runs on this machine, as for `worktree diff`,
so both sessions must be here.

`fan keep` removes every sibling of the session you keep, the way `worktree rm`
does: a sibling with uncommitted changes is left in place unless `--stash` or
`--force` is passed, and the command exits 1 to say so. The daemon does the
removal (`keep-fan`), so the TUI and the CLI share it; against a daemon from
before that verb the CLI removes the siblings itself, with the same result.
`--merge` first merges the kept session's branch into its base in the main
checkout, as `tuios ship merge` does. When that merge is refused or
conflicts, it is undone and no sibling is removed.

`--host` runs the fan-out on another machine, in its checkout of the repository
you are in, found and cloned the way `worktree new --host` does it. The agent
must be installed there, and is looked up on that machine's `PATH`: yours is
not sent, and `--env` is refused. The sessions show in the rail under the
host. `fan keep HOST:SESSION` keeps one there, and `worktree pull
HOST:SESSION` brings its work here.

```bash
tuios fan 3 --host build --agent claude 'Add a retry.'
tuios worktree pull build:api-fan-add-retry-2
tuios fan keep build:api-fan-add-retry-2 --stash
```

### `tuios start-agent`

Start an agent in a new pane, here or on another machine, and return once it
is ready for a prompt.

**Usage:**
```bash
tuios start-agent <agent> [-s [<host>:]<session>] [--name <name>] [--cwd <dir> | --repo <dir> | --clone] [--workspace <n>] [--focus] [--prompt <prompt>] [--ready-timeout <ms>] [--protocol acp|codex] [--env NAME[=VALUE]]... [--grants <grant>[,<grant>...]] [--task <id>] [--json] [-- <args>...]
```

`--task` claims a task card of the session for the new pane as soon as the
pane exists. The card must be held by no pane, not blocked and not done, and
the call needs what `tuios task claim` needs. It is checked before anything
starts, and the session must exist already.

`--grants` says what the agent may do through tuios: `read`, `write`, `fan`,
`respond`, `admin`, or `none` (see [`tuios pane-grants`](#tuios-pane-grants)).
Without it the pane holds the default of `[agents.permissions]`, or, started
from a pane without `admin`, that pane's own grants.

**Examples:**
```bash
tuios start-agent claude --name reviewer
tuios ask-agent -w reviewer 'review the diff on this branch'
tuios start-agent 'codex --model o5' --name tests --prompt 'Run the tests and fix what fails.'
```

`<agent>` is written as for `fan`. The command waits until the agent shows it
is at its prompt (idle or done), then types `--prompt` if one was given, and
prints the pane and the evidence. It exits 1 when the agent is not ready: it
stopped on a question of its own (the pane is kept for you to answer, and the
Inbox shows it), showed nothing before `--ready-timeout` (default 120000), or
exited. It also exits 1 when a `--prompt` was not taken. The pane is not
focused unless `--focus` is passed.

The command sends your `PATH` with any `--env`, as `fan` does, when the
session is on this machine. For a session on another machine
(`-s host:session`) it sends no `PATH`, and the agent is looked up on that
machine's `PATH`. `--env` there is refused with `forbidden`, because
variables do not cross machines.

The session `-s` names is created when it does not exist. The agent starts in
`--cwd`, or the main checkout of the repository `--repo` names, or else the
focused pane's directory. With `-s HOST:SESSION` and neither, it starts in that
machine's checkout of the repository you are in, found and cloned the way
`worktree new --host` does it (`--clone` clones it there when it has none).
Arguments after `--` are passed to the agent as an argv.

```bash
tuios start-agent -s build:api claude --prompt 'Profile the build.' -- --model opus
```

`--protocol` runs the agent headless over a structured protocol instead of in
its own TUI, and the pane shows the conversation as a transcript you type
prompts into:

```bash
tuios start-agent --protocol acp 'opencode acp' --name helper --prompt 'List the TODOs.'
tuios start-agent --protocol codex codex --name tests
```

`acp` is the Agent Client Protocol, version 1, for any agent command that
speaks it. `codex` is the Codex app-server, and `app-server` is added to the
`codex` command. The pane runs [`tuios agent-proto`](#tuios-agent-proto),
which reports the agent's state itself, so the command returns once that
report says idle. A permission the agent asks for is answered in the pane with
a number key, or from the Inbox when one line shows the whole request, with no
`[agents.approvals]` needed. A daemon older than `--protocol` refuses it by
name.

### `tuios agent-proto`

The pane program of `start-agent --protocol`: run an agent headless over ACP
or the Codex app-server, and show it as a transcript with a prompt line.

**Usage:**
```bash
tuios agent-proto --protocol acp|codex [--harness <id>] [--cwd <dir>] -- <agent> [args...]
```

It starts the agent with pipes, in a session of its own with no controlling
terminal, and offers it no file system and no terminal, so the agent acts
under its own sandbox and approval settings. Everything the agent sends is
cleaned of escape sequences before it is written. Type a prompt and press
Enter to send it; a paste arrives as one prompt. Ctrl+C cancels a turn, and
Ctrl+D on an empty line quits. A permission is shown with a number key per
answer; a key counts once the question has been up for half a second, and a
paste never answers one.

Inside a tuios pane it reports the pane's state under `--harness` (default:
the protocol): `idle`, `working`, `done` or `errored`, and `needs_input` with
kind `approval` for a permission, which it also holds for the Inbox with
`request-approval` when one line shows the whole request. Outside tuios it
reports nothing and works the same. When the agent exits, the pane shows the
end of its stderr and waits for Enter.

It also writes what the agent says about itself to the pane's agent metadata,
under the source `protocol`, each key only when its value changes: `model`
(the model the conversation opened with, from Codex's `thread/start` or ACP's
`session/new` models, and Codex's `model/rerouted`), `context` (tokens in
context of the model's window, from Codex's `thread/tokenUsage/updated` or
ACP's `usage_update`), `cost` (the session's cost from ACP's `usage_update`;
Codex sends none) and `plan` (steps done of the plan's steps, `3/7`). Every
field is optional: one the agent does not send is not written, and every key
is sent again at the start of each turn. Each prompt, tool call and finished
turn also goes to the daemon as `set-agent-state` activity, when the daemon's
`set-agent-state` lists that parameter; the activity changes no state (its
`if_state` is `none`). Both are sent off the pane's input loop. A Codex pane
now shows the turn's plan in the transcript, as an ACP pane does, and an ACP
pane whose agent names its model shows it in the first line, `connected to
opencode 1.2 (Claude Sonnet 4)`, as a Codex pane does.

```bash
tuios agent-proto --protocol acp -- opencode acp
```

### `tuios agent-statusline`

What Claude Code's status line runs once `tuios integration install
claude-code --statusline` is installed: read the status line payload on stdin
and write the model, context use and cost to the pane's agent metadata.

**Usage:**
```bash
tuios agent-statusline claude-code|opencode|kilo [-s SESSION] [-w PANE] [--then CMD] [--turn-end] [--explain] [--timeout D]
```

`-s, --session` names the session of the pane (default: `TUIOS_SESSION`), and
`-w, --window` the pane (default: `TUIOS_PANE_ID`, then the controlling
terminal, then the parent processes).

| Payload field | Metadata key |
| --- | --- |
| `model.display_name`, else `model.id` (Claude Code); `modelID` (opencode, Kilo) | `model` |
| `context_window.used_percentage` (Claude Code) | `context`, as `42%` |
| `cost.total_cost_usd` (Claude Code); `cost` (opencode, Kilo) | `cost`, as `$1.20` |

Every field is optional, and one that is missing, null or of another type is
not written. The keys go under the source `statusline`, with no TTL: they
clear when the agent leaves the pane. It prints nothing of its own. `--then`
runs your own status line command through `sh -c` with the same stdin and
prints its output unchanged, and the command exits with its status. That is
how a status line of your own is kept.

The pane is found from `-w`, then `TUIOS_PANE_ID`, then the process's terminal
and parent processes, as for `agent-hook`; a process in no pane asks the
daemon again at most once a minute. It calls only `set-agent-meta`, for that
pane, at most once every 15 seconds while the values change, and not at all
while they stay the same. A model change, context use crossing 80%, and a
change passed with `--turn-end` (the opencode plugin passes it when the
session goes idle) go at once, and unchanged values are sent again after 10
minutes so a daemon that restarted gets them back. The last values sent, and
any the interval held back, are kept in `statusline-<session>-<pane>.json`
(mode 0600) beside the daemon's socket. Held values go with the next run that
is due, or when the turn ends: Claude Code's `Stop` hook (`tuios agent-hook
claude-code`) sends them, and a run after the `Stop` goes at once. It reads at most 1 MiB of stdin, gives up on the daemon after 300ms
(`--timeout`), and exits 0 whatever goes wrong on the tuios side.

```bash
tuios agent-statusline claude-code --then '~/.claude/statusline.sh'
echo '{"model":{"display_name":"Opus"},"context_window":{"used_percentage":42}}' | tuios agent-statusline claude-code --explain
```

### `tuios kill-server`

Stop the TUIOS daemon process. This stops all sessions.

**Usage:**
```bash
tuios kill-server
```

**Contract:** the command is synchronous. It returns only once the daemon has
written every session's resurrection state and removed its socket, so a script
may start a new daemon as soon as it returns:

```bash
tuios kill-server && tuios start-server   # safe: no race
```

The daemon unlinks its socket last, after the final saves, and that unlink is
what this command waits for. A refused connection is not the same signal: the
daemon closes its listener at the start of shutdown, while state is still
unsaved, so polling the socket for connectivity can report "stopped" before
anything has been persisted.

If the daemon has not finished within 10 seconds the command fails, naming the
pid and the socket, rather than returning success while the old process is still
running. Re-running it re-checks. Force killing with `kill -9` skips the final
save and loses any state written since the last periodic save.

When no daemon is running, the command reports that and removes a stale socket
if one is present. It exits 0 in that case.

`--restart` tells the attached clients that a new daemon follows, so they wait
for it and attach again. Without it the clients quit at once.
`tuios restart-server` passes it.

### `tuios restart-server`

Stop the daemon and start it again with the newest tuios installed. Use it
after an update: the daemon runs the build it started with until it stops.

**Usage:**
```bash
tuios restart-server             # show what stops, ask, then restart
tuios restart-server --dry-run   # show what stops, and change nothing
tuios restart-server --yes       # restart without a question
tuios restart-server --last      # show the steps of the last restart
```

The command first says what a restart does:

```
Daemon now      0.10.0
After restart   0.10.2   (from ~/.local/bin/tuios)

These stop:
  nvim in "edit" (session work)
  claude in "agent" (session work)
Only shells in notes.

These come back:
  Each session, with its layout, its pane history and new shells.
  claude-code in "agent" (session work) can resume.
The Inbox offers to resume each one.
Restart the daemon? [y/N]
```

Then it stops the daemon, starts the new one and waits until it answers:

```
Stopping the daemon...
Starting the daemon 0.10.2...
The daemon restarted on 0.10.2.
These sessions came back: work, notes.
```

- The new daemon runs the newer of two binaries: the tuios at the path of
  this command, which an update replaces, and the `tuios` on PATH, which an
  install in the Nix store, mise, asdf or Linuxbrew moves. `--version`
  decides. When the version after the restart is the daemon's own, the plan
  says "This restart starts the same version."
- The stop is `kill-server`, so every session is saved first. The new daemon
  restores every saved session before it answers.
- The stop and the start run in a process of their own, in a session of its
  own and deaf to SIGHUP. So a restart run in a pane of the daemon it stops
  finishes. Each step goes to `restart.log` beside the daemon log, and
  `--last` shows it.
- One restart runs at a time. A second one refuses while the first runs.
- `daemon.resume_agents` says what the new daemon does with the agent
  conversations: `ask` puts a Resume item in the Inbox, `auto` resumes them,
  and `off` leaves them to `tuios resume-agent`.
- The command asks in every state but a stopped daemon, a daemon that did
  not answer included. With no terminal to ask on, it refuses unless `--yes`
  is given. `--json` needs `--yes`. Nothing is changed when it refuses.
- When the daemon is not running, the command starts it.

The app runs this command from the command palette ("Restart the daemon"),
from the version notice, from the Daemon tab of the settings and from the
rail's menu for this machine. It then starts again in the same session.
Other attached clients wait up to 15 seconds for the new daemon and attach
to their session again. See
[KEYBINDINGS.md](KEYBINDINGS.md#restart-the-daemon).

`--expect DIGEST` refuses the restart unless the plan has that digest. The
app passes the digest of the plan the person agreed to, so a program that
started since makes the restart refuse: "What a restart stops changed after
you agreed to it." Nothing is changed.

`--json` writes one JSON object per line: `plan`, then `stopping`,
`starting` and `done`. The `plan` object holds `binary`, `version`, `daemon`
(with each session's `busy` panes and its `resume` agents) and
`resume_mode`. The `done` object holds `restarted`, `after`, `back` and
`missing`. A failed step sets `error` and `fix`, and the command exits 1.

| Error | Next step |
| --- | --- |
| "The daemon did not stop. It still runs version X." | Run `tuios kill-server` to see why. |
| "The daemon did not start." | Run `tuios start-server` to see why. The sessions come back when the daemon starts. |
| "The daemon started and did not answer." | Run `tuios ls` to check it, or `tuios logs`. |
| "Another restart of the daemon is running." | Wait for it to end. `tuios restart-server --last` shows its steps. |
| "The restart stopped before it finished." | Run `tuios restart-server --last`, then `tuios ls`. |

A restart ends every program running in a pane. To move the daemon to another build with the programs still running, use [`tuios daemon upgrade`](#tuios-daemon-upgrade) instead.

### `tuios daemon`

Run the daemon in the foreground (for debugging).

**Usage:**
```bash
tuios daemon [flags]
```

**Flags:**
- `--log-level <level>`: Debug log level: `off`, `errors`, `basic`, `messages`, `verbose`, `trace`
- `--no-restore`: Do not restore saved sessions on start. Run `tuios resurrect` to restore one on demand

**Debug log levels:**
- `off`: No debug output (default)
- `errors`: Only error messages
- `basic`: Connection events and errors
- `messages`: All protocol messages except PTY I/O
- `verbose`: All messages including PTY I/O
- `trace`: Full payload hex dumps

**Note:** This is primarily for debugging. The daemon starts automatically in the background when you run `tuios new` or `tuios attach`. Use this command to run the daemon in the foreground with debug logging.

### `tuios daemon-app`

macOS only. Write a small app, TUIOS Daemon, that starts the daemon. Panes of
a daemon that the app started keep local network access after the terminal
quits. See [Local Network Access on macOS](SESSIONS.md#local-network-access-on-macos).

**Usage:**
```bash
tuios daemon-app install [--login] [--force] [--binary PATH] [--path PATH]
tuios daemon-app status
tuios daemon-app uninstall [--path PATH]
```

**Flags of `install`:**
- `--login`: Also write a LaunchAgent that opens the app at login
- `--force`: Replace an app that is already there. This removes its Local Network permission
- `--binary <path>`: The tuios that the app starts. The default is the tuios on `PATH`
- `--path <path>`: Where to write the app. The default is `~/Applications/TUIOS Daemon.app`

When the app is installed, each new daemon starts through it. Set
`TUIOS_NO_DAEMON_APP=1` to start a daemon directly.

### `tuios daemon upgrade`

Upgrade the running daemon to another tuios binary in place, without ending any pane's program. Every pane's program keeps running with the same pid, the same terminal and the same screen, and the daemon keeps its pid. Live upgrades are experimental, opt-in, and macOS and Linux only.

**Usage:**
```bash
tuios daemon upgrade [flags]
```

**Flags:**
- `--binary <path>`: The tuios binary to run the daemon as (default: the tuios running the command)
- `--json`: Print the outcome as one JSON object

**Examples:**
```bash
tuios daemon upgrade
tuios daemon upgrade --binary ~/bin/tuios-next
tuios --server test daemon upgrade --binary ./tuios   # upgrades only the daemon named test
```

**Output:**
```
Checking /usr/local/bin/tuios (v0.10.1) accepts this daemon's state (handoff v3)... ok
Paused 4 panes, saved their screens (34.3 KB).
Starting v0.10.1 in place (pid 8615 kept)...
Upgraded in 0.06 s. 4 panes and their programs kept.
```

With attached clients the last line adds how many were told to attach again, such as ` 2 attached clients were told to attach again.` `--json` prints one object with `pid`, `from`, `to`, `binary`, `panes`, `clients`, `seconds`, `fallback`, `recovered`, `instance` and `handoff`, the measurements of the handoff in the shape of `hello`'s `upgrade` field (see [protocol.md](protocol.md#hello)).

**How it runs:**
1. The binary is run once as `<binary> daemon handoff-accepts`, before anything pauses. A binary that does not run, or reads another handoff version, is refused and nothing changes. A tuios from before live upgrades fails this check. Before that run, the command and the daemon refuse a binary owned by neither you nor root, or one its group or others can write. The daemon runs and execs the very file it checked, so renaming a folder on the path afterwards cannot put another file in its place. On Linux it runs the open file. On macOS and other systems it runs a private copy of the file in its own state folder. A script, such as a wrapper, still runs by its path. A binary you cannot read, only run, runs by its path on macOS. For these two, keep the binary in folders no other user can write.
2. The daemon pauses every pane and writes its state down. A chatty program blocks in `write()` for the pause and loses nothing; 60 busy panes with 1000 rows of history each pause for about 0.3 s.
3. Attached clients are told and dropped, and the daemon execs the new binary, which takes the panes over. Calls made during the swap wait in the socket's backlog and the new image answers them.

**What is kept:** sessions and windows as they stand; each pane's screen, the alternate screen with the main one under it, terminal modes (bracketed paste, mouse, kitty keyboard flags), titles and the title stack; the last 1000 rows of history per pane (deeper history is not carried); the folder and branch the shell reported; OSC 133 marks and command history; program status (OSC 7501) and agent state; pane tokens, so `TUIOS_PANE_TOKEN` keeps verifying; agent mailboxes; exit statuses, including a pane that exits during the upgrade; and the event stream's boot id and numbering, so `subscribe`, `stream-pane` and `pane-view` resume.

**What ends:**
- Attached clients are dropped. A tuios client on this machine waits up to 15 seconds for the new image, attaches to its session again by itself, and says `The daemon was upgraded. tuios reattached.` When the new image speaks another wire protocol than the client's build, the client finds it at the handshake, before it attaches, and prints `The daemon is being upgraded to <version>. Your programs are still running. Run 'tuios attach <session>' to continue.` and exits 0. It prints the same when no new image takes the session back within the wait, and so does a client attached to another machine's session. SSH and web clients say to connect again. A client from a build without live upgrades reports the daemon as lost. `tuios pane-view` reconnects on its own.
- A JSON verb call that was running or waiting (`wait-for`, a waiting popup, `ask-agent`) ends with `daemon_upgrading`. Call it again; the new image answers.
- Size leases end with their connection. Plugins and links to other machines are stopped and started again by the new image, and links redial.
- A pane's `close_on_exit` is not carried: after the upgrade, a window whose program exits with no client attached stays open.

**Refusals:** the command exits 1 with `upgrade_refused` and nothing changes when the daemon runs on Windows, is embedded in another program (`tuios-web`, the SSH server), holds panes hosted here for another machine or a window whose process runs on another machine, is running a `tuios fan verify` check, or is running a popup with `capture_stdout`. A second upgrade while one runs is refused as `busy`. Run from inside a pane, the upgrade waits for the person: every attached client shows a dialog with the binary's full path, its version, and the pane that asked by its title, id and session. No is the default, and only a key pressed at a client answers it: Down or Right moves to Yes, any other key, Tab included, moves back to No, and Enter chooses. The first answer closes the dialog on the other clients. No, Esc, 60 seconds without an answer, no client attached that shows the dialog (a view-only client, a `gui-bridge` renderer and a client too old for the dialog do not), or the agent features turned off refuses it with `forbidden` and `daemon-upgrade is for the person`, followed by which of these it was and what to do, and nothing changes. A plugin is refused the same way without a dialog. A daemon from before live upgrades answers `unknown_verb`, and the command says to restart it with `tuios restart-server`, which stops every program in every pane. On Windows, `tuios restart-server` is the way to move to another build.

**Fallback:** at start the daemon keeps the binary it runs at `<state>/handoff/tuios.prev` (a hard link, or a copy across file systems; one per server). If the new binary starts and cannot take the panes over (an error, a panic, or a 30 second watchdog), the daemon execs `tuios.prev`, which takes them back. The command then says the new binary could not take the panes over and the daemon went back to the old version, that every program is still running, to see `tuios logs`, and exits 1.

**Crash of the new binary:** before any pane pauses, the daemon starts a keeper, `tuios.prev daemon handoff-keeper`, that holds a copy of every pane's terminal, the sockets and the start lock until the new image is up, then exits. If the new image dies first (a crash, the out-of-memory killer, `SIGKILL`), the keeper runs `tuios.prev` in its own place, which takes the panes back: every program keeps running with the same pid, and the daemon comes back under the keeper's pid. The command says the new binary died before it was up and names both pids, and `--json` has `recovered` and `fallback` set; it exits 1. The daemon brought back this way is not the parent of the programs it took back: it still learns when one ends, with its exit status on macOS and without it (`-1`) on Linux. If the new image had already started reading the panes when it died, what it read is lost from their screens. A daemon stopped on purpose (`kill-server`) during the upgrade is not brought back.

The design is in [design/live-handoff.md](design/live-handoff.md). What each kind of restart keeps is in [SESSIONS.md](SESSIONS.md#what-survives).

### Workflow Example

```bash
# Start a new session for work
tuios new work

# ... do some work, then detach with Ctrl+B d ...

# Later, list your sessions
tuios ls

# Reattach to continue working
tuios attach work

# When done, kill the session
tuios kill-session work
```

---

## Remote Control Commands

TUIOS provides commands to control a running session from external scripts and tools. These commands communicate with the TUIOS daemon to send keystrokes, execute commands, and query state. This enables powerful scripting, automation, and integration with external tools.

> **Note:** When sending TUIOS commands via `send-keys`, `Ctrl+B` refers to the default leader key. This is configurable via the `leader_key` option in your config file.

### `tuios send-keys`

Send keys to the program in a window: arrows, page keys, Enter, `ctrl+c`.

With `-w` the keys go to that window's terminal, whether or not a client is
attached and whichever window has the focus. Without `-w` they go to the
attached client as if the person pressed them, which drives the window manager
or the focused window; with no client attached they go to the focused window.

From inside a pane, `-w` is required. A pane does not send keys into a pane
that waits on a prompt (`needs_input`). To answer that prompt, pass
`--allow-blocked`. It also needs the `respond` grant. You, outside every pane,
are held to neither rule.

**Usage:**
```bash
tuios send-keys <keys> [flags]
```

**Flags:**
- `-s, --session <name>`: Target session (default: this pane's session, else the most recently active)
- `-w, --window <target>`: Target window: full id, the index `list-windows` prints, the exact name, or a unique id prefix (default: the attached client, else the focused window)
- `-N, --repeat <n>`: Send the whole sequence n times, 1 to 1000 (default 1)
- `-l, --literal`: Write the argument to the window's terminal unchanged, with no key names
- `-r, --raw`: Treat each character as a separate key (no splitting on space/comma)
- `--allow-blocked`: From a pane, send keys into a pane that waits on a prompt. Read the prompt first
- `--json`: Output the result as JSON

**Output:**
Where the keys went:

```
sent 5 keys to window docs (3a42ab8f)
```

or `sent 2 keys to the attached client (...)` without `-w`. `--json` gives
`sent_to` (`window` or `client`), `keys`, and for a window `window_id` and
`window`.

**Keys:** the argument is split on spaces and commas. Names are
case-insensitive.

| Key | Name | Other spellings that work |
| --- | --- | --- |
| Arrows | `Up` `Down` `Left` `Right` | `up`, `UP`, `arrow-up`, `ArrowUp`, `up-arrow`, `KEY_UP`, `<Up>` |
| Page keys | `PageUp` `PageDown` | `PgUp`, `PgDn`, `Page_Down`, `NPage`, `PPage`, `KEY_NPAGE` |
| Line ends | `Home` `End` | `KEY_HOME`, `<End>` |
| Enter | `Enter` | `Return`, `CR`, `KEY_ENTER` |
| Escape | `Escape` | `Esc` |
| Editing | `Tab` `BTab` `Space` `Backspace` `Delete` `Insert` | `shift+Tab`, `BSpace`, `BS`, `Del`, `DC`, `Ins`, `IC` |
| Function keys | `F1` to `F12` | `f5`, `KEY_F5` |
| A character | `q` `j` `G` `/` | any single character |
| With modifiers | `ctrl+c` `alt+b` `shift+Up` `ctrl+Right` | `C-c`, `M-b`, `S-Up`, `^C`, `Ctrl+C` |
| A raw sequence | `\e[A` | `\x1b[A`, `\033[A`, `^[[A` |
| The leader key | `PREFIX` | `$PREFIX`; only without `-w`, with a client attached |

Arrows, `Home` and `End` are sent in the form the program asked for
(application cursor keys). A named key or a key with modifiers is encoded
the way the client encodes it for a person: a program that asked for the
kitty keyboard protocol or modifyOtherKeys gets that encoding. Text stays
text. A word that looks like a key but is not one (`Dwon`,
`KEY_FOO`, `F13`) is refused with the key names and the closest one, and
nothing is sent. A plain lower-case word such as `ls` is typed as its letters.

**send-keys is not for text.** `send-keys 'echo hello'` types `echohello`. Use
[`tuios send-text`](#tuios-send-text).

**Examples:**
```bash
# Scroll the pager in the window named docs
tuios send-keys -w docs Down
tuios send-keys -w docs Down --repeat 10
tuios send-keys -w docs 'PageDown PageDown'

# Interrupt what runs in the window named build
tuios send-keys -w build ctrl+c

# A window by the id new-window printed
id=$(tuios new-window logs --print-id)
tuios send-keys -w "$id" End

# Keys for the window manager: the leader key and then q, no -w
tuios send-keys "ctrl+b q"
tuios send-keys "\$PREFIX q"

# Enter terminal mode in the attached client (press 'i')
tuios send-keys i
```

### `tuios send-text`

Write text verbatim to a pane's PTY, with no key parsing at all.

Nothing in the argument is interpreted, so spaces, quotes and punctuation
arrive as typed. A trailing newline is the Enter that runs the line, which
makes this one call where `send-keys` needs two.

From inside a pane, `-w` is required, and a pane does not type into a pane on
`needs_input` without `--allow-blocked`, as for `send-keys`.

**Usage:**
```bash
tuios send-text <text> [flags]
```

**Flags:**
- `-s, --session <name>`: Target session (default: this pane's session, else the most recently active)
- `-w, --window <id-or-name>`: Target window (default: focused)
- `--allow-blocked`: From a pane, type into a pane that waits on a prompt. Read the prompt first
- `--json`: Output the result as JSON. Without it the command prints nothing, and a failure exits `1`

**Examples:**
```bash
# Run a command in the focused pane (the trailing newline submits it)
tuios send-text 'go build ./...
'

# Type without submitting
tuios send-text -w build 'partial input'

# Text with spaces, quotes and commas needs no flags
tuios send-text -w build 'git commit -m "fix: cache, retries"'
```

### `tuios list-buffers`, `show-buffer`, `set-buffer`, `delete-buffer`, `paste-buffer`

Read and change the paste buffers, as the tmux commands of the same names do.
A yank in copy mode adds a buffer. The daemon keeps the buffers, so every
client and session on this machine shares them. `[paste_buffers]` sets how
many to keep.

**Usage:**
```bash
tuios list-buffers [--json]
tuios show-buffer [-b <name>] [--json]
tuios set-buffer [-b <name>] [-a] [<text> | -] [--json]
tuios delete-buffer [-b <name>] [--json]
tuios paste-buffer [-b <name>] [-s <session>] [-w <window>] [-d] [-r] [--allow-blocked] [--json]
```

**Flags:**
- `-b, --buffer <name>`: The buffer (default: the newest buffer that tuios named, as in tmux). For `set-buffer`, the default is a new buffer named `bufferN`
- `-a, --append`: `set-buffer` adds the text to the end of the named buffer. With no `-b`, it makes a new buffer, as in tmux
- `-s, --session`, `-w, --window`: The pane `paste-buffer` pastes into (default: the focused pane)
- `-d, --delete`: `paste-buffer` deletes the buffer after the paste, unless it was set again meanwhile
- `-r, --raw`: `paste-buffer` keeps each line feed. Without it, each line feed becomes a carriage return, as in tmux
- `--allow-blocked`: From a pane, `paste-buffer` pastes into a pane that waits on a prompt
- `--json`: Output the result as JSON

A buffer can hold any bytes, a binary file included. `show-buffer` prints the
content with no line feed added. `set-buffer -` reads the standard input. With
no text on a terminal, `set-buffer` stops and says how to give it. `paste-buffer` removes control
characters and uses the bracketed paste marks when the program in the pane
turned them on. With a session on another machine, `paste-buffer` sends the
text of a buffer from this machine.

From inside a pane, reading the buffers needs the `read` grant, changing them
needs `write`, and `paste-buffer` needs both. A buffer a pane without `admin`
sets is that pane's own, and such a pane reaches only its own buffers. It
cannot make a named buffer. With no `-b`, your own commands take the newest
of your own buffers, never one a pane set. `set-buffer` with
empty text stores nothing and exits 0, as tmux does. Input longer than 64 MiB
is refused, and nothing is stored.

**Examples:**
```bash
# What can be pasted again
tuios list-buffers

# Keep a command, and paste it into the ops pane later
tuios set-buffer -b deploy 'kubectl rollout restart deploy/api'
tuios paste-buffer -b deploy -w ops

# Store the output of a command
git log -1 --format=%H | tuios set-buffer
```

### `tuios new-window`

Open a new window in a session and print its id.

The window is created by the daemon whether or not a client is attached, so
this works on a detached session. Give it a name to address it later without
holding on to the id.

**Usage:**
```bash
tuios new-window [name] [command...] [flags]
```

Words after the name are the argv the window runs instead of a shell, with no
shell in between: `tuios new-window htop /usr/bin/htop`. Put `--` before a
command that has flags of its own, or tuios reads them as its own flags:
`tuios new-window log -- git log --oneline -20`.

**Flags:**
- `-s, --session <name>`: Target session (default: this pane's session, else the most recently active)
- `--workspace <n>`: Workspace to open the window on (default: the calling pane's workspace, else the one the session shows)
- `--cwd <dir>`: Directory to start the shell in (default: the daemon's)
- `--no-focus`: Leave the focus where it is
- `--host <name>`: Run the window's process on this machine from the `[hosts]` table (default: this machine)
- `--grants <grant>[,<grant>...]`: What the window's process may do through tuios: `read`, `write`, `fan`, `respond`, `admin`, or `none` (default: `[agents.permissions]`). See [`tuios pane-grants`](#tuios-pane-grants)
- `--json`: Output result as JSON
- `--print-id`: Print only the new window's full id
- `--keep-open`: Keep the window after its program exits. The window shows a line with the exit status under the last output
- `--wait`: Wait for the program to exit, print nothing, and exit with its status. A program that a signal stopped gives 128 plus the signal number
- `--timeout <ms>`: With `--wait`: milliseconds to wait before failing (default: no limit)

**Output:**
The 8-character window id and the window's name, separated by two spaces:

```
a1b2c3d4  build
```

That id prefix, and the name, are what `-w` accepts everywhere else. With
`--print-id` the output is the full id alone, for `id=$(tuios new-window build --print-id)`.

**Examples:**
```bash
# Open an unnamed window
tuios new-window

# Open a named window and run something in it
tuios new-window build
tuios send-text -w build 'go build ./...
'

# Run the tests beside you, and read the output if they fail
tuios new-window tests --no-focus --keep-open --wait -- go test ./... ||
  tuios capture-pane -w tests --scrollback

# Capture the new window's id for scripting
id=$(tuios new-window build --print-id)
tuios new-window --json | jq -r .window_id

# JSON output carries the full id and the name
tuios new-window --json build
# Output: {"focused":true,"host":"","message":"command executed","name":"build","pty_id":"8fe359af-0f9e-4efe-9595-7b1d3467dc50","success":true,"unplaced":true,"window_id":"a6e55709-071e-4345-9363-ff4ef0a63c02","workspace":1}

# Target a specific session
tuios new-window -s mysession dev
```

### `tuios popup`

Run a command in a floating pane centred over the layout, and print its id.

The pane closes when the command exits. Nothing re-parses the arguments after
`--`, so nothing needs quoting. This is how a picker becomes an overlay: run
fzf, gum or any other full-screen program in it.

It needs an attached client, because a popup is a thing on a screen. The pane is
not tiled, it is not in the window cycle, and it cannot be minimized.

The popup writes to its own screen, not to this command's output. With
`--wait` this command stays open until the popup's command exits and exits
with its status (130 when the popup was closed by hand). With
`--capture-stdout`, which implies `--wait`, the command's standard output
comes here instead of into the popup: a picker such as fzf or gum draws on the
terminal and prints only the choice, so the choice is what this command
prints. Capture is not supported on Windows. Without either, redirect inside
the popup or send the selection to another pane.

**Usage:**
```bash
tuios popup [flags] -- <command> [args...]
```

**Flags:**
- `-s, --session <name>`: Target session (default: this pane's session, else the most recently active)
- `--width <size>`: Width in cells (`60`) or percent (`60%`). Default `80%`
- `--height <size>`: Height in cells (`20`) or percent (`50%`). Default `60%`
- `--dim <percent>`: Dim the screen behind this popup by `0` to `90` percent. Omit to inherit `appearance.popup_dim` (default `0`); explicit `--dim 0` turns it off

Neither size flag has a short form: `-w` selects a window everywhere else, and
`-h` is help.
- `--name <name>`: Name for the popup
- `--cwd <dir>`: Directory to run the command in
- `--workspace <n>`: Workspace to open the popup on
- `--wait`: Stay open until the command exits, and exit with its status
- `--capture-stdout`: Print the command's standard output here instead of in the popup (implies `--wait`)
- `--timeout <ms>`: With `--wait`, milliseconds to wait before failing with `timeout`; the popup stays open (default: as long as it is open)
- `--json`: Output result as JSON

A size larger than the pane region is cut down to the region.

Dimming applies only while the popup has focus and leaves the popup lit.
A TML popup inherits `appearance.modal_dim` unless overridden.

**Lifetime:**

A popup lives as long as its command. Detaching leaves it running, and it is
still there on the next attach. A daemon restart does not bring it back: the
restore respawns a shell rather than the command, which is not the popup. Press
esc in window mode to close one by hand, or close it like any other pane.

To keep shells in a box between shows, use the scratch terminal
(`Ctrl+B g`), a small layout of panes. It comes back hidden after a daemon
restart. See
[SESSIONS.md](SESSIONS.md#the-scratch-terminal). To put a command in a popup
on a key of its own, use a `[[keybindings.command]]` entry. See
[KEYBINDINGS.md](KEYBINDINGS.md#command-keys).

**Examples:**
```bash
# Pick a file in a centred popup and use the answer
file=$(tuios popup --capture-stdout -- fzf)

# Wait for a confirmation and branch on it
tuios popup --wait -- gum confirm "Deploy?" && ./deploy.sh

# Keep the answer in a file instead
tuios popup -- sh -c 'ls | fzf > /tmp/pick'

# Send the selection straight to the pane you came from
tuios popup -- sh -c 'tuios send-text -w main "$(ls | fzf)"'

# A small popup, in cells
tuios popup --width 60 --height 20 -- gum choose one two three

# Watch something, then press q to close it
tuios popup --width 90% --height 80% -- htop

# Dim the background while choosing
tuios popup --dim 30 -- gum choose one two three

# Capture the popup's id for scripting
tuios popup --json -- fzf | jq -r .window_id
```

### `tuios xpanes`

Open one pane per item in a new tiled workspace, and turn multifocus on for
all of them. Then the keys you type go to every pane. This is like
[tmux-xpanes](https://github.com/greymd/tmux-xpanes).

**Usage:**
```bash
tuios xpanes [flags] [items...]
command | tuios xpanes [flags]
```

The items are the arguments. With no arguments, tuios reads one item from each
line of stdin, when stdin is not a terminal. tuios ignores empty lines.

**Flags:**
- `-c, --command <cmd>`: Command for each pane. tuios replaces `{}` with the item, in shell quotes
- `-s`: Speedy mode. The pane runs the command with `sh -c`, with no interactive shell, and stays until you press Enter
- `-ss`: Speedy mode. The pane closes when the command stops
- `--interval <seconds>`: Time to wait between the panes, for example `0.5`
- `-I, --replace <text>`: Text that tuios replaces with the item (default: `{}`)
- `--ssh`: Run `ssh` with the item in each pane. This is the same as `-s -c 'ssh -- {}'`. The `--` makes sure that ssh does not read an item that starts with `-` as an option. Add `-ss` to close each pane when its ssh stops
- `-l, --layout <name>`: `tiled`, `even-horizontal` or `even-vertical`, or `t`, `eh` and `ev` (default: `tiled`)
- `-n, --items-per-pane <n>`: Number of items for each pane. tuios joins them with spaces (default: 1)
- `--no-sync`: Do not turn multifocus on
- `--workspace <n>`: Workspace for the panes. It must be empty (default: the first empty workspace)
- `--session <name>`: Session for the panes (default: the session of this pane, else the most recently active). It has no short form, because `-s` is speedy mode, as in tmux-xpanes
- `--force`: Open more than 64 panes
- `--json`: Output the result as JSON

**Panes:**

- Each pane starts a shell. With `-c`, tuios types the command into the shell
  of that pane and presses Enter. tuios waits until the shell shows its
  prompt, for at most 10 seconds. The shell stays when the command stops.
  tmux-xpanes does the same. This works with and without a client attached.
- With `-s`, the pane runs the command with no shell. When the command stops,
  the pane shows "The command stopped. Press Enter to close the pane." Press
  Enter to close it. With `-ss`, the pane closes when the command stops.
- With `--interval`, tuios waits between the panes. With `-s` or `-ss`, it
  waits between opening the panes, because each command starts with its pane.
  Without them, it opens all the panes and waits between typing the commands.
- Without `-c`, each pane is a shell. In a session on another machine, the
  daemon there chooses the shell, and the pane does not get
  `TUIOS_XPANES_ITEM` or `TUIOS_XPANES_INDEX`.
- Each pane gets the item in `TUIOS_XPANES_ITEM` and its number, from 1, in
  `TUIOS_XPANES_INDEX`.
- The item is the name of the pane.
- The panes start in the folder where you run `tuios xpanes`.

**Layout and multifocus:**

tuios shows the new workspace and lays out the panes in item order. `tiled` is
a grid. `even-horizontal` puts the panes side by side. `even-vertical` puts
them one above the other.

The layout and multifocus need a client attached to the session. The layout
also needs tiling on and the `bsp` layout. When tuios cannot do one of them,
it opens the panes and tells you what it did not do.

**When the panes close:**

tuios remembers the workspace where you ran `tuios xpanes`. From inside a
pane, it is the workspace of that pane. From outside, it is the workspace on
screen. When the last pane of the xpanes workspace closes, tuios shows that
workspace again, if it still has panes. Set `workspaces.return_when_empty` to
`false` to stay on the empty workspace. See
[CONFIGURATION.md](CONFIGURATION.md#when-a-workspace-becomes-empty).

`tuios xpanes` uses the verbs `list-workspaces`, `select-workspace`,
`new-window`, `send-text` and `run-command`. The two client commands `ArrangePanes` and
`SetMultifocus` also work alone with
[`tuios run-command`](#tuios-run-command).

**Examples:**
```bash
# Three ssh sessions, and type into all of them at the same time
tuios xpanes --ssh host1 host2 host3

# Items from stdin, one command for each
printf 'a\nb\nc\n' | tuios xpanes -c 'echo {}'

# No shell, one second apart, and each pane closes when curl stops
tuios xpanes -ss --interval 1 -c 'curl -s https://{}/health' web1 web2 web3

# Close all the panes when you are done
tuios close-workspace 2

# Follow logs side by side, without multifocus
ls /var/log/*.log | tuios xpanes -l even-horizontal --no-sync -c 'tail -f {}'

# Two items for each pane
tuios xpanes -n 2 -c 'diff {}' a.txt b.txt c.txt d.txt
```

### `tuios close-window`

Close one pane and stop its program. Name the pane by its name, its id or the
number `list-windows` prints. It works with no client attached.

**Usage:**
```bash
tuios close-window [flags] <window>
```

**Flags:**
- `-s, --session <name>`: Target session (default: the session of this pane, else the most recently active)
- `--json`: Output the result as JSON

**Examples:**
```bash
# Close the pane named build
tuios close-window build

# Close a pane by id in the session work
tuios close-window -s work 86e5e19f
```

### `tuios clear-history`

Clear the scrollback of a pane, as tmux `clear-history` does. The screen
stays. With `--screen`, tuios also removes the rows above the prompt, as
`cmd+k` does in Ghostty and iTerm2. The prompt row then moves to the top of
the pane.

The daemon clears the pane for every client of the session. An attach later
does not bring the old rows back. tuios clears nothing while a full-screen
program, such as an editor, uses the pane. The `clear_scrollback` key does the
same as `--screen`. See [KEYBINDINGS.md](KEYBINDINGS.md#clear-the-scrollback).

**Usage:**
```bash
tuios clear-history [flags]
```

**Flags:**
- `-s, --session <name>`: Target session (default: the session of this pane, else the most recently active)
- `-w, --window <window>`: Target window by name or ID (default: the focused pane)
- `--screen`: Also remove the rows above the prompt
- `--json`: Output the result as JSON

**Examples:**
```bash
# Clear the scrollback of the focused pane
tuios clear-history

# Clear the scrollback and the screen of the pane named build
tuios clear-history -w build --screen
```

### `tuios close-workspace`

Close every pane on a workspace, like tmux `kill-window`. Without a number,
tuios closes the panes of the current workspace.

**Usage:**
```bash
tuios close-workspace [flags] [workspace]
```

**Flags:**
- `-s, --session <name>`: Target session (default: the session of this pane, else the most recently active)
- `--json`: Output the result as JSON

Scratch panes stay open. To close a scratch group, name its scratch workspace.
When the workspace goes, the workspaces above it move down one. See
[CONFIGURATION.md](CONFIGURATION.md#workspace-numbers). A pane that runs this
command needs the `admin` grant. The
`close_workspace` action does the same from the keyboard, and the `Close` row of
a workspace tab's right-click menu in the dock does it for that tab's workspace.
See [KEYBINDINGS.md](KEYBINDINGS.md#close-every-pane-on-a-workspace).

**Examples:**
```bash
# Close the panes that tuios xpanes opened on workspace 2
tuios close-workspace 2

# Close the panes of the current workspace
tuios close-workspace
```

### `tuios ask-human`

Ask the person a question with a fixed set of answers, wait for them to pick
one, and print it.

**Usage:**
```bash
tuios ask-human [flags] <question> -o <answer> [-o <answer>...]
tuios ask-human --request-id <id>
```

The question goes in the Inbox as a row under Questions. A client that shows the
asking pane opens the Inbox on it at once, unless the person is typing into
the pane or has an overlay open, and the digits 1 to 9 pick an answer once it
has been on screen for a moment; from any other pane it waits there with the usual alert, and with
nobody attached it waits for the next attach. Only the person at an attached
client can answer; an agent cannot.

When `--timeout` runs out first, the command exits `2` and the question stays.
The answer is then mailed to the asking pane from `human`, marked
`verified_human`, so `tuios wait-for agent-message` picks it up; or come back
with `--request-id`. From inside a pane the question is asked as that pane,
and naming another is refused. An answer to a call that was killed while it
waited is mailed the same way. A caller whose tool stops commands after a
while (two minutes for many agent harnesses) keeps `--timeout` below that, or
asks with `--no-wait` and waits with `tuios wait-for agent-message`.

**Flags:**
- `-s, --session <name>`: Target session (default: this pane's session, else the most recently active)
- `-w, --window <id-or-name>`: The pane asking, where a late answer is mailed (default: your own pane; none from outside every pane)
- `-o, --option <answer>`: An answer the person can pick; give 1 to 9, each one line of at most 60 bytes
- `--timeout <ms>`: Milliseconds to wait for the answer (default: 120000, at most one hour)
- `--no-wait`: Ask and return at once, exit `2`; the answer arrives as mail
- `--request-id <id>`: Come back for a question already asked
- `--json`: Output the result as JSON: `request_id`, `status`, `answer`, `answer_index`, `answered_by`, `verified_human`

The question is one line of printable text, at most 160 bytes. For a longer
question, send the details to the person with `tuios send-agent-message -w human`,
then ask a short question.

While a call from inside a pane waits, that pane shows `needs_input` with the
question as its note. When the call returns, the pane shows its earlier state
again, or the state the pane reported while the call waited. A pane already on
`needs_input` keeps its own prompt. A question from outside every pane changes
no pane's state.

**Exit status:** `0` with the answer alone on stdout; `2` when there is no
answer yet; `1` when the question ended without one (dismissed, superseded by
a newer question from the same pane, or its pane closed).

**Examples:**
```bash
# Ask, and branch on the answer
if [ "$(tuios ask-human 'Deploy to staging?' -o yes -o no)" = yes ]; then ./deploy.sh; fi

# Ask and move on; the answer arrives as mail
tuios ask-human 'Which region?' -o us -o eu --no-wait

# Come back for an answer
tuios ask-human --request-id 9f86d081884c7d65
```

### `tuios run-command`

Execute a TUIOS command (same commands available via tape scripts).

**Usage:**
```bash
tuios run-command <command> [args...] [flags]
```

**Flags:**
- `-s, --session <name>`: Target session (default: this pane's session, else the most recently active)
- `--json`: Output result as JSON (useful for scripting)
- `--list`: List all available commands

`run-command` sends a client protocol message, so from inside a pane it needs
the `admin` grant (see [`tuios pane-grants`](#tuios-pane-grants)). Under the
default `mode = "open"` every pane holds `admin`. Prefer a verb where one
exists: `tuios get-window` and `tuios list-windows` read windows with `read`.

**Available Commands:**

`tuios run-command --list` prints this list from the binary.

| Command | Arguments | Description |
|---------|-----------|-------------|
| `NewWindow` | `[name]` | Create a new terminal window |
| `CloseWindow` | `[name]` | Close the focused window, or every window with that name |
| `NextWindow` | | Focus the next window |
| `PrevWindow` | | Focus the previous window |
| `FocusWindow` | `<name>` | Focus a window by name |
| `RenameWindow` | `<name>` or `<old> <new>` | Rename the focused or a named window |
| `MinimizeWindow` | `[name]` | Minimize the focused or a named window |
| `RestoreWindow` | `[name]` | Restore the focused or a named window |
| `TerminalMode` | | Switch to terminal mode |
| `WindowManagementMode` | | Switch to window management mode |
| `ToggleTiling`, `EnableTiling`, `DisableTiling` | | Turn tiling mode on or off |
| `SnapLeft`, `SnapRight`, `SnapFullscreen` | | Snap the focused window |
| `Split` | `horizontal`, `vertical`, `left`, `right`, `up` or `down` | Split the focused window. A side names where the new window goes |
| `RotateSplit` | | Rotate the split direction |
| `EqualizeSplits` | | Equalize all split ratios |
| `SetMasterPosition` | `left`, `right`, `top`, `bottom` or `center` | Put the master panes of the current workspace on that side. With `center`, the stack is on both sides |
| `SetMasterCount` | `1`-`9` | Set how many panes of the current workspace are master panes |
| `CycleMasterPosition` | | Move the master panes to the next side |
| `AddMaster`, `RemoveMaster` | | Make one more pane, or one pane fewer, a master pane |
| `SwapWithMaster` | | Swap the focused pane with the master pane. Needs the master-stack layout |
| `FocusMaster` | | Focus the master pane. Needs the master-stack layout |
| `ArrangePanes` | `<layout> [workspace [window...]]` | Lay out the panes of the workspace again as `tiled`, `even-horizontal` or `even-vertical`. The named windows come first, then the other panes in window order. With a workspace, the command fails when that workspace is not showing. Needs the bsp layout |
| `SetMultifocus` | `[window...]` | Put exactly these windows in multifocus. Each window must be on the showing workspace and not minimized. From a pane, each window must be one that the pane can type into. With no window, clear multifocus |
| `Screenshot` | | Save the focused window as an image |
| `SwitchWorkspace` | `<1-9>` | Switch to workspace |
| `MoveToWorkspace` | `<1-9>` | Move focused window to workspace |
| `EnableAnimations`, `DisableAnimations`, `ToggleAnimations` | | Turn UI animations on or off |
| `SetDockbarPosition` | `<position>` | Set dockbar position (top/bottom/hidden) |
| `SetBorderStyle` | `<style>` | Change window border style |
| `SetTheme` | `<theme>` | Change the color theme |
| `ShowNotification` | `<message> [type]` | Show a notification |
| `ListWindows`, `GetWindow [id-or-name]`, `GetSessionInfo` | | The older spellings of `list-windows`, `get-window` and `session-info`, which are the ones to use |

**Examples:**
```bash
# List all available commands
tuios run-command --list

# Create a new window
tuios run-command NewWindow "my-terminal"

# Create window and get JSON output with window ID
tuios run-command --json NewWindow "my-terminal"
# Output: {"message":"command executed","name":"my-terminal","success":true,"window_id":"75684348-98ba-4e60-a9c4-0b1e1920b25e"}

# Switch workspace
tuios run-command SwitchWorkspace 2

# Toggle tiling
tuios run-command ToggleTiling

# Close focused window
tuios run-command CloseWindow

# Target a specific session
tuios run-command -s mysession NewWindow "dev"
```

### `tuios set-config`

Change TUIOS configuration at runtime.

**Usage:**
```bash
tuios set-config <path> <value> [flags]
```

**Flags:**
- `-s, --session <name>`: Target session (default: this pane's session, else the most recently active)
- `--json`: Output the result as JSON: `key`, `value`, `applied`, and `reason` when `applied` is false

With a client attached, the client applies the value and writes it to
`config.toml`. With no client attached, the daemon keeps the value for the
session. The next client that attaches applies it and writes it to
`config.toml`. The command still prints `Set PATH = VALUE` on stdout, and says on
stderr that the value is not applied yet. `agents.enabled` is the person's
switch: a process in a pane cannot set it.

**Paths:** every option `tuios list-options` prints can be set, by its full
path (`appearance.dockbar_position`) or, for an `[appearance]` option, by its
name alone. Some of them:

| Path | Values | Description |
|------|--------|-------------|
| `dockbar_position` | `bottom`, `top`, `hidden` | Dockbar position (default `top`) |
| `dock_compact` | `true`, `false` | Draw the dock as one row with no rule (default `false`) |
| `dock_mode_icon_window` | text, `""` or `default` | Icon in the mode pill in window mode. An empty value shows no icon. `default` uses the icon of the glyph set |
| `dock_mode_icon_terminal` | text, `""` or `default` | Icon in the mode pill in terminal mode |
| `dock_mode_icon_tiling` | text, `""` or `default` | Icon in the mode pill while tiling is on |
| `dock_mode_pill` | `tiling`, `input` | What the mode pill shows while tiling is on: the tiling icon, or the terminal or window icon (default `tiling`) |
| `dock_prefix_indicator` | `pill`, `badge` | Where the dock shows an armed leader key (default `pill`) |
| `theme_light` | a theme id, or empty | The theme while the terminal is light. `theme` is then the dark theme (default empty) |
| `border_focused_gradient` | two or more colours, or empty | Colours the focused pane's border blends through (default empty) |
| `border_gradient_angle` | `0` to `359` | Direction of the gradient in degrees (default `45`) |
| `window_title_style` | `pill`, `tab`, `plain` | Shape of a pane's title (default `pill`) |
| `window_title_align` | `auto`, `left`, `center`, `right` | Place of a pane's title on its row (default `auto`) |
| `sidebar.row_style` | `bar`, `marker`, `underline`, `pill` | How the rail marks the row you are on (default `bar`) |
| `sidebar.header_style` | `auto`, `plain`, `rule`, `pill`, `icon` | How a rail section header is drawn (default `auto`) |
| `sidebar.density` | `normal`, `roomy` | Space between the rail's sections (default `normal`) |
| `border_style` | `rounded`, `normal`, `thick`, `double`, `block`, `outer-half-block`, `inner-half-block`, `ascii`, `hidden`, `glyphs` | Border style |
| `motion` | `none`, `basic`, `full` | How much moves: `basic` keeps window slides and the copy sweep, `full` (the default) adds the overlay fade-in and the working-agent shimmer |
| `theme_transition` | `none`, `circle`, `fade` | How a theme change shows: `circle` grows the new theme from the middle of the screen, `fade` changes all cells at the same time (default `none`) |
| `theme_transition_duration` | `100` to `2000` | Milliseconds a theme transition takes (default `450`) |
| `dim_unfocused` | `0` to `90` | Percent the content of a pane you are not in is dimmed (default `0`, off) |
| `dim_foreground` | `true`, `false` | Let `dim_unfocused` dim the text of a pane you are not in as well as its background (default `true`). `false` keeps the text at full strength and dims only the background |
| `dim_multifocus` | `true`, `false` | Dim the panes in the multifocus set like other panes you are not in (default `false`) |
| `modal_dim` | `0` to `90` | Percent the screen behind a modal panel is dimmed (default `30`, `0` is off). On a light ground the screen fades toward its own background instead of darkening |
| `popup_dim` | `0` to `90` | Percent the screen behind a focused plain popup is dimmed (default `0`, off). `popup --dim` overrides it |
| `animations_enabled` | `true`, `false` | Deprecated on/off switch: `false` sets `motion` to `none`, `true` to `full` |
| `hide_window_buttons` | `true`, `false` | Hide window buttons |
| `window_button_style` | `pill`, `dots` | How the window controls are drawn. On the left, the pill order is close, zoom, minimize, so close sits at the outer corner |
| `window_button_position` | `right`, `left` | Which end of the title bar they sit on |
| `background` | `off`, `theme`, a colour | Background painted on every surface not set on its own: panes, desktop, window chrome, dock and rail (default `off`) |
| `pane_background` | `off`, `theme`, a colour, or empty | Background behind pane content where the program left the default; empty follows `background` |
| `desktop_background` | `off`, `theme`, a colour, or empty | Background behind and between panes; empty follows `background` |
| `window_chrome_background` | `off`, `theme`, a colour, or empty | Background under pane borders and title bars, which keep their own ink; empty follows `background` |
| `dock_background` | `off`, `theme`, a colour, or empty | Background under the dock; empty follows `background` |
| `appearance.sidebar.background` | `off`, `theme`, a colour, or empty | Background under the rail; empty follows `background` |
| `hints.all_panes` | `true`, `false` | The hints key puts labels on all panes on the workspace, not only on the focused pane (default `false`) |
| `scratch.width` | cells (`100`) or percent (`80%`) | Width of the scratch terminal that `Ctrl+B g` shows (default `80%`) |
| `scratch.height` | cells (`30`) or percent (`80%`) | Height of the scratch terminal (default `80%`) |
| `daemon.window_size` | `latest`, `smallest`, `largest` | The client whose size the session uses: the client that last had input (default), the smallest, or the largest. The daemon applies it to the session at once. It is not saved to the config file |

**Examples:**
```bash
# Change dockbar position
tuios set-config dockbar_position bottom

# Change border style
tuios set-config border_style rounded

# Turn animations off
tuios set-config motion none

# Hide window buttons
tuios set-config hide_window_buttons true
tuios set-config window_button_style dots
tuios set-config window_button_position left

# Paint the theme's background behind pane content, or a colour of your own
tuios set-config pane_background theme
tuios set-config pane_background '#1e1e2e'

# Paint every surface at once, then give the dock its own colour and leave
# the rail on the terminal's background. A surface's own value wins, and
# empty puts it back to following background.
tuios set-config background theme
tuios set-config dock_background '#11111b'
tuios set-config appearance.sidebar.background off
tuios set-config appearance.sidebar.background ''

# Target a specific session
tuios set-config -s mysession dockbar_position hidden

# Give the session the size of the client that last had input
tuios set-config -s mysession daemon.window_size latest
```

### `tuios wait-for`

Block until the daemon reports that a condition matched.

The daemon watches its own events, so a script stops polling a pane and
sleeping between captures. The command exits `0` when the condition matches,
and non-zero with the `timeout` error when it does not match before
`--timeout`.

**Usage:**
```bash
tuios wait-for <condition> [flags]
```

**Conditions:**
| Condition | Matches when |
|-----------|--------------|
| `session-exists` | The named session is present |
| `window-output` | The window's content matches `--pattern` |
| `window-exit` | The window's shell exited |
| `window-idle` | The window printed nothing for `--idle` milliseconds |
| `agent-state` | An agent reached one of the `--until` states; without `--window`, any agent pane in the session matches; with `--any-session`, any agent pane in any session; with `--select`, any agent pane the selector matches, or with `--every` all of them |
| `agent-message` | A message arrived. With `--window`, the first unread message in that inbox; without it, any message left in the session after the wait began |
| `command-finished` | A shell that marks its commands with OSC 133 finished one. With `--window`, that pane's next command, or with `--command-seq N` the first once the pane has finished more than N (already true if it happened before the wait). Without a window, any pane in the session. Prints the exit code |

**Flags:**
- `-s, --session <name>`: Target session (default: this pane's session, else the most recently active)
- `-w, --window <id-or-name>`: Target window (default: focused; `agent-state`: any window)
- `--pattern <regexp>`: Go regular expression (RE2), required by `window-output`
- `--new`: For `window-output`: match only output written after the wait starts. Text already on the screen or in the scrollback does not match. A program that redraws its screen writes its text again, and that text matches
- `--until <states>`: Agent state(s) to wait for, comma-separated, required by `agent-state`
- `--thread <id>`: Only match a message in this thread, for `agent-message`. Pass any message id in it
- `--idle <ms>`: Milliseconds of silence that count as idle (default: 500)
- `--timeout <ms>`: Milliseconds to wait before giving up (default: 30000)
- `--any-session`: For `agent-state`: watch every session on the daemon, including ones created during the wait. Takes no `--session` or `--window`, and the result names the session that matched
- `--command-seq <N>`: For `command-finished` with `--window`: match once the pane has finished more than N commands. Read N from `list-windows --json` before starting the command
- `--select <selector>`: For `agent-state`: watch the agent panes a [selector](AGENT_STATE.md#selectors) matches, in every session, including panes that open during the wait. Takes no `--session`, `--window` or `--any-session`
- `--every`: With `--select`: wait until at least one pane matches and every matched pane is in one of the `--until` states
- `--json`: Output result as JSON

The `window-output` pattern is matched against the window's scrollback, so
output that has already scrolled off the visible screen still matches, and
output printed before the wait started matches immediately.

That last part has a sharp edge. A pane echoes the command it was sent, so a
marker written literally in the command matches its own echo and the wait
returns before the work has run. A marker left in the scrollback by an earlier
run matches the same way. Assemble the marker so the literal appears only in the
output (`printf "BUILD_%s\n" OK`), or use `window-exit` in a window opened for
the one command.

`--new` removes the old output from the match. The wait then reads only the
output the pane writes after the daemon starts the wait. Output written before
that point does not count, so a command that finishes before the wait starts does not
match. A daemon older than this flag refuses it, and the command tells you to
run `tuios restart-server`.

**Examples:**
```bash
# Wait for a build to print its marker
tuios wait-for window-output -w build --pattern 'BUILD OK'

# Ignore the marker of the last build that is still on the screen
tuios wait-for window-output -w build --pattern 'BUILD OK' --new

# Wait for a pane to go quiet for two seconds
tuios wait-for window-idle -w build --idle 2000

# Wait for a command's shell to exit, allowing ten minutes
tuios wait-for window-exit -w build --timeout 600000

# Wait for a session to appear
tuios wait-for session-exists -s work

# Wait until any agent in the session is waiting on a human
tuios wait-for agent-state -s work --until needs_input

# Wait until an agent in any session is waiting on a human
tuios wait-for agent-state --any-session --until needs_input

# Wait until every agent of a fan-out has finished its turn
tuios wait-for agent-state --select 'group:fan/add-retry' --until idle,done --every --timeout 3600000

# Wait for mail in your own inbox
tuios wait-for agent-message -s work -w "$TUIOS_PANE_ID" --timeout 600000

# Branch on the result
if tuios wait-for window-output -w build --pattern 'BUILD OK' --timeout 60000; then
    echo "build finished"
else
    echo "build timed out"
fi

# Wait for the command after the 4th in the build pane, with its exit code
tuios wait-for command-finished -w build --command-seq 4 --timeout 600000
```

### `tuios run`

Type one command line at a pane's shell prompt, wait for it to finish, print
what it printed, and exit with its exit status.

It reads where the command starts and ends from the shell's own OSC 133 marks,
so it needs a shell with prompt integration: fish and zsh with it on, bash with
a setup, or any shell a terminal injects its integration script into. It never
types into a running program.

**Usage:**
```bash
tuios run [flags] -- <command line>
```

The words after `--` are joined with spaces into one line that the shell
parses, so quote for the shell as you would when typing it.

**Flags:**
- `-s, --session <name>`: Target session (default: this pane's session, else the most recently active)
- `-w, --window <id-or-name>`: Target window (default: focused)
- `--timeout <ms>`: Milliseconds to wait for the command (default: 30000). A timeout does not stop the command
- `--lines <N>`: Keep only the last N lines of the output (0 keeps all)
- `--json`: Output the whole result as JSON: `exit_code`, `output`, `cmdline`, `duration_ms`, `command_seq`, `truncated`

**Exit status:** the command's own. When the shell sent no status, run says so
on stderr and exits `0`. A refusal exits `1`: `not_at_prompt` when a command is
already running in the pane or another `run` there has not ended,
`no_shell_integration` when its shell sends no marks. Nothing is typed in
either case. A shell that marks its prompts and not its commands (bash before
4.4, which ignores the recipe's PS0) is found out by the first `run` in the
pane: the line is typed, and when the shell draws a new prompt with no command
mark, `run` fails at once with `no_shell_integration`. Every later `run` there
is refused before typing.

**Examples:**
```bash
# Run the tests in the build pane and branch on the status
tuios run -w build --timeout 600000 -- go test ./... && echo passed

# Only the last 40 lines of a long build
tuios run -w build --lines 40 -- make

# The whole result
tuios run -w build --json -- make lint
```

### `tuios subscribe`

Print the daemon's event stream, one JSON object per line.

The first line is the subscribe ack. It carries `seq`, the last event number
assigned when the stream went live, and `boot_id`, a random id for this daemon
start. Every event after it carries its own `seq` and `boot_id`. The event
types and their fields are listed in [protocol.md](protocol.md#event-stream).

Without `--session` the stream covers every session on the daemon. Most
commands read an omitted session as the most recently active one; this one
does not.

**Usage:**
```bash
tuios subscribe [flags]
```

**Flags:**
- `-s, --session <name>`: Only events from this session (default: every session)
- `-w, --window <id>`: Only events about this window id
- `--types <list>`: Only these event types, comma-separated (default: all)
- `--after-seq <n>`: Replay the retained events after this seq before streaming live
- `--boot-id <id>`: The `boot_id` the `--after-seq` came with, so a daemon restart shows as a gap. Needs `--after-seq`
- `--count <n>`: Exit after printing this many events, gap lines included (default: run until the stream ends)
- `--hosts`: Also print the `agent-state`, `session-created` and `session-closed` events of every linked host, each with `host` set. Without it, the only events about other machines are `attention` for their Inbox items and `host-changed`, and only when no `--session` or `--window` is given

To resume after a disconnect, pass the `seq` of the last event you printed and
its `boot_id`. The daemon keeps the last 4096 events, apart from `output`
events, and replays the ones after that seq before carrying on live. When it
cannot replay everything you missed, a `gap` line comes first with a `reason`:
`evicted` (the oldest events you missed are gone), `boot_changed` (the daemon
restarted), `not_retained` (your filter includes `output`, which is never
replayed) or, on a live stream, `overflow` (you read too slowly). After a gap,
read current state again with `tuios list-agents` or `tuios list-windows`.

**Examples:**
```bash
# Every agent state change on the daemon
tuios subscribe --types agent-state

# One session's window lifecycle
tuios subscribe -s work --types window-created,window-closed

# Resume where a previous run stopped
tuios subscribe --types agent-state --after-seq 118 --boot-id 9f2c41d07a3e8b65

# Wait for the next bell anywhere, then exit
tuios subscribe --types bell --count 1

# Follow the Inbox: every item that opens, changes or closes
tuios subscribe --types attention

# Every agent on every machine, and every host coming or going
tuios subscribe --hosts --types agent-state,host-changed
```

### `tuios list-attention`

List the Inbox: every approval and question an agent is blocked on, mail to
you, errored agents, conversations a daemon restart left to resume, and
finished turns nobody has looked at, in every session on the daemon and on
every linked host it streams. Rows are grouped Approvals, Questions (an
agent's own and those put with `ask-human`), Mail, Errored, Resume, Done,
oldest first, with how long each has waited, its
id, its session and pane, and what it said. The TUI's Inbox (prefix `i`) is
the same list. A row of another machine names it,
`build:api/claude`, and a row of a machine whose link is down ends in
`[unreachable, seen 5m ago]`: it is what that machine said last.

An item closes by itself when what opened it stops being true. Dismissing one
is for the person at an attached client and is done from the Inbox; there is
no command for it, because a command run from a pane is exactly what must not
be able to clear the person's queue. Snoozing, marking unread and undo are the
person's acts too and have no command either. `--snoozed` lists the items the
person snoozed, after the rest under a Snoozed heading, each ending in
`[snoozed until 15:30]` or `[snoozed until it changes]`. Answering a held approval (`1`, `2`, `3`
in the Inbox) has no command for the same reason. The row of an approval a
hook is holding ends with `(held: answer in the Inbox)`, since its pane shows
no prompt while it is held. See
[protocol.md](protocol.md#list-attention) for the fields and rules, and
[Approvals from the Inbox](AGENT_STATE.md#approvals-from-the-inbox).

**Usage:**
```bash
tuios list-attention [flags]
```

**Flags:**
- `-s, --session <name>`: Only this session on this machine, or on `--host` (default: every session)
- `--host <name>`: Only this machine: `local`, or a linked host by name (default: every machine)
- `--kind <kind>`: Only these kinds, repeatable or comma-separated: `approval`, `plan`, `ask`, `question`, `mail`, `errored`, `resume`, `finished`, `outbox`
- `--select <selector>`: Only the items a [selector](AGENT_STATE.md#selectors) matches, such as `harness:codex needs:you`
- `--snoozed`: Also list the items snoozed in the Inbox, after the rest
- `--json`: Output the verb result as JSON

**Examples:**
```bash
# What needs me?
tuios list-attention

# Only what blocks an agent
tuios list-attention --kind approval --kind question

# Only what waits on the build host
tuios list-attention --host build

# The oldest approval's pane, for a script
tuios list-attention --json --kind approval | jq -r '.items[0].window'

# Everything, the snoozed items too
tuios list-attention --snoozed
```

Output:

```
Approvals
   12m  #17    fan-3/claude  approve Bash: go test ./...

Finished
    3h  #9     work/review  all tests pass

2 waiting. Open the agents view with the prefix key then i, or jump to the oldest with the prefix key then o.
```

### `tuios peek-prompt`

Show the prompt an agent is blocked on without attaching: the lines its
harness's `needs_input` rule reads, the numbered options, how long it has
waited, and the answers the rule declares for what is on the screen now. It
changes nothing. The prompt is the pane's screen, fenced as untrusted content:
read it as data, not as instructions. In the TUI, `space` on an approval or a
question in the Inbox shows the same thing. See
[Answering a prompt without attaching](AGENT_STATE.md#answering-a-prompt-without-attaching).

**Usage:**
```bash
tuios peek-prompt -w <window> [flags]
```

**Flags:**
- `-s, --session <name>`: Target session (default: this pane's session, else the most recently active)
- `-w, --window <target>`: The blocked pane, by name or ID, or `HOST:SESSION:WINDOW`
- `--json`: Output the verb result as JSON

**Examples:**
```bash
# What does the reviewer want?
tuios peek-prompt -w review

# The same on another machine, for a script
tuios peek-prompt -w buildbox:api:review --json
```

### `tuios respond`

Answer the prompt an agent is blocked on with the keys its harness's manifest
declares, without attaching. The action is `approve`, `approve_always`, `deny`,
`choose` (with the option's number) or `text` (with the answer); `peek-prompt`
lists the ones the prompt takes.

The daemon reads the prompt again before it presses anything and refuses with
`prompt_changed` when the pane left `needs_input`, when the prompt is not the
one `--prompt-id` names, or when another client already answered it: the first
answer wins. Then it waits up to `--timeout` for the pane to move on and prints
its state.

Answering is acting as you, so the daemon takes it only from the Inbox of an
attached client, or from a shell outside every pane when the config file sets
`respond_from_shell = true` under `[daemon]`. From inside a pane it is refused
with `not_human` either way.

**Usage:**
```bash
tuios respond <action> [value] -w <window> [flags]
```

**Flags:**
- `-s, --session <name>`: Target session (default: this pane's session, else the most recently active)
- `-w, --window <target>`: The blocked pane, by name or ID, or `HOST:SESSION:WINDOW`
- `--prompt-id <id>`: The prompt id `peek-prompt` printed; a prompt that changed since is refused
- `--timeout <ms>`: How long to wait for the pane to move on (default 5000, at most 30000)
- `--json`: Output the verb result as JSON

**Examples:**
```bash
# Read the prompt, then approve exactly that prompt
tuios peek-prompt -w review
tuios respond -w review --prompt-id 75f8b9fadb5b5dfc approve

# Pick option 2 of a question
tuios respond -w review choose 2
```

### `tuios queue`

Queue a message for the agent in a pane. It is typed as a prompt once the
agent has been at rest (`idle` or `done`, or `unknown` for a harness that can
never show idle) for a second, one message per rest, and never over a prompt
the agent is waiting on. For a harness that cannot show working, a rest after a
typed message is also new output followed by 5 seconds of silence. If the agent is at rest now,
it is typed right away. The daemon then waits for the agent to show it took
the message, the way `fan` waits for its first prompt. A message the agent
shows no sign of taking is marked `stalled`, is never typed again, and opens a
question in the Inbox; it holds the messages behind it until the agent next
works, shows on its screen that it took it, or you drop it, and the next message is then typed at the next rest.
A message also waits while you type into the pane, and while the agent's
input box holds your draft. See
[Queued messages](AGENT_STATE.md#queued-messages).

A pane holds at most `[agents.queue] max` messages (8 by default) of at most
16 KiB each. A reply from the Inbox with a long paste can carry more, as a
file the daemon writes when it types the reply (see `queue-prompt` in
[protocol.md](protocol.md#the-delivery-queue)). The queue lives in the daemon's memory, so a daemon restart drops
it, and so do the pane closing and the agent leaving the pane. From inside a
pane the message is checked like `send-text` when it is queued, and against
the pane's grants again when it is typed. See
[Queued messages](AGENT_STATE.md#queued-messages).

**Usage:**
```bash
tuios queue [flags] TEXT...
tuios queue ls [-w <window>] [flags]
tuios queue rm ID | --all -w <window> [flags]
```

**Flags:**
- `-s, --session <name>`: Target session (default: this pane's session, else the most recently active)
- `-w, --window <target>`: The agent's pane, by name or ID, or `HOST:SESSION:WINDOW` (default: the focused pane; for `ls`, every pane of the session)
- `--all` (`rm`): Drop every message queued for the pane that you may drop
- `--json`: Output the verb result as JSON

The words of `TEXT` are joined with spaces. To queue a message that reads
`ls` or `rm`, put `--` before it. `ls` prints one line per message: its id,
state (`waiting`, `delivering` or `stalled`), who queued it (`human` from the
Inbox, `shell` from outside every pane, a pane's id, or `link:HOST`), its age,
the pane, and the message's first line. `rm` from inside a pane drops only
what that pane queued, and from a shell every message but the ones you queued
from the Inbox, which only the attached client can drop.

**Examples:**
```bash
# Reply to the agent in the build pane once it finishes its turn
tuios queue -w build 'make the backoff jitter configurable'

# What waits, and drop one message
tuios queue ls
tuios queue rm q3

# Everything queued for one pane
tuios queue rm --all -w build
```

### `tuios task`

Hand out a session's work as task cards. A card is one unit of work: a title,
the prompt for the pane that takes it, a stage, and the pane that holds it. The
daemon keeps the cards with the session, so they outlive the pane that added
them. After a daemon restart they come back with every holder let go. A card is
also let go when its pane closes or its agent leaves the pane. See
[Task verbs](protocol.md#task-verbs).

The stages are `todo`, `plan`, `doing`, `verify`, `review`, `shipped` and
`done`. `claim` moves a card in `todo` or `plan` to `doing`, and `done` moves
it to `done` and lets it go.

tuios also moves a card when it records a fact about the card's work, unless
`[tasks] auto_stage = false` ([CONFIGURATION.md](CONFIGURATION.md#the-task-board)):

| Fact | From | To |
| --- | --- | --- |
| A plan held for approval on the pane that holds the card | `todo`, `doing` | `plan` |
| The plan approved from the Inbox | `plan` | `doing` |
| `tuios fan verify` starting in the card's fan (`fan --task`) | `doing` | `verify` |
| Every attempt's check ended and none passed | `verify` | `doing` |
| A pull request on the branch opened (cards held in the worktree's session, or in its fan) | `plan`, `doing`, `verify` | `review` |
| The pull request merged | `plan`, `doing`, `verify`, `review` | `shipped` |
| The pull request closed without a merge | `review` | `doing` |

A move fires only from its stages, so a card put in another stage by hand
stays there. A blocked card and a done card never move on their own, and done
is always set by hand. The history entry is by `tuios` and names the fact.

A plan is held only when `[agents.approvals]` holds plans for the harness and
the pane is not in front of you, so a plan you answer in the pane moves no
card. A plan kept planning, or a hold that times out, leaves the card in
`plan` until its pull request opens: the pull request is proof enough that the
plan went through. A pull request moves every card held in the worktree's session, so a
second pane there holding an unrelated card moves with the branch. With a fan,
each attempt's pull request reaches the card: one closing without a merge
moves it back to `doing` while another may still be open.

**Usage:**
```bash
tuios task add [-p PROMPT] [--stage STAGE] TITLE... [flags]
tuios task ls [--stage STAGE] [--open] [--all-sessions] [flags]
tuios task get ID [flags]
tuios task claim ID | --next [-w <window>] [flags]
tuios task done ID [flags]
tuios task stage ID STAGE [flags]
tuios task block ID REASON... | --clear [flags]
tuios task release ID [flags]
tuios task rm ID [flags]
```

**Flags:**
- `-s, --session <name>`: Session of the cards (default: this pane's session, else the most recently active)
- `-p, --prompt <text>` (`add`): What the pane that takes the card is to do, at most 16 KiB; `-` reads it from standard input
- `--stage <stage>` (`add`, `ls`): The stage it starts in; for `ls`, only the cards in it
- `--open` (`ls`): Leave out the cards that are done
- `--all-sessions` (`ls`): List the cards of every session on this machine, with a SESSION column first. Takes no `--session`
- `--next` (`claim`): Take the oldest card no pane holds that is not blocked or done, and that no fan of another session works on
- `-w, --window <target>` (`claim`): The pane that takes the card (default: this pane; required outside a pane)
- `--clear` (`block`): Lift the block
- `--json`: Output the verb result as JSON

The words of `TITLE` and `REASON` are joined with spaces. `ls` prints one line
per card: its id, stage (with `!` when it is blocked), the pane that holds it,
its age, and its title. `claim` prints the card's id and title on its first
line, so a script can read the id with `cut -d' ' -f1`; with nothing to take it
fails with `no_task`, and a card another pane holds fails with `task_held`.

From inside a pane, changing a card needs the `task` grant. A pane claims
only for itself and finishes, stages, blocks or releases only the card it
holds, unless it holds `admin`. `rm` from a pane needs `admin`.

**Examples:**
```bash
# A conductor adds the work
tuios task add -p 'Read api/retry.go and add a jitter option, with a test.' make the backoff jitter configurable

# A worker pane takes the next card, and finishes it
tuios task claim --next
tuios task done t1

# Stuck on something, then free again
tuios task block t1 waiting on the staging key
tuios task block t1 --clear

# What is open
tuios task ls --open
```

### `tuios review`

Show what the agent in a pane changed, leave notes on its lines, and send the
notes to the agent. The diff is the pane's worktree against the base it was
made from, or for a plain repository against the merge base with its upstream
branch, else only what is not committed. Committed and uncommitted work show
together, untracked files included and ignored files left out. An untracked
file larger than `[agents.checkpoints] max_untracked_mb` (50 by default) is
listed as not read, with no counts. It is read by the daemon through a temporary git index, so the repository, its index and its
files are not changed. See
[Reviewing an agent's changes](AGENT_STATE.md#reviewing-an-agents-changes).

**Usage:**
```bash
tuios review [SESSION] [-w <window>] [--base <ref> | --against <session> | --uncommitted] [--stat] [--path <path>]... [--context <n>] [--json]
tuios review note [-w <window>] FILE:LINE TEXT... [--side old]
tuios review note [-w <window>] --hunk '<header>' FILE TEXT...
tuios review note --edit ID TEXT... | --remove ID
tuios review notes [-w <window>] [--clear] [--json]
tuios review send [-w <window>] [--id ID]... [--now] [--json]
```

**Flags:**
- `-s, --session <name>`: Target session, also accepted as the argument (default: this pane's, else the most recently active)
- `-w, --window <target>`: The pane, by name or ID (default: the focused pane)
- `--base <ref>`: Diff against this branch, tag or commit, through its merge base with `HEAD`
- `--against <session>`: Diff against another attempt of the same fan
- `--uncommitted`: Only what is not committed yet
- `--stat`: The list of changed files with their counts, without the diff
- `--path <path>`: Only this path, relative to the repository root. Repeatable
- `--context <n>`: Lines of context around each change, 0 to 20 (default 3)
- `--side old` (`note`): `LINE` is a removed line, numbered as in the base
- `--hunk <header>` (`note`): The note is on the whole hunk with this header
- `--edit <id>`, `--remove <id>` (`note`): Change or drop a note
- `--clear` (`notes`): Remove every note you may remove
- `--id <id>` (`send`): Send only this note, sent before or not. Repeatable
- `--now` (`send`): Send only if the agent is at rest with nothing queued; never queue
- `--json`: Output the verb result as JSON

`tuios review` prints a heading, one line per changed file (its status `A`,
`M`, `D`, `R`, or `U` for untracked, and its counts), then each file's hunks
with both line numbers and the notes under the lines they are on. A diff stops
at 400 files, 2 MiB of text or 5000 lines in one file; files past that show
their counts only.

A note keeps its line's text and follows it when the file changes; one whose
line is gone is marked outdated. `review notes` lists each note's id, place,
author (`human`, `shell`, a pane, or `link:HOST`), state and text. From inside
a pane only the notes that pane wrote can be edited or removed; from a shell,
any but the ones left from the attached client.

`review send` sends the unsent notes as one message through the delivery
queue ([`tuios queue`](#tuios-queue)): typed when the agent is at rest, never
over a prompt. The message says who sent it: "a script" from a shell, the pane
from inside one, and "the person" only from the attached client. A note
written by someone else says who wrote it. A note whose author may not type
into the pane now, or whose pane is gone, is withheld and listed after the
summary. From inside a pane, notes can be added only on a pane you could type
into.

The review commands work on this machine's sessions. A `HOST:SESSION` or
`HOST:SESSION:WINDOW` target is refused: attach to that machine and review
there, or bring the work here with
[`tuios worktree pull`](#tuios-worktree) and review that.

**Examples:**
```bash
# What the agent in the focused pane changed
tuios review

# A fan attempt against its base, or against another attempt
tuios review api-fan-retry-2
tuios review api-fan-retry-2 --against api-fan-retry

# Leave two notes and send them
tuios review note -s api-fan-retry-2 api/retry.go:42 'log the attempt number here too'
tuios review note -s api-fan-retry-2 --hunk '@@ -88,4 +100,6 @@' api/retry.go 'wrap with context'
tuios review send -s api-fan-retry-2
```

### `tuios checkpoint`

List, read and restore the checkpoints of an agent's turns. The daemon saves
a pane's git work tree each time its agent finishes a turn that changed a
file. The index, `HEAD`, the branch and the stash do not change. See
[Turn checkpoints](AGENT_STATE.md#turn-checkpoints).

**Usage:**
```bash
tuios checkpoint list [-s <session>] [-w <window>] [--json]
tuios checkpoint diff [N] [-s <session>] [-w <window>] [--stat] [--path <path>]... [--context <n>] [--json]
tuios checkpoint restore N [-s <session>] [-w <window>] [--force] [--json]
```

**Flags:**
- `-s, --session <name>`: Session of the pane (default: this pane's, else the most recently active)
- `-w, --window <target>`: The pane, by name or ID (default: the focused pane)
- `--stat` (`diff`): The list of changed files with their counts, without the diff
- `--path <path>` (`diff`): Only this path, relative to the repository root. Repeatable
- `--context <n>` (`diff`): Lines of context around each change, 0 to 20 (default 3)
- `--force` (`restore`): Restore while the agent is working or waiting on a prompt
- `--json`: Output the verb result as JSON

`checkpoint list` prints one row per checkpoint: its number, the turn, the
agent state, the time, the commit and the label. `checkpoint diff N` shows
what turn N changed, against the checkpoint before it. Without N it shows the
newest. `checkpoint restore N` saves the work tree as a safety checkpoint, then
puts the files back as checkpoint N holds them. It prints the number of the
safety checkpoint. Restore that number to undo the restore.

### `tuios ship`

Take an agent's work from its worktree to a merged change: commit it, merge
the branch into its base, push the branch, and open a pull request. See
[Shipping a worktree](AGENT_STATE.md#shipping-a-worktree).

**Usage:**
```bash
tuios ship commit [-s <session>] [-w <window>] [-m <message>] [--force] [--json]
tuios ship merge [-s <session>] [-w <window>] [--into <branch>] [--squash | --ff-only] [-m <message>] [--json]
tuios ship push [-s <session>] [-w <window>] [--remote <name>] [--yes] [--wait <duration>] [--request <id>] [--json]
tuios ship pr [-s <session>] [-w <window>] [--base <branch>] [--title <text> [--body <text>]] [--draft] [--remote <name>] [--yes] [--wait <duration>] [--request <id>] [--json]
tuios ship status [-s <session>] [-w <window>] [--refresh] [--json]
```

**Flags:**
- `-s, --session <name>`: Session of the pane (default: this pane's, else the most recently active)
- `-w, --window <target>`: The pane, by name or ID (default: the pane this runs in, else the focused pane)
- `-m, --message <text>` (`commit`): The commit message. The default is the pane's last prompt, or the line its last turn ended with
- `--force` (`commit`): Commit while the agent is working or waiting on a prompt
- `--into <branch>` (`merge`): The branch to merge into. The default is the base the worktree was made from
- `--squash`, `--ff-only` (`merge`): Make one commit, or only fast-forward
- `-m, --message <text>` (`merge`): The message of the merge or squash commit
- `--remote <name>` (`push`, `pr`): The remote. The default is the one the branch follows, else the only one, else `origin`
- `-y, --yes` (`push`, `pr`): Do not ask before sending
- `--wait <duration>` (`push`, `pr`): How long to wait for your answer in the Inbox, when one is needed (default 2m)
- `--request <id>` (`push`, `pr`): Wait again for the answer to a question an earlier call put in the Inbox
- `--base <branch>` (`pr`): The branch the pull request merges into
- `--title <text>`, `--body <text>`, `--draft` (`pr`): The pull request's title, body and draft state. Without `--title`, gh fills the title and body from the commits
- `--refresh` (`status`): Ask gh now
- `--json`: Output the verb result as JSON. A failure prints `success`, `error`, `code` and, for a conflict or a dirty checkout, `files`

**Examples:**
```bash
tuios ship commit -s api-feat-retry -m 'Add a retry to the client'
tuios ship merge -s api-feat-retry
tuios ship merge -s api-feat-retry --squash -m 'Add a retry to the client'
tuios ship pr -s api-feat-retry --draft
tuios ship status -s api-feat-retry --refresh
```

git runs in the daemon with your own environment: your name, email, signing
setup and hooks. tuios sets no identity and adds no trailer. `ship commit`
stages every change, untracked files included and ignored files not. When a
hook or the signing program refuses the commit, the index goes back to what
it was. A call from inside a pane runs git with no hooks, and with no program
that only the repository's own config names.

`ship merge` merges into the main checkout. That checkout must have the
target branch checked out and no uncommitted change to a tracked file. When
the merge conflicts, it is undone with `git reset --merge`, and the command
lists the files that conflict (code `merge_conflict`). Uncommitted changes in
the worktree are not merged, and the command says how many there are.

`ship push` and `ship pr` send work off this machine. The first call shows
what would be sent: the branch, its commit, the remote, the commits and the
pull request. The command asks `[y/N]` at a terminal. Elsewhere it needs
`--yes`. When the command runs inside a tuios pane, the person must also allow
it in the Inbox. The question pops up on the client that shows the pane, and
the command waits for the answer. A push is never forced. `ship pr` needs the
gh CLI, installed and logged in (`gh auth login`). tuios holds no GitHub token.

The pull request and its checks show on the agent's row in the rail (`PR #12
open pass`), in `tuios worktree ls`, and in the `pr` field of `ls --json` and
`worktree ls --json`. While a client is attached, the daemon reads each open
pull request again every minute with `gh pr view`. With no open pull request,
or no client, nothing is read.

`fan keep <session> --merge` merges the kept attempt the same way before it
removes the others. `--squash`, `--ff-only` and `--into` choose how. When the
merge is refused, no attempt is removed.

### `tuios set-agent-state`

Report a pane's agent state so the session can show which panes need
attention.

**Usage:**
```bash
tuios set-agent-state <state> [flags]
```

**States:** `none`, `working`, `needs_input`, `idle`, `done`, `errored`, `unknown`

**Flags:**
- `-s, --session <name>`: Target session (default: the pane's own session in a pane, else the most recently active)
- `-w, --window <id-or-name>`: Target window (default: the pane this runs in, else the focused one)
- `-m, --message <text>`: Short note reported with the state
- `--source <source>`: Where the state came from: `report`, `osc`, `screen`, `stall` (default: `report`)
- `--harness <id>`: Id of the harness the state is about, e.g. `claude-code`
- `--kind <kind>`: What a `needs_input` state waits for: `approval`, `question` or `auth`. Only valid with `needs_input`
- `--agent-session-id <id>`: The harness's own conversation id. Stored on the pane, and turns on the nested-session guard (below)
- `--transcript-path <path>`: The transcript file the harness writes. For a harness whose manifest has a transcript reader, the pane is joined to this exact file
- `--if-state <states>`: Apply only when the pane is in one of these comma-separated states

**Hook fields:**
The last four flags are what `tuios agent-hook` sends, and each is sent only when
set, so a call that uses none of them works against an older daemon. An older
daemon ignores these fields rather than refusing them, so `--if-state` asks the
daemon first and fails, sending nothing, when the daemon does not support it.
`--if-state` is how "the tool ran after an approval" moves a pane from
`needs_input` back to `working` without also turning a `done` pane back to
`working`. A report with `--agent-session-id` is refused while the pane's own
agent is `working` or `needs_input` by its own report and the report names a
different session, or a different harness: that is a nested run, such as a
`claude -p` a tool call started inside the pane. At rest a different session
takes the pane over, as `/clear` or a restart should. `tuios agent-hook` also
sends the harness's pid, which lets a new session from the same harness process
take the pane over mid-turn, as `/clear` after an interrupted turn does. This
command has no flag for it, so a report from here with a different
`--agent-session-id` is refused mid-turn.

**Sources and precedence:**
More than one source can have an opinion about the same pane. Each source is
ranked, and a source may write over a claim ranked at or below its own and
never over one ranked above it. A source updating its own claim is the
same-rank case and is always allowed.

| Source | Rank | What it is |
|--------|------|------------|
| `report` | highest | The harness, or its hook shim, calling for itself |
| `osc` | | An escape sequence the pane emitted |
| `screen` | | A rule matched against the pane's rendered text |
| `stall` | lowest | The output-stall heuristic |

There is one exception, for the case ranking alone gets wrong: a `screen` rule
that matched a blocking prompt may write over a higher-ranked claim that has
gone stale, meaning the pane has painted since that claim was stamped and the
claim has stood unrefreshed for two seconds. The displaced claim is put back the
moment a later look finds the prompt gone. It applies only to the daemon's own
screen tier, which has actually read the pane; passing `--source screen` here
never overrides anything. See
[Agent state](AGENT_STATE.md#the-one-exception-a-visible-blocker).

`report` is the default, so a caller written before sources existed keeps its
authority. A report the daemon declines prints to stderr and leaves the state
alone:

```
Not applied: a higher-ranked source owns this pane. It still reports working.
```

The other refusals name their own reason on that line: an `--if-state` that did
not hold, or a nested run from another conversation or another harness.

**Examples:**
```bash
# Mark the focused pane as working
tuios set-agent-state working

# Mark a specific pane as needing input, with a note
tuios set-agent-state needs_input -w build -m "awaiting approval"

# Say the block is an approval, for a named conversation
tuios set-agent-state needs_input --kind approval --agent-session-id 5f1c -m "approve Bash: make"

# Clear a block after the tool ran, and leave any other state alone
tuios set-agent-state working --if-state needs_input

# Report on behalf of a named harness, from an escape sequence
tuios set-agent-state working --source osc --harness claude-code

# Clear a pane's agent state
tuios set-agent-state none
```

### `tuios set-agent-meta`

Record short facts about the agent in a pane, such as its model, how full its
context is, or a one-line summary of the task. The rail draws them on the
second line of the agent's row. They are display only: they never change the
agent state, a wait, an alert or a message.

**Usage:**
```bash
tuios set-agent-meta [key=value ...] [flags]
```

Each argument is `key=value`, and `key=` removes the key. A key is 1 to 24
lower-case letters, digits, `_` or `-`, starting with a letter. A value has its
control characters replaced and is cut to 80 characters; the keys that were cut
are named on stderr. One call sets at most 16 keys, and a pane holds at most 32.
Keys keep the position they first arrived in, so an update does not reorder the
row. The metadata clears when the agent leaves the pane.

A call that repeats the values the pane already holds changes nothing and sends
nothing to attached clients, and renews a TTL only once less than half of it is
left, so a feed may write on every tick. The keys `now`, `prompt` and
`subagents` are written by tuios from what the harness hooks report, and are
refused here; see [`tuios agent-log`](#tuios-agent-log).

**Flags:**
- `-s, --session <name>`: Target session (default: this pane's session, else the most recently active)
- `-w, --window <id-or-name>`: Target window (default: focused)
- `--source <name>`: Who is writing, so `--clear` removes only this writer's keys
- `--ttl <duration>`: Drop the keys this call sets after this long, at most `24h` (default: keep until removed)
- `--clear`: Remove every key this source wrote (every key with no `--source`) first. The keys tuios writes, `now`, `prompt` and `subagents`, stay
- `--json`: Print the result

**Examples:**
```bash
# From a statusline or hook: the model and context use, for a minute
tuios set-agent-meta -w "$TUIOS_PANE_ID" --source statusline --ttl 60s model=opus context=42%

# Remove one key
tuios set-agent-meta summary=

# Remove every key this source wrote
tuios set-agent-meta --source statusline --clear
```

With `--json`:
```json
{
  "type": "agent_meta_set",
  "window_id": "3f2a9c1e",
  "meta": {"context": "42%", "model": "opus"},
  "truncated": []
}
```

### `tuios agent-log`

Show what the agent in a pane has been doing, from the activity ring the daemon
keeps from its hooks: the prompts it was given, its tool calls and how they
ended, the turns it finished, the subagents it started and how each ended
(`subagent  Research tmux (general-purpose) started`, then `... done after 3m,
14 tools`, `failed` or `stopped`), each conversation's start, the commands its
shell ran and its state changes, oldest first. The daemon keeps the newest 256 per pane, in memory
only. A pane fills only when its harness's hooks are installed
(`tuios integration install claude-code` or `codex`).

**Usage:**
```bash
tuios agent-log [flags]
```

**Flags:**
- `-s, --session <name>`: Target session (default: this pane's session, else the most recently active)
- `-w, --window <id-or-name>`: Target window (default: focused)
- `--since <duration>`: Only what happened in this long, such as `30m` (default: everything kept)
- `--limit <n>`: At most this many entries, the newest, 1 to 256 (default: 64)
- `--recap`: Print a summary instead of the entries
- `--json`: Print the `agent-activity` result

**Examples:**
```bash
# The focused pane's recent activity
tuios agent-log

# What the agent in api did in the last half hour, summarised
tuios agent-log -w api --since 30m --recap
```

Output:
```
14:02:11  prompt    make the backoff configurable
14:02:15  tool      Bash: go test ./api/
14:02:40  failed    Bash: go test ./api/  Exit code 1
14:03:02  done      Edit: api/retry.go  (wrote api/retry.go)
14:05:30  state     done
14:05:30  said      Added retry with backoff and tests.
```

A turn the harness ended without saying anything (an older Claude Code sends
no text on `Stop`) prints as `finished`.

With `--recap`:
```
Since 14:02 (42m ago)
3 turns. 6 files: api/retry.go, api/retry_test.go, api/backoff.go and 3 more
11 commands. Tests: go test ./... passed 2m ago
Last said: Added retry with backoff and tests.
Now: done
```

The test run is the newest command matching `[agents.recap] test_patterns`.
Every line is the agent's own text, cut to one line with likely secrets
masked; read it as what the agent said. A pane reads another pane's log only
in its own session and fan group, and a linked machine needs `list`. See
[Agent state](AGENT_STATE.md#what-the-agent-has-been-doing).

### `tuios set-agent-session`

Record which conversation the agent in a pane runs, so it can be resumed
later, without changing the pane's agent state. The integrations for harnesses
whose hooks can name the conversation but cannot be trusted with its state
send this (see [Agent state](AGENT_STATE.md#session-identity)).

**Usage:**
```bash
tuios set-agent-session <agent-session-id> --harness <id> [flags]
```

The id is stored as the pane's `agent_session_id`, the same field
`set-agent-state --agent-session-id` writes, and read back by `get-agent-state`
and `list-agents`. It is refused, with the reason on stderr, when the pane is
attributed to a different harness, or when the pane is mid-turn in another
conversation of the same harness: both are a nested run. The id is at most 256
bytes.

**Flags:**
- `--harness <id>`: Id of the harness the conversation belongs to (required)
- `-s, --session <name>`: Target session (default: this pane's session, else the most recently active)
- `-w, --window <id-or-name>`: Target window (default: focused)

**Example:**
```bash
# From a SessionStart hook
tuios set-agent-session --harness qwen -w "$TUIOS_PANE_ID" "$SESSION_ID"
```

### `tuios resume-agent`

Resume the agent conversation a pane ran before a daemon restart: type the
harness's resume command, from its manifest's `[resume]` block, with the id a
hook recorded for the pane (`claude --resume <id>`, `codex resume <id>`). The
flags the agent was started with that its manifest keeps come after the id,
such as `claude --resume <id> --permission-mode plan --model opus`. When a kept
flag turns approvals off, a second line says so, such as `Resumes with
approvals off (--dangerously-skip-permissions)`. It brings back the
conversation, not the process. See
[Agent state](AGENT_STATE.md#resuming-after-a-restart).

**Usage:**
```bash
tuios resume-agent [flags]
```

It types only when the pane's shell is at its prompt, and fails with
`not_ready` otherwise. It fails with `not_resumable` when the pane has no
recorded conversation, its harness has no resume command, the recorded id is
not one plain shell token, or the pane runs on another machine. Nothing is
typed on a failure. A pane's Resume row in the Inbox closes when it succeeds.
It works on any pane with a recorded conversation, including one whose agent
had exited before the restart, which the restore itself does not offer.

**Flags:**
- `-s, --session <name>`: Target session (default: this pane's session, else the most recently active)
- `-w, --window <id-or-name>`: Target window (default: focused)
- `--dry-run`: Print the command without typing it
- `--json`: Output result as JSON

**Example:**
```bash
tuios resume-agent -w build --dry-run
# claude --resume 5f1c2b7e-9a3d-4c1e-8f00-1234567890ab

tuios resume-agent -w build
# Resumed claude-code conversation 5f1c2b7e-... in 3f2a9c1e: claude --resume 5f1c2b7e-...
```

```json
{
  "success": true,
  "message": "command executed",
  "window_id": "3f2a9c1e-0000-4000-8000-000000000000",
  "harness": "claude-code",
  "agent_session_id": "5f1c2b7e",
  "argv": ["claude", "--resume", "5f1c2b7e"],
  "command": "claude --resume 5f1c2b7e",
  "typed": true
}
```

What a daemon restart does with these conversations is
`daemon.resume_agents`: `ask` (default) opens a Resume row per pane in the
Inbox, answered with `y`; `auto` types the command into each restored shell;
`off` does neither.

### `tuios rename-session`

Rename a session.

The new name is what `tuios ls` shows and what `attach` and `-s` take. New
panes get it as `TUIOS_SESSION`. Panes that already run keep the old name, and
tuios commands from them still reach the session. Attach and kill-session by
the old name fail and name the new one. The rename also clears a label set
with `tuios set-session-name`. The name of a running or saved session is
refused. A daemon older than this command answers that it does not know it.
Run `tuios restart-server`.

With one argument, the session is the one given by `-s`, or else the session
of the pane you run it in.

**Usage:**
```bash
tuios rename-session [session] <new-name> [flags]
```

**Flags:**
- `-s, --session <name>`: Session to rename (default: the session of this pane)

**Examples:**
```bash
# Rename the session "test" to "work"
tuios rename-session test work

# Rename the session of this pane
tuios rename-session work
```

### `tuios set-session-name`

Set the label a session shows in the sidebar and the dock.

The session keeps its own name for addressing, persistence and
`TUIOS_SESSION`, so a script that targets it by name keeps working. Pass no
name to clear the label. To change the name itself, use
`tuios rename-session`.

**Usage:**
```bash
tuios set-session-name [name] [flags]
```

**Flags:**
- `-s, --session <name>`: Target session (default: this pane's session, else the most recently active)

**Examples:**
```bash
# Label the current session
tuios set-session-name "Payments API"

# Label a specific session
tuios set-session-name -s work "Payments API"

# Clear the label
tuios set-session-name
```

### `tuios set-session-accent`

Set the accent a session uses. It is shared by every client attached to the
session and kept across a reattach. Pass no accent to clear it.

**Usage:**
```bash
tuios set-session-accent [accent] [flags]
```

**Flags:**
- `-s, --session <name>`: Target session (default: this pane's session, else the most recently active)

**Examples:**
```bash
# Accent the current session
tuios set-session-accent cyan

# Accent a specific session
tuios set-session-accent -s work cyan

# Clear the accent
tuios set-session-accent
```

### `tuios note`

Set, read or clear the return note of a session or a pane. A note is one short
line. It says what the session is for or what comes next. tuios shows it in
the dock when you attach or switch to the session. The sidebar, the session
switcher and the Inbox show it too.

The note is kept with the session. It survives a detach and a daemon restart.
A note is at most 200 bytes. Newlines become spaces.

**Usage:**
```bash
tuios note set TEXT... [flags]
tuios note get [flags]
tuios note clear [flags]
```

**Flags:**
- `-s, --session <name>`: Target session (default: this pane's session, else the most recently active)
- `-w, --window <pane>`: A pane by name or id, for the pane's note (default: the session's note)
- `--json`: Output result as JSON

`tuios note get` prints the note, and prints nothing when there is none.
`tuios ls --json` also gives each session's `note`.

**Examples:**
```bash
# Say what comes next before you stop
tuios note set next: run the migration

# Read it back
tuios note get

# A note on one pane
tuios note set -w build waiting for CI

# Remove the note
tuios note clear
```

### `tuios set-session-space`

File a session under a space, a named group of related sessions that `tuios ls` and the sidebar list together, under the space's name. A space is only a label on its sessions: it exists while at least one session is in it, and it survives a daemon restart with them. Pass no space to take the session out of any.

Surrounding whitespace is trimmed. A space name then follows the session name rules (no slash, backslash or control character) and is at most 64 bytes. A global session cannot be in a space.

**Usage:**
```bash
tuios set-session-space [space] [flags]
```

**Flags:**
- `-s, --session <name>`: Target session (default: this pane's session, else the most recently active)

**Examples:**
```bash
# File the current session under the space payments
tuios set-session-space payments

# File a specific session
tuios set-session-space -s work payments

# Take the session out of any space
tuios set-session-space
```

### `tuios set-session-order`

Put the sessions in an order. Every client attached to the daemon lists them in it, at once: the sidebar, the session switcher and `tuios ls`. Moving a session up or down on the sidebar does the same. The order survives a daemon restart.

Every name must be a live session. A session you leave out, and one made later, goes after the named ones in creation order.

**Usage:**
```bash
tuios set-session-order <session>... [flags]
```

**Examples:**
```bash
# List work first, then notes, then everything else
tuios set-session-order work notes
```

### `tuios set-workspace-name`

Name a workspace so the dock and the sidebar show the label instead of the
number. The number stays the workspace's identity, and is the label an unnamed
workspace shows. Pass no name to clear it.

**Usage:**
```bash
tuios set-workspace-name <workspace> [name] [flags]
```

**Arguments:**
- `workspace`: Workspace number, 1-based
- `name`: Label for the workspace. Omit to clear it.

**Flags:**
- `-s, --session <name>`: Target session (default: this pane's session, else the most recently active)

**Examples:**
```bash
# Name workspace 2
tuios set-workspace-name 2 review

# Name a workspace in a specific session
tuios set-workspace-name -s work 2 review

# Clear the name
tuios set-workspace-name 2
```

---

## Inspection Commands

Query the state of a running TUIOS session. These commands are designed for scripting and return structured data about windows and session state.

**Note:** These commands query the daemon's stored state directly and work even when no TUI client is attached to the session. This makes them ideal for background scripting and monitoring.

### `tuios list-verbs`

Print the control protocol's verb catalog: every verb with its parameter schema,
accepted values, and example requests, plus the protocol version and the stable
error codes.

```bash
tuios list-verbs [verb] [--json]
```

This is the discovery entry point for scripting and for agents driving TUIOS. It
needs no documentation to interpret: the schema, the value sets, and the error
vocabulary are all in the output.

**Examples:**

```bash
# Every verb with its parameters
tuios list-verbs

# Just one verb
tuios list-verbs capture-pane

# Machine-readable
tuios list-verbs --json | jq '.verbs[].verb'
```

### `tuios list-hooks`

List the hooks and what each one last did.

**Usage:**
```bash
tuios list-hooks [flags]
```

**Flags:**
- `-s, --session <name>`: Target session (default: this pane's session, else the most recently active)
- `--event <name>`: Only the hooks on this event
- `--json`: Output as JSON (default is human-readable table)

**Example output:**
```
╭────────────────────┬─────────┬──────────────────────────┬──────┬────────┬───────────────────────────╮
│ EVENT              │ SIDE    │ COMMAND                  │ RUNS │ STATE  │ LAST                      │
├────────────────────┼─────────┼──────────────────────────┼──────┼────────┼───────────────────────────┤
│ after-new-window   │ session │ ~/.config/tuios/new.sh   │ 2    │ ran    │ 2026-08-31T21:16:32+04:00 │
│ after-agent-state  │ session │ notify-send "$TUIOS_AG…  │ 0    │ waiting│                           │
│ after-attach       │ client  │ tmux-style-banner        │ 1    │ failed │ exit 127: command not fo… │
╰────────────────────┴─────────┴──────────────────────────┴──────┴────────┴───────────────────────────╯
```

A hook runs its command for the side effect, so a command that was never found
used to look exactly like one that worked. This is where the difference is
visible. `RUNS` of 0 means the command is fine and the event never happened. A
row that is missing altogether means the event name is misspelled and the hook
was never loaded.

`SIDE` says which process runs it. The daemon runs the hooks for the facts it
owns, so those fire on a detached session and fire once however many clients are
attached. The client runs the ones that need its terminal, so they are only
listed while a client is attached.

**JSON Output Structure:**
```json
{
  "success": true,
  "hooks": [
    {
      "event": "after-new-window",
      "side": "session",
      "command": "~/.config/tuios/new.sh",
      "runs": 2,
      "last_exit": 0,
      "last_run": "2026-08-31T21:16:32+04:00",
      "last_error": "",
      "last_ms": 16
    }
  ],
  "total": 1,
  "events": ["after-new-window", "..."],
  "client_attached": false
}
```

`events` lists every name a hook can be written on. `client_attached` says
whether a client answered for its half of the table: false means the client rows
are missing because nobody is attached, not that no client hooks exist.

### `tuios list-dock-components`

List the dock's components: what the bar is made of, what each cell reads, and
what each component's command last did.

**Usage:**
```bash
tuios list-dock-components [flags]
```

**Flags:**
- `-s, --session <name>`: Target session (default: this pane's session, else the most recently active)
- `--json`: Output as JSON (default is human-readable table)

**Example output:**
```
╭───────────────┬───────┬─────────┬──────────────────────────┬────────┬──────────────────────╮
│ COMPONENT     │ SIDE  │ SOURCE  │ REFRESH                  │ STATE  │ READS                │
├───────────────┼───────┼─────────┼──────────────────────────┼────────┼──────────────────────┤
│ mode          │ left  │ builtin │ render                   │ drawn  │                      │
│ workspaces    │ left  │ builtin │ render                   │ drawn  │                      │
│ custom/branch │ left  │ custom  │ event:after-focus-change │ drawn  │ feat/dock-components │
│ windows       │ center│ builtin │ render                   │ drawn  │                      │
│ custom/k8s    │ right │ custom  │ interval 30s             │ failed │ exit 127: ...        │
╰───────────────┴───────┴─────────┴──────────────────────────┴────────┴──────────────────────╯
```

A component whose command fails is hidden from the bar rather than left showing
a stale value, so this is where the failure is visible. `STATE` is `drawn`,
`hidden`, `failed`, or `gave up`; `READS` carries the cell text, or the exit
code and error when there is one.

The dock is composed by the attached client, so this needs a client attached.

**JSON Output Structure:**
```json
{
  "success": true,
  "components": [
    {
      "name": "custom/branch",
      "side": "left",
      "source": "custom",
      "refresh": "event",
      "events": "after-focus-change",
      "command": "~/.config/tuios/dock/git-branch.sh",
      "on_click": "",
      "max_width": 24,
      "text": "\u001b[35m\uf418\u001b[0m main",
      "visible": true,
      "last_exit": 0,
      "last_run": "2026-08-23T07:02:11Z",
      "last_error": "",
      "stopped": false
    }
  ]
}
```

`source` is `builtin` or `custom`. `refresh` is `render` (drawn from model state
on frames that were happening anyway), `once`, `interval` (with `interval`),
`push`, or `event` (with `events`). `text` is the cell as drawn, escapes
included. `last_error` and `last_exit` describe the component's last run, and
`stopped` says it has failed enough times to be left alone until a
`refresh-dock`.

### `tuios refresh-dock`

Re-run a dock component now, whatever its `refresh` mode says.

**Usage:**
```bash
tuios refresh-dock [component] [flags]
```

With no argument every component is re-run. Refreshing also clears a give-up, so
a component that failed five times in a row starts working again once its script
is fixed, without restarting the session.

**Flags:**
- `-s, --session <name>`: Target session (default: this pane's session, else the most recently active)
- `--json`: Output as JSON

**Examples:**
```bash
# After editing the script it runs
tuios refresh-dock agents

# From a hook, so the cell updates the moment the thing it reports changes
#   [hooks]
#   after-agent-state = "tuios refresh-dock agents"
```

See `examples/dock/` for working components and the config that wires them up.

### `tuios pip`

Pin a pane as the picture-in-picture view, or unpin it.

**Usage:**
```bash
tuios pip [window] [flags]
```

The view is a small live copy of the pane in a corner of the screen. It shows
while another pane has the focus. The pane stays where it is in the layout. A
click on the view goes to the pane.

Name the pane by ID or name. Omit it to pin the focused pane. Name the pinned
pane again to unpin it. The view belongs to the attached client, so the command
needs one. Set the size and the corner in `[pip]`.

**Flags:**
- `-s, --session <name>`: Target session (default: this pane's session, else the most recently active)
- `--off`: Unpin whatever is pinned
- `--json`: Output as JSON

**Examples:**
```bash
# Watch the agent pane while you work in another pane
tuios pip agent

# Take the view away
tuios pip --off
```

### `tuios call`

Send one verb to the daemon and print its reply as JSON.

**Usage:**
```bash
tuios call <verb> [params]
```

`params` is a JSON object, or `-` to read it from standard input. Omit it for
a verb that takes none. The reply is the daemon's result object as it is.

Use it from a program that can start a process but cannot write to the
socket, such as a Tern plugin. The daemon checks the call as it checks any
other, so a pane is held to its grants, and the verbs only the person may
call stay refused from a pane. `tuios list-verbs` lists every verb.

`call` refuses the verbs that hold the connection open after their reply:
`subscribe` (use `tuios subscribe`), `stream-pane`, `open-file-stream`,
`open-pane`, `pane-calls`, `link-peer` and `open-host-connection`.

The call waits 30 seconds, or for the verb's own `timeout` param (in
milliseconds) and 10 seconds more. `--timeout` sets the wait.

Exit status:
- 1: the daemon answered with an error, printed as `{"error": {"code", "message", "hint"}}`
- 2: the arguments or params are wrong
- 3: the daemon could not be reached, or did not answer in time

**Flags:**
- `--pretty`: Indent the JSON
- `--json`: Print bad input and transport errors as JSON too, with the code `invalid_input` or `transport`
- `--timeout <duration>`: How long to wait for the reply

**Examples:**
```bash
# Every session, as the daemon reports it
tuios call list-sessions

# A verb with params
tuios call list-windows '{"session":"work"}'
```

### `tuios pane-view`

Show one pane in this terminal, with no tuios around it.

**Usage:**
```bash
tuios pane-view -w <window> [flags]
```

The pane's output goes to this terminal as it is. What you type goes to the
pane, Ctrl-C included. A terminal that draws its own panes, such as Tern, runs
one `pane-view` for each tuios pane. Each pane then gets the terminal's own
scrollback, selection and search.

`pane-view` does not attach. It reads the pane through `stream-pane`, so the
session's clients do not change. The daemon answers the requests a program
sends to its terminal, so `pane-view` keeps them from the outer terminal,
which would answer them a second time.

With `--size follow` (the default), the pane takes this terminal's size while
no tuios client shows the session. With several viewers, the largest decides.
When the last viewer leaves, the pane goes back to its own size. While a
client shows the session, the pane only gets smaller to fit this terminal.
With `--size pane`, the pane keeps its size and only gets smaller. The daemon
makes these decisions, so a client that attaches or detaches, or a rename,
changes the size at once.

At start, `pane-view` asks this terminal for its colours and graphics, and
tells the daemon. While no tuios client shows the session, a program in the
pane that asks (OSC 10, 11 and 4, DA1, the kitty graphics query) gets this
terminal's answers.

Close the terminal to stop viewing. The pane and its session keep running.
After a daemon restart, `pane-view` resumes on the new daemon.

Exit status:
- the status of the pane's program when it exits
- 128 plus the signal that ended the pane's program, or ended `pane-view`
- 3 when the pane's window closes while its program runs
- 1 for an error, such as a pane or session that does not exist

**Flags:**
- `-s, --session <name>`: Target session (default: this pane's session, else the most recently active)
- `-w, --window <window>`: The pane to show, by ID or name
- `--size follow|pane`: Whether the pane takes this terminal's size (default: follow)

**Examples:**
```bash
# Show the pane named build of the session work
tuios pane-view -s work -w build

# Keep the pane at the size the session gives it
tuios pane-view -s work -w build --size pane
```

### `tuios list-windows`

List all windows in a TUIOS session.

**Usage:**
```bash
tuios list-windows [flags]
```

**Flags:**
- `-s, --session <name>`: Target session (default: this pane's session, else the most recently active)
- `--json`: Output as JSON (default is human-readable table)
- `--all`: List the panes of every session on this machine, one row each
- `--all-hosts`: Also list the panes of every session on each host in `[hosts]`
- `--text <N>`: Add the last N lines of each pane's screen, up to 200

With `--all`, `--all-hosts` or `--text`, each row has `session`, `host` (for a
pane on another machine, with `untrusted`), `workspace`, `workspace_name`,
`window_id`, `name`, `title`, `command`, `cwd`, `focused` and `agent_state`.
`--text` adds `text`, or `text_error` when the pane's text cannot be read. The
command reads text with `capture-pane`, so the same grants apply. A pane that
holds `read` alone lists only its own session, and the JSON has an `errors`
entry for the listing it may not make. These are the rows that the pane
navigator (`Ctrl+B /`) shows.

**Examples:**
```bash
# List windows in table format
tuios list-windows

# Every pane of every session, with the last 20 lines of each screen
tuios list-windows --all --text 20 --json

# Output as JSON for scripting
tuios list-windows --json

# Query a specific session
tuios list-windows -s mysession --json
```

**Example output:**
```
╭─────┬──────────┬───────┬────┬───────┬───────╮
│ IDX │ ID       │ NAME  │ WS │ SIZE  │ AGENT │
├─────┼──────────┼───────┼────┼───────┼───────┤
│ *0  │ 0ceb415a │ dev   │ 1  │ 60x38 │ none  │
│ 1   │ ce9ae44c │ build │ 1  │ 60x38 │ none  │
╰─────┴──────────┴───────┴────┴───────┴───────╯

2 windows. * marks the focused one.
```

The `ID` column is the 8-character prefix that `-w` accepts. With no windows
the command says so and points at `tuios new-window`.

**JSON Output Structure:**
```json
{
  "current_workspace": 1,
  "focused_index": 0,
  "focused_window_id": "0ceb415a-9f5c-44d8-a57c-60c132f54572",
  "message": "command executed",
  "success": true,
  "total": 2,
  "windows": [
    {
      "agent_state": "none",
      "custom_name": "dev",
      "cwd": "/home/me/src/api",
      "display_name": "dev",
      "focused": true,
      "height": 38,
      "index": 0,
      "minimized": false,
      "pty_id": "fd022e1f-7d42-4c45-8ddf-5ecaf8bee488",
      "title": "Terminal 0ceb415a",
      "width": 60,
      "window_id": "0ceb415a-9f5c-44d8-a57c-60c132f54572",
      "workspace": 1,
      "x": 0,
      "y": 0
    },
    {
      "agent_state": "none",
      "custom_name": "build",
      "cwd": "/home/me/src/api",
      "display_name": "build",
      "focused": false,
      "height": 38,
      "index": 1,
      "minimized": false,
      "pty_id": "23ed3d8a-b6f4-4047-b01a-3d2f1dd83515",
      "title": "build",
      "width": 60,
      "window_id": "ce9ae44c-7e64-424c-acd9-48cb21ac55c5",
      "workspace": 1,
      "x": 60,
      "y": 0
    }
  ],
  "workspace_windows": [2, 0, 0, 0, 0, 0, 0, 0, 0]
}
```

`custom_name` is present only on a window that was given a name, `cwd` only
when the shell has reported its directory, and `host` only when the window's
process runs on another machine. `agent_message` and `agent_state_at` appear
once a pane has reported an agent state. `agent_resumable` names the harness
of a pane whose agent conversation a daemon restart would offer back, and is
absent on every other pane. `tuios restart-server` reads it. The daemon answers
this from its own state, so the shape is the same whether or not a client is
attached.

### `tuios get-window`

Get detailed information about a specific window.

**Usage:**
```bash
tuios get-window [id-or-name] [flags]
```

**Arguments:**
- `id-or-name`: Window ID or custom name. If omitted, returns the focused window.

**Flags:**
- `-s, --session <name>`: Target session (default: this pane's session, else the most recently active).
  `host:session` reads a session on another machine.
- `--json`: Output as JSON (default is human-readable)

It reads with the `get-window` verb, so from inside a pane it needs only the
`read` grant, on the pane's own session and its fan group. Against a daemon
from before that verb it sends the client protocol's `GetWindow` command, as
it used to.

**Examples:**
```bash
# Get focused window info
tuios get-window

# Get focused window as JSON
tuios get-window --json

# Get specific window by name
tuios get-window dev --json

# Get window by ID
tuios get-window a1b2c3d4 --json

# Query a specific session
tuios get-window -s mysession dev --json
```

**Example output:**
```
name           build
id             e5f6a7b8-1c2d-4e3f-9a8b-7c6d5e4f3a2b
index          2
title          Terminal e5f6a7b8
workspace      1
size           120x40
focused        false
minimized      false
agent          working
agent message  awaiting approval
```

The `agent message` line appears only when the pane reported one.

**JSON Output Structure:**

With a client attached, the client answers:

```json
{
  "cursor_visible": true,
  "cursor_x": 40,
  "cursor_y": 0,
  "custom_name": "build",
  "display_name": "build",
  "focused": false,
  "fullscreen": false,
  "has_foreground_process": false,
  "height": 38,
  "id": "ce9ae44c-7e64-424c-acd9-48cb21ac55c5",
  "message": "command executed",
  "minimized": false,
  "pty_id": "23ed3d8a-b6f4-4047-b01a-3d2f1dd83515",
  "scrollback_lines": 0,
  "shell_pgid": 46889,
  "success": true,
  "title": "build",
  "width": 60,
  "workspace": 1,
  "x": 60,
  "y": 0
}
```

With no client attached, the daemon answers with one entry of the
`list-windows` shape above: `window_id` rather than `id`, plus `index`, `cwd`
and `agent_state`, and no cursor or process fields.

### `tuios session-info`

Get information about the TUIOS session state.

**Usage:**
```bash
tuios session-info [flags]
```

**Flags:**
- `-s, --session <name>`: Target session (default: this pane's session, else the most recently active)
- `--json`: Output as JSON (default is human-readable)

**Examples:**
```bash
# Get session info in human-readable format
tuios session-info

# Get session info as JSON
tuios session-info --json

# Query a specific session
tuios session-info -s mysession --json
```

**Example output:**
```
session        work
display name   Payments API
accent         cyan
windows        3
workspace      1 of 9
tiling         tiling
size           120x40
attached       true
window size    latest
named          2=review
```

The `display name`, `accent` and `named` lines appear only when those are set,
and `host focus` only while a client is attached.

**JSON Output Structure:**
```json
{
  "accent": "",
  "current_workspace": 1,
  "display_name": "",
  "height": 40,
  "host_focus": "focused",
  "layout_mode": "bsp",
  "master_ratio": 0.5,
  "message": "command executed",
  "mode": "unknown",
  "num_workspaces": 9,
  "session_id": "2e131c6c-4555-4d08-8c4e-7abb25f5522f",
  "session_height": 40,
  "session_name": "work",
  "session_width": 120,
  "success": true,
  "tiling_mode": "tiling",
  "tui_attached": true,
  "width": 120,
  "window_count": 2,
  "window_size": "latest",
  "workspace_names": {},
  "workspace_order": null
}
```

**Fields:**
| Field | Description |
|-------|-------------|
| `session_name` | The session's name, the one `-s` takes |
| `session_id` | The session's id |
| `display_name` | The session's display name, empty when none is set |
| `accent` | The session's accent, empty when none is set |
| `current_workspace` | Active workspace number |
| `num_workspaces` | Number of workspaces the session has |
| `workspace_names` | Named workspaces, keyed by number. A workspace with no name is left out |
| `workspace_order` | Always `null`. A workspace's number is its position, so moving one renumbers it. Kept for scripts that read it |
| `window_count` | Number of windows across all workspaces |
| `tiling_mode` | `tiling` or `floating` |
| `layout_mode` | The tiling layout in use: `bsp`, `master-stack` or `scrolling`, or `unknown` before a client has reported one |
| `master_ratio` | The master pane's share of the width in the `master-stack` layout |
| `mode` | Always `unknown`. The input mode belongs to the attached client, which the daemon does not ask |
| `width`, `height` | The session's size in cells, as the last client sent it with its state |
| `session_width`, `session_height` | The size the daemon gave the session from its clients |
| `window_size` | The size policy in use: `smallest`, `largest` or `latest`. It is `smallest` while a client from before the option is attached. See [SESSIONS.md](SESSIONS.md#session-size-with-more-than-one-client) |
| `tui_attached` | Whether a client is attached |
| `host_focus` | Whether the person can be looking at the session, from the focus events of the attached clients' terminals: `focused` when any client's terminal has focus, `unfocused` when every one reported losing it, `unknown` when none is attached or a terminal never reports focus |

The theme is not listed here. It is a session option: read it with
`tuios get-config appearance.theme`.

### `tuios capture-pane`

Capture the content of a terminal pane and write it to stdout.

**Usage:**
```bash
tuios capture-pane [flags]
```

**Flags:**
- `-s, --session <name>`: Target session (default: this pane's session, else the most recently active)
- `-w, --window <id-or-name>`: Target window (default: focused)
- `-S, --scrollback`: Include the scrollback history. Without `--lines`, the capture keeps the last 3 commands in at most 2000 lines
- `--commands <N>`: Keep the last N commands of the scrollback in at most 2000 lines. It needs the shell's OSC 133 marks. Takes no `--lines`, `--last-command` or `--unwrap`
- `--lines <N>`: Keep only the last N lines. `0` keeps all
- `--ansi`: Preserve ANSI escape codes (colors, styles)
- `--resolved`: Rewrite ANSI index colours (31, 91, 38;5;n, ...) to 24-bit
  RGB, so a capture matches what a themed client paints. Indices below 16 come
  from the palette; the rest of the standard 256-colour cube and grey ramp use
  their fixed values. Implies `--ansi`. Without a palette this uses the xterm
  defaults.
- `--palette <#rrggbb,...>`: The 16 hex colours a client's theme paints ANSI
  indices 0-15 with, used by `--resolved`. Must have exactly 16 entries.
- `--json`: Output the result as JSON. A capture from another machine carries `host` and `"untrusted": true`
- `--last-command`: Capture only what the last finished command printed, as
  plain text, read between the shell's OSC 133 marks. Fails with
  `no_shell_integration` when no command has finished under them.
- `--unwrap`: Join the rows that the pane wrapped because a line was longer
  than the pane. Each line then comes back as the program wrote it, so a
  search finds a long path or URL. A row that ends with a newline stays a line.
- `--trim`: Drop the blank lines at the end of the capture.

A daemon older than this tuios refuses `--unwrap` and `--trim`. The command
then says to run `tuios restart-server`.

A `--ansi` capture without `--resolved` keeps the guest's SGR indices (e.g.
`\x1b[31m`); the consumer resolves them against its own palette. `--resolved`
is for consumers that render the capture verbatim, and implies `--ansi`.

`--lines` counts from the last line that has content, so the blank rows below
the cursor do not count. This is how you read the tail of a long scrollback
without pulling all of it.

A history holds 10,000 lines or more, which is too much for an agent to read.
So `--scrollback` without `--lines` keeps the last 3 commands. It finds them
by the shell's OSC 133 marks. Each command runs from its prompt to the next
prompt. The capture keeps at most 2000 lines. A command whose output is too
long keeps its command line, the start of its output and its end. One line
replaces the middle, for example `… 48,213 lines omitted …`. `--commands N`
keeps the last N commands under the same limit.

A shell that sends no marks gives the last 2000 lines. So does `--unwrap`,
because joined lines do not match the marks. `tuios doctor shell` prints the
lines that turn the marks on.

When the capture leaves something out, a note on stderr says what. With
`--json`, `lines_omitted` gives the count, `command_marks` says whether the
marks cut the capture, and `commands` gives each command's kept and omitted
lines. Use `--lines 0` to get the whole history. The `capture-pane` verb
itself has no cap, so the tmux shim and the MCP server get the whole history
as before. A daemon older than `--commands` refuses it, and the command tells
you to run `tuios restart-server`.

**Examples:**
```bash
# Capture the focused window's visible screen
tuios capture-pane

# Capture the last 3 commands of a window
tuios capture-pane -w build --scrollback

# Capture the last 10 commands
tuios capture-pane -w build --commands 10

# Capture the whole scrollback
tuios capture-pane -w build --scrollback --lines 0

# Read the last 40 lines a build printed
tuios capture-pane -w build --scrollback --lines 40

# Capture with ANSI colors preserved
tuios capture-pane --ansi

# Capture with colours resolved to RGB against the current theme palette
tuios capture-pane --ansi --resolved --palette "#45475a,#f38ba8,#a6e3a1,#f9e2af,#89b4fa,#f5c2e7,#94e2d5,#bac2de,#585b70,#f38ba8,#a6e3a1,#f9e2af,#89b4fa,#f5c2e7,#94e2d5,#a6adc8"

# Pipe to a file
tuios capture-pane -w editor --scrollback > pane.txt

# What the last command in the build pane printed, and nothing else
tuios capture-pane -w build --last-command
```

---

### `tuios screenshot`

Render a window to a styled image and save it.

**Usage:**
```bash
tuios screenshot [flags]
```

**Flags:**
- `-s, --session <name>`: Target session (default: this pane's session, else the most recently active)
- `-w, --window <id-or-name>`: Target window (default: focused)
- `-f, --format <fmt>`: `png` (default), `svg`, `ansi`, `html` or `txt`
- `--frame <style>`: `window` (default), `plain` or `none`
- `--theme <name>`: Render in this palette instead of the session's
- `-o, --out <path>`: Write here instead of a generated name
- `-S, --scrollback`: Put the pane's history above the screen
- `--lines <N>`: Bound the history to the last N rows
- `--cursor`: Draw the cursor cell
- `--copy`: Try to copy the image to the clipboard (the default)
- `--no-copy`: Do not try to copy the image to the clipboard
- `--json`: Output the result as JSON

The daemon renders and writes the file, so this works on a detached session
with nobody attached. It prints the path it wrote.

Everything about the frame comes from the `screenshot.*` options: padding, a
wash derived from your theme, corner radius, shadow, title bar and window
control marks. `png` and `svg` carry the frame; `ansi` and `txt` are the bare
stream.

With no theme set, basic and indexed colors fall back to the xterm reference
defaults. Only your terminal knows its own palette, so that is a guess and the
result says so on stderr. `--theme` renders in a named palette instead.

A capture is drawn in your terminal's own font where the terminal will say
which font that is. kitty answers that question, so a capture from a kitty
client comes out with your Nerd Font icons in it and no setting to make.

Where the terminal does not answer, `screenshot.font_family` names the font to
draw with, and `screenshot.font_file` points straight at a file and wins over
everything else. The daemon renders with those two as well, because it has no
terminal to ask. With none of them the capture is drawn in a built in font that
has no icons, and a missing glyph draws as a dotted outline box rather than a
silent blank.

`screenshot.font_file` also embeds that font in SVG and HTML output so those
files stand alone, which makes them megabytes rather than kilobytes. Only that
setting does: a font tuios found by asking your terminal is used to draw the
picture and is not copied into an export you did not ask to be standalone.

**Examples:**
```bash
# The focused window, as a PNG under screenshot.directory
tuios screenshot

# A named window on a named session, detached is fine
tuios screenshot -s work -w build

# With history above the screen
tuios screenshot --scrollback --lines 200

# An SVG for a README
tuios screenshot --format svg --out demo.svg

# Re-render in another palette
tuios screenshot --theme catppuccin_mocha

# For a script
tuios screenshot --json
```

`tuios screenshot` draws no images. The daemon does not keep the pictures
that programs show with the kitty graphics protocol or with sixel, so the
image cells are blank. To include the images, take the capture in the TUI:
press the leader then `C`, or run the `Screenshot` command.

A capture in the TUI draws the images that the client shows:

- A kitty image, a kitty image in Unicode placeholder cells, and a sixel image
  are drawn at their cells.
- A pane scrolled into its history shows the images on its screen.
- `png`, `svg` and `html` draw images. `ansi` and `txt` do not.
- One capture decodes at most about 25 megapixels of images. An image past
  that limit is not drawn.
- A kitty image that a program streams as a temporary file or as shared
  memory is drawn only if it is not a stream of frames.
- A client keeps at most 8 MiB of kitty images for captures. When it needs
  more, it drops the images that are not on the screen first, then the
  oldest. A dropped image is not drawn.

Region and full screen captures are not CLI commands. They need a viewport and
composed chrome, which only an attached client has: press the leader then `C`
in the TUI and drag, or press `f`.

---

## More Commands

These commands have no section of their own here. Each one's `--help` lists
its flags and examples, and `tuios --skill` shows how an agent in a pane uses
them.

**Sessions:**

| Command | What it does |
|---------|--------------|
| `tuios resurrect [session-name]` | List the sessions saved on disk, or restore one and attach (also `tuios restore`). `--json` lists them for a script: `name`, `windows`, `status` (`restorable` or `live`) and `saved_at` |

Some commands also answer to a short name: `attach` to `a`, `new` to `n`,
`ls` to `list-sessions`, `resurrect` to `restore`, `hosts remove` to `rm`, and
`keybinds` to `keys` or `kb`.

**Windows and workspaces:**

| Command | What it does |
|---------|--------------|
| `tuios focus-window [window]` | Move the focus to a pane, by name, id, `--relative next` or `--direction left`. With `appearance.focus_wrap` on, `--direction` wraps at the edge of a tiled layout |
| `tuios move-window [workspace]` | Move a window to another workspace (`--follow` goes with it). `--to-session NAME` moves it to another session, and its program keeps running |
| `tuios select-workspace <workspace>` | Show a workspace |
| `tuios list-workspaces` | List the workspaces in a session and how many windows each holds |
| `tuios set-window` | Rename a window (`--name`), minimize it (`--minimize`) or restore it (`--restore`) |
| `tuios set-agent-quiet` | Keep a window's finished turns, questions and failures out of the Inbox. `--off` clears the mark. Needs an agent in the pane and the admin grant |
| `tuios split-window <horizontal\|vertical\|left\|right\|up\|down>` | Divide a pane and open a new one beside it. A side names where the new pane goes. Needs an attached client and tiling on |
| `tuios set-layout` | Turn tiling on or off (`--tiling`), reset the splits (`--equalize`: every split to half in BSP, and in master-stack the configured master ratio with even shares for the other panes), flip the focused split (`--rotate`), or shape the master-stack layout of the current workspace (`--master-position left\|right\|top\|bottom\|center`, `--masters N`). See [LAYOUT_MODES.md](LAYOUT_MODES.md#master-stack-layout) |

**Agents:**

| Command | What it does |
|---------|--------------|
| `tuios list-agents` | List the agent panes in a session and what each is doing. `--all-sessions` lists every session on this machine, each row named `session/name`; `--all-hosts` lists every session on every host, with a SESSION column, and a host that is down shows the rows it last gave. `--select` lists the panes a [selector](AGENT_STATE.md#selectors) matches, in every session, and prints the `--confirm` token for them. Each row carries `identity`, `confidence` and `evidence_age_ms` (see [AGENT_STATE.md](AGENT_STATE.md#confidence)), `subagents`, how many subagents the pane's agent is running, and with `--json` `subagent_list`, each subagent with its description, state (`running`, `done`, `failed`, `stopped`), the tool it runs and how it ended (see [AGENT_STATE.md](AGENT_STATE.md#each-subagent)) |
| `tuios list-attention` | List the Inbox: what is waiting for you in every session, on this machine and on every linked host (see below). `--host` narrows it to one machine, `--select` to what a selector matches |
| `tuios peek-prompt` | Show the prompt an agent is blocked on, its options and the answers it takes, without attaching |
| `tuios respond <action> [value]` | Answer the prompt an agent is blocked on. Only from the person: an attached client's Inbox, or a shell outside every pane with `[daemon] respond_from_shell`, or from a pane the person gave the `respond` grant |
| `tuios get-agent-state` | Read a pane's reported agent state. `--json` carries `identity`, `confidence` and `evidence_age_ms`: the milliseconds since the last evidence about the state arrived, or `null` for a pane that never had a state, and `subagents`, how many subagents the pane's agent is running (see [Agent metadata](AGENT_STATE.md#agent-metadata)) |
| `tuios set-agent-meta [key=value ...]` | Record display metadata about a pane's agent (model, context, a summary) for the rail |
| `tuios set-agent-session <id> --harness <h>` | Record which conversation a pane's agent runs, for a later resume, without changing its state |
| `tuios resume-agent [-w pane] [--dry-run]` | Type the pane's recorded conversation's resume command into its shell, after a daemon restart |
| `tuios send-agent-message <text>` | Leave a message in another agent's inbox, or post a notice to the session. `--from` names the sender, and defaults to the pane the command runs in. `--from human` from inside a pane is refused with `forbidden`: only the person at an attached client can send as `human` (see [Who can act as the person](AGENT_STATE.md#who-can-act-as-the-person)). With `-s HOST:SESSION` and that host's link down, the message waits on this machine and goes when the link is back; the Inbox shows it under Waiting to send. `--select` sends one message to every agent pane a selector matches, after listing them: it asks at a terminal, and takes `--yes` or `--confirm TOKEN` otherwise. `--subject` gives it a one-line subject (at most 120 characters), `--reply-to ID` joins that message's thread, and `--attach PATH` (absolute, repeatable, at most 8) attaches files |
| `tuios read-agent-messages` | Read the messages agents have left in this session. Each body prints inside the untrusted fence, and every body line starts with `│ `, as in `ask-agent` replies and `peek-prompt`. Reading `-w human` from inside a pane is always a peek. `--unread` shows only unread messages, `--peek` reads without marking anything read, except that a peek by a pane of its own inbox (`-w "$TUIOS_PANE_ID"`) marks its unread messages seen, so the sender can tell they were looked at. A peek of another pane's inbox marks nothing, `--notices` includes the session-wide notices |
| `tuios ask-agent <text>` | Ask another agent a question and wait for its answer. `--from` names the asking pane, and defaults to the pane the command runs in. Fails with `prompt_stalled` when the target shows no sign of taking the question within `--stall-timeout` (5000 ms) of Enter. `--select` asks every agent pane a selector matches, at most 16 at once, after the same confirmation as `send-agent-message --select`; a pane on `needs_input` is refused in its own row. `--settle MS` (2000) is the silence that counts as finished for a pane that reports no state; `--allow-blocked` types at a target on `needs_input`, answering its prompt |
| `tuios queue <text>` | Leave a message for an agent that is typed as a prompt when it comes to rest, never over a prompt it waits on and never twice. `queue ls` lists what waits, `queue rm ID` or `queue rm --all -w PANE` drops it. See [`tuios queue`](#tuios-queue) |
| `tuios review [SESSION]` | Show what the agent in a pane changed against its base, with the notes left on it. `review note FILE:LINE TEXT` leaves one, `review notes` lists them, `review send` sends the unsent ones to the agent as one queued message. See [`tuios review`](#tuios-review) |
| `tuios start-agent <agent>` | Start an agent in a new pane and return once it shows it is at its prompt, optionally typing a first `--prompt`. `-s HOST:SESSION` starts it on another machine, in its checkout of the repository you are in. `--protocol acp\|codex` runs it headless as a transcript. See [above](#tuios-start-agent) |
| `tuios agent-proto --protocol P -- <agent>` | The pane program of `start-agent --protocol`: run an agent headless over ACP or the Codex app-server and show it as a transcript. See [above](#tuios-agent-proto) |
| `tuios explain-agent-detect` | Show what the agent detector sees in a pane |
| `tuios explain-agent-screen` | Show what a harness's screen and title rules make of a pane: the tail, each rule's region and the text it read there, why each refusal refused (strings, patterns, nested groups), the title and last OSC 9;4 progress report, and which manifest file is in force |
| `tuios integration install [harness...]` | Write tuios's managed hook entries or plugin into a harness's configuration: claude-code, codex, copilot, cursor-agent, gemini-cli, opencode, kilo, amp, kimi, pi, omp and qwen report state; antigravity, crush, devin, droid, grok, hermes and qoder report the session id only (`--all` for every harness that has run here, `--command` for a tuios not on PATH). `--mcp` also registers `tuios mcp` as an MCP server named tuios with claude-code, codex, gemini-cli and opencode, without the tools that type into panes. `--mcp-write` registers it with `--write`. `--statusline` points Claude Code's status line at `tuios agent-statusline`, which feeds the model, context use and cost to the rail; a status line of your own is never replaced, and `--then CMD` (which implies `--statusline`) chains to it. For claude-code, codex, opencode and pi it also writes a short tuios skill that tells the agent to run `tuios --skill`; a tuios skill you wrote, changed or linked is left alone, and `--no-skill` writes none. See [Agent state](AGENT_STATE.md#harness-integrations) |
| `tuios integration uninstall [harness...]` | Remove the hook entries tuios wrote, the MCP server entry it wrote and the Claude Code status line it wrote (putting back the command it chained to), and nothing else |
| `tuios integration status [harness...]` | Say whether each integration is installed and current, and whether it reports state or the session id, for the four harnesses with an MCP registration whether `tuios mcp` is registered, and for Claude Code whether the status line feed is installed (`--json`, with `reports`, `mcp` and `status_line`) |
| `tuios mcp` | Serve tuios to an agent harness as an MCP server over stdio. By default it cannot type into a pane, and it is held to the session of the pane it runs in. Its default tools still set your own agent state and meta and send and read mail. `--write` adds the tools that type into panes. `--scope all` reaches every session. See [tuios mcp](#tuios-mcp) |
| `tuios doctor shell` | Per pane: whether its shell marks its commands with OSC 133, which `tuios run`, `wait-for command-finished` and `capture-pane --last-command` need, and, when one does not, the lines that turn the marks on for your `$SHELL` (zsh, and bash 4.4 or newer; fish 4 sends them itself). A pane that marks its prompts and ran a command without marking it is flagged as prompt marks only, and one that has not run a command yet is said to mark its prompts (`-s`, `--json`, with `command_mark_seen` and `prompt_marks_only`) |
| `tuios doctor agents` | Per harness: on PATH or not, integration installed and current or not, what it reports, the recognised harnesses with no integration and why, the running agent panes whose integration is missing or out of date with the command that fixes each, and the harness manifests loaded from the user manifest directory, which of them replace a bundled one, and the files there that failed to load (`--json`) |
| `tuios agent-hook <harness> [event]` | What an installed hook runs: read the hook payload on stdin and report the pane's state, or for a session integration only its conversation id (`set-agent-session`). For Claude Code and Codex the prompt, tool and Stop events also carry the event as activity for [`tuios agent-log`](#tuios-agent-log), and a `Stop` reports `done` with the first line of what the agent said last. Claude Code's `SubagentStart` and `SubagentStop` report no state: they send the subagent with `report-agent-activity`, which moves the pane's `subagents` count, and a `SessionStart` sends a `session_start` there after its state report, which clears it. A report that ends a turn also sends what the pane's `agent-statusline` feed held back (`set-agent-meta`). For Claude Code and Codex, `SessionStart`, `UserPromptSubmit` and `PostToolUse` also add one line about the pane's unread mail to the agent's context, once per message: the count, the senders and the `read-agent-messages` command. It never holds a subject or a body. `--explain` prints the decision to stderr. With `[agents.approvals]` naming the harness, a permission prompt (Claude Code `PermissionRequest`, including an `ExitPlanMode` plan unless `hold_plans = false`, Qwen Code `PermissionRequest`, opencode or Kilo `permission.asked`) then waits for an answer from the Inbox and prints the harness's decision, or nothing when there is none. See [Agent state](AGENT_STATE.md#harness-integrations) and [Approvals from the Inbox](AGENT_STATE.md#approvals-from-the-inbox) |
| `tuios agent-statusline <harness>` | What the Claude Code status line `integration install --statusline` writes runs, and what the opencode and Kilo plugins run for the model and cost: write the model, context use and cost on stdin to the pane's agent metadata. `--then CMD` chains to your own status line. See [above](#tuios-agent-statusline) |
| `tuios tmux-shim [-- command]` | Run a command (your shell when none is given) with a `tmux` on PATH that answers in this tuios session, so a tool that drives tmux, such as Claude Code agent teams (`tuios tmux-shim -- env CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude`), opens its panes here. Off until you run it. `--log FILE` moves the log of calls the shim could not answer from `$XDG_STATE_HOME/tuios/tmux-shim.log`; `--log-all` records every call. Not on Windows. See [The tmux shim](TMUX_SHIM.md) |
| `tuios tmux <tmux arguments>` | The shim asked for by name: answer one tmux command line (`tuios tmux display-message -p '#{pane_id}'`). In a pane, it answers in the caller's session. Outside a pane, every tuios session is a tmux session. A tmux session is a tuios session, a window `@N` is workspace N, a pane `%N` is a tuios window. See [The tmux shim](TMUX_SHIM.md#commands) for the commands it answers |
| `herdr <herdr arguments>` | tuios run through the `herdr` link that the daemon makes beside its socket, which every pane gets as `HERDR_BIN_PATH`. It answers herdr's command line (`pane`, `tab`, `workspace`, `agent`, `worktree`, `notification show`, `api snapshot`), so tools built for herdr work in a tuios pane: `"$HERDR_BIN_PATH" pane split --pane "$HERDR_PANE_ID" --direction right`. It prints herdr's JSON and uses herdr's exit codes. `tuios pane ...` and `tuios notification ...` answer the same two groups. See [herdr's command line](AGENT_STATE.md#herdrs-command-line) |
| `tuios pane-grants` | Show the pane this runs in and what it may do through tuios. See [below](#tuios-pane-grants) |
| `tuios set-pane-grants` | Give a pane grants (`--grants read,write`), or the default back (`--reset`). See [below](#tuios-pane-grants) |
| `tuios stash put <file>` | Copy a file into the session store and print the stored path |
| `tuios stash get <stored-path> [file]` | Copy a stashed file out of the session store, across a link |
| `tuios stash list` | List the files in the session store |

**Plugins:**

| Command | What it does |
|---------|--------------|
| `tuios plugin-cell set ID TEXT [--action ACTION]`, `tuios plugin-cell clear ID` | From a plugin with the `ui` grant: set or clear a dock cell its manifest names. A click runs `ACTION` |
| `tuios plugin-notify TEXT [--level LEVEL]` | From a plugin with the `ui` grant: show a notification under the plugin's name |
| `tuios plugins install SOURCE [--ref REF] [--subdir DIR] [--yes] [--no-enable] [--no-build] [--replace] [--grant admin]` | Get a plugin with git, build it, pin its commit in `plugins.lock` and enable it. `SOURCE` is the name of a plugin of the tuios release, such as `pr-status`, `owner/repo[/dir][@ref]` on github.com, a git URL (`https://`, `ssh://`, `git@host:path`, `file://`) with an optional `@ref`, or a local folder. tuios shows the plan and asks first. A native plugin that asks for `admin` needs `--grant admin`. Each install builds into a new folder. A failed build changes nothing that runs. Needs `git`. Refused inside a pane |
| `tuios plugins update [ID...] [--check] [--yes] [--grant admin]` | Move installed plugins to the newest commit of their ref. tuios shows the commits and asks. It asks again, also with `--yes`, on a change to what the plugin runs or asks for, a rewritten history or a moved tag. `--check` changes nothing. Exits 3 when a source cannot be reached. Refused inside a pane |
| `tuios plugins uninstall ID [--yes]` | Undo `tuios plugins install`. Disable the plugin, stop its processes and close its panes. Remove it from `plugins.lock`, remove its folder in `$XDG_DATA_HOME/tuios/plugins/` and remove its approval. `ID` can also be the source you installed from. The config and state folders of the plugin stay. Refused for a plugin that `install` did not install: use `unlink` for a linked folder. Refused inside a pane |
| `tuios plugins approve ID [--deny] [--grant admin] [--yes]` | Allow a tuios plugin to run on this machine, or deny it. tuios shows what the plugin runs and its grants, and asks first. A plugin that asks for `admin` needs `--grant admin`. When the plugin's manifest changes, it waits for a new answer. Refused inside a pane and from a plugin |
| `tuios plugins new NAME [--id ID]` | Make a plugin folder that works: a manifest, a shell script, a README and a GitHub workflow that runs `check` and attaches the plugin to the release of a tag |
| `tuios plugins check [PATH]` | Read a plugin folder as tuios would. Print each problem and warning, and exit 1 when the plugin cannot load. Runs nothing, needs no daemon |
| `tuios plugins dev PATH` | Install a folder in place and reload it each time a file changes, until Ctrl-C. Asks once at the start. Refused inside a pane |
| `tuios plugins install [--yes]` | With no `SOURCE`: install each plugin in `plugins.lock` at its pinned commit. It does not enable them. `--yes` trusts the author of `plugins.lock` |
| `tuios plugins list [--json]` | List the plugins tuios finds, with the state of each and the reason: `on`, `off`, `error`, `waiting for approval` or `denied`. An installed plugin shows `managed` and its source and commit. Reads the files only. It runs no plugin code |
| `tuios plugins info ID [--json]` | Show a plugin's build and startup commands, actions, panes, event hooks and link handlers |
| `tuios plugins enable ID` | Add the plugin to `[plugins] enabled`. A running daemon starts it at once. Refused inside a pane |
| `tuios plugins disable ID` | Remove the plugin from `[plugins] enabled` and stop its processes. Refused inside a pane |
| `tuios plugins link DIR [--enable]` | Add a plugin folder to `[plugins] dirs`. The plugin stays off unless you add `--enable`. Refused inside a pane |
| `tuios plugins unlink ID` | Remove a linked folder from `[plugins] dirs`, disable the plugin and close its panes. Refused inside a pane |
| `tuios plugins build ID` | Run the plugin's `[[build]]` commands in its folder. Each command is shown before it runs. Refused inside a pane |
| `tuios plugins run ID ACTION [--wait]` | Run an action of an enabled plugin. `--wait` waits for it to end and prints its output |
| `tuios plugins open ID PANE [--placement P]` | Open a pane of an enabled plugin. `P` is `overlay`, `popup`, `split`, `tab` or `zoomed` |
| `tuios plugins stats [--json]` | Show each plugin's processes and memory now, and its runs and run time since the daemon started. No memory on macOS. Needs the daemon |
| `tuios plugins log [ID] [--limit N] [--json]` | Show the last runs of plugin commands, with their exit codes and output |

An enabled plugin runs with your rights. Grants are not a sandbox. See
[PLUGINS.md](PLUGINS.md).

**Other machines:**

| Command | What it does |
|---------|--------------|
| `tuios hosts` | List the machines in the `[hosts]` config table and the state of each link. A host whose tuios is too old to stream its agents is named below the table, with what to update: its agents are polled and what waits there is not in the Inbox. A host with mail waiting here for its link says how many |
| `tuios hosts add <name> <addr>` | Add a machine. `--tailnet` takes the address from your tailnet; `--command`, `--ssh-option` and `--connect-timeout` tune the link; `--repos-root DIR` says where the host keeps its checkouts, for `fan --host`, `worktree new --host` and `start-agent -s HOST:SESSION`, and is kept when the host is added again without it, as its link policy fields are |
| `tuios hosts remove <name>` | Remove a machine |
| `tuios hosts test <name>` | Open one link to a host and report what happened. `--start` starts the daemon there when it does not run. `--speed` measures how fast a copy to the host can be. `--dry-run`, `--json`. See [below](#tuios-hosts-test) |
| `tuios cp SRC... DST` | Copy files and folders between this machine and its hosts, or between two hosts. See [below](#tuios-cp) |
| `tuios transfers` | List the copies the daemon runs, and pause, resume, cancel, wait for or clear them (also `tuios copies`). See [below](#tuios-transfers) |
| `tuios hosts tailnet` | List the machines on your tailnet and which are offered as addresses |
| `tuios hosts signin [name]` | Open the Tailscale sign-in page of each host that waits for one, or of the named host. With no desktop, it prints the address. `--print`, `--json`. See [Tailscale SSH check mode](SESSIONS.md#tailscale-ssh-check-mode) |
| `tuios hosts sync [host...]` | Install the tuios version of this machine on the hosts in the `[hosts]` table, every host when none is named. `--dev` builds a checkout (`--src DIR`, or the current folder), `--binary PATH` sends a file, and a release build fetches its own release. The daemon on a host keeps its old version unless `--restart` is given, which lists what a restart ends and asks first (`--yes` without a terminal). `--start` starts each daemon that does not run, after the install. `--dry-run`, `--json`, `--local`. See [below](#tuios-hosts-sync) |
| `tuios pair` | Show a QR code that adds this machine to a phone. The phone sends its key, and you accept it. The key can only open a tuios link, with the policy of a new `[hosts.DEVICE]` table. See [below](#tuios-pair) |
| `tuios stdio-proxy [--as NAME]` | Hidden. What the other machine's daemon runs over ssh for a link. `--as` pins the name this machine's link policy is resolved for, whatever the other machine calls itself: put it in a forced command in `authorized_keys` (`command="tuios stdio-proxy --as laptop",restrict ...`) to make the policy a boundary. See [What another machine may do here](CONFIGURATION.md#what-another-machine-may-do-here) |

A call over a link that the far machine's policy does not allow fails with
`forbidden`, and the message names the capability and the `[hosts]` table on
that machine that grants it. By default a linked machine may not answer
prompts: `tuios respond -w HOST:SESSION:WINDOW` needs `"respond"` in `allow`
there.

**Configuration and appearance:**

| Command | What it does |
|---------|--------------|
| `tuios list-options [prefix]` | List every settable configuration option, with its type, default and accepted values. `--section NAME` lists one group, such as `sidebar` or `dock` |
| `tuios list-options --search <query>` | The options matching a fuzzy query on path, value or description, best first, as the settings page searches |
| `tuios get-config <path>` | Read a configuration option from a running session. `-s` names the session. `--json` adds the source: `session`, `config` or `default` |
| `tuios list-themes [theme]` | List the themes, and describe one. `--filter TEXT` lists only the ids that contain it, such as `gruvbox` |
| `tuios import-theme <file>` | Convert a terminal colour scheme into a tuios theme |
| `tuios theme reload` | Read the theme and glyph files again in every tuios client on this machine, and ask each terminal for its colours again. Clients also read the files when a file in the themes or glyphs directory changes |
| `tuios theme export <theme>` | Print a theme as a theme file, with only the colours that are different from its built-in base. `--full` writes all the colours. `--format base16` writes a base16 scheme |
| `tuios theme share <theme>` | Print a theme as one line that starts with `tuios-theme:v1:`, to paste in a message |
| `tuios keybinds preset [name]` | Show or set the keybind preset (`tuios`, `tmux`, `screen`, `zellij`). `list` shows every preset, `show NAME` prints its file |
| `tuios keybinds cheatsheet [preset]` | Show the keys a preset keeps, the tuios keys it moved, and what it does not have. `--json` |
| `tuios list-glyphs [set]` | List the glyph sets, and describe one |
| `tuios logs` | View daemon logs |

**Tape scripts:**

| Command | What it does |
|---------|--------------|
| `tuios tape play <file.tape>` | Run a tape file in interactive mode |
| `tuios tape exec <file.tape>` | Execute a tape file in a running session |
| `tuios tape validate <file.tape>` | Validate a tape file without running it |
| `tuios tape list` | List all saved tape recordings (`--json` for a script: `dir`, and `tapes` with `name`, `path`, `size` and `modified`) |
| `tuios tape show <name>` | Display the contents of a tape file |
| `tuios tape delete <name>` | Delete a tape recording |
| `tuios tape dir` | Show the tape recordings directory path |

### `tuios pair`

Show a QR code that adds this machine to a phone. You do not copy a key by hand.

The tuios phone app is not released yet. An Android app is in private
testing. An iOS app comes later. `tuios pair` pairs a phone with that app.

To use tuios on a phone today:

- Open tuios-web in the browser on the phone. Keep tuios-web on `localhost`
  and reach it over Tailscale or an ssh tunnel, or start it with a password.
  See [Who can connect](WEB.md#who-can-connect).
- Use [Collie](https://github.com/AltanS/collie) to talk to agents. Collie has
  its own pairing. It does not use `tuios pair`.

```
tuios pair [--name DEVICE] [--machine NAME] [--allow list,mail,open,write,respond,files] [--timeout 5m]
           [--listen HOST:PORT] [--listen-all] [--accept-local] [--authorized-keys PATH]
           [--advertise-ssh HOST:PORT,...] [--advertise-pair HOST:PORT,...]
           [--ssh-port 22] [--host-key PATH] [--command PATH] [--yes] [--json]
```

1. Run `tuios pair` on the machine.
2. Scan the code with the tuios app on the phone.
3. Compare the check code and the key fingerprint on the screen with the ones
   on the phone.
4. Type `y` to accept the key.

The question shows the device name, the check code, the key, the address the
request came from and the allow list:

```
A device asks to pair.
  Name:  phone
  Check: 482916
  Key:   ECDSA SHA256:...
  From:  192.168.1.23:51734
  Allow: list, mail
Compare the check code and the key with the phone. Add this key? [y/N]
```

tuios then changes two files, in this order:

1. It adds a new `[hosts.DEVICE]` table to `config.toml`, with `allow` set to
   `--allow`. Without `--allow`, the list is `list` and `mail`. tuios reads
   the file back. When the table is not there as the policy of the device,
   tuios stops and does not add the key.
2. It adds one line to `~/.ssh/authorized_keys`:

```
command="/usr/bin/tuios stdio-proxy --as phone",restrict ecdsa-sha2-nistp256 AAAA... tuios-pair:phone
```

The key can only run `tuios stdio-proxy --as phone`. `restrict` stops port
forwards, agent forwards and a terminal. The `[hosts.phone]` table sets what
the phone may do here. See
[What another machine may do here](CONFIGURATION.md#what-another-machine-may-do-here).

tuios refuses a device name that is in use here. Case does not matter. A name
is in use when:

- `config.toml` has a `[hosts]` table of that name.
- A forced command in the authorized keys file opens links under that name
  (`stdio-proxy --as NAME`).
- It is the name of this machine.

| Flag | What it does |
|------|--------------|
| `--name DEVICE` | The device name. It replaces the name the phone sends. Use letters, digits, dot, dash and underscore |
| `--machine NAME` | The machine name in the code. The phone shows it. The default is the host name, up to the first dot |
| `--allow LIST` | The `allow` list of the new `[hosts.DEVICE]` table. The default is `list,mail`. `files` lets the device read and write files here; a write from it lands only under the device's `files_roots` (the receive folder `~/Downloads/tuios` unless you add more in `config.toml`) and never in keys, credentials or shell start files |
| `--timeout D` | The time the code works. The default is 5 minutes. The maximum is 1 hour |
| `--listen HOST:PORT` | Listen on this address. Port 0 picks a free port. Without it, tuios listens on each address in the code |
| `--listen-all` | Let the listener use every interface, as `0.0.0.0` or `[::]` do, or a public address. tuios prints a warning for every interface |
| `--accept-local` | Accept a request from this machine. Use it for a phone in an emulator, or for a machine that runs tailscaled in userspace mode, which sends each tailnet connection from `127.0.0.1` |
| `--authorized-keys PATH` | The file for the key. The default is `~/.ssh/authorized_keys`. tuios makes the file (0600) and its folder (0700) when they do not exist |
| `--advertise-ssh LIST` | The ssh addresses in the code. They replace the addresses tuios finds |
| `--advertise-pair LIST` | The pairing addresses in the code. They replace the addresses tuios finds |
| `--ssh-port N` | The ssh port for the addresses tuios finds. The default is 22 |
| `--host-key PATH` | The ssh host public key in the code. The default is the first of `/etc/ssh/ssh_host_ed25519_key.pub`, `ssh_host_ecdsa_key.pub` and `ssh_host_rsa_key.pub` |
| `--command PATH` | The tuios path in the forced command. See below for the default |
| `--yes` | Accept the key without a question. Use it for tests only |
| `--json` | Print the link as the first JSON line and the result as the last |

The forced command uses the `tuios` on `PATH`, as `PATH` names it, when that
file is this tuios. For example, it uses `~/.nix-profile/bin/tuios` or
`/opt/homebrew/bin/tuios`, not the file in `/nix/store` or in the Homebrew
`Cellar`. An upgrade replaces that file, and a forced command with its path
stops working. When `tuios` on `PATH` is another binary, or is not there,
tuios uses its own path and prints a warning. Give `--command` to set a path
that stays the same after an upgrade.

tuios finds the addresses itself, in this order:

1. The MagicDNS name of this machine, when `tailscale status --json` answers.
2. Up to three LAN IPv4 addresses. tuios leaves out the interfaces of
   containers, VMs and VPNs.

`s` holds these addresses with the ssh port. `p` holds the addresses that
the listener uses, in the same order. The listener does not use a public
address without `--listen-all`, so `p` can be shorter than `s`. An address in
`p` and the address at the same place in `s` do not always name the same
interface. The phone tries the addresses of each list in order.

tuios refuses the authorized keys file before it shows the code when sshd
would not use keys from it. sshd checks the file, its folder and each folder
above it up to the home folder. tuios refuses one that anyone can write to or
that another user owns. It prints a warning for one that the group can write
to. Debian's sshd accepts a group that holds only you. Other builds of sshd
refuse it.

The code stops when one phone pairs, when the time runs out, or after three
wrong requests. A wrong request is a pairing request with a `mac` that does
not match. A request that is not a pairing request gets an error and does not
count. A key that is in the file already is refused. The key must be ECDSA
P-256, Ed25519, or RSA with 3072 bits or more.

A request with a good `mac` from this machine, or from a machine in the
`[hosts]` table, stops the pairing. A program on such a machine can read the
code from the screen or from a pane, and that program is not the phone.
tuios knows these addresses:

- This machine: each address of its interfaces, loopback included.
  `--accept-local` lets them through.
- A machine in `[hosts]`: the IP in its `addr`, the addresses that the host
  name in `addr` resolves to, and the tailnet IP of the tailnet machine of
  that name. tuios does not ask ssh, so an alias in `~/.ssh/config` with no
  DNS name is not found. `--accept-local` does not change this.

#### The pairing protocol

The QR code holds this link:

```
tuios://pair?v=1&m=MACHINE&u=USER&s=HOST:PORT,...&p=HOST:PORT,...&fp=SHA256:...&t=TOKEN
```

| Field | Value |
|-------|-------|
| `v` | `1` |
| `m` | The machine name |
| `u` | The ssh user |
| `s` | The ssh addresses: the tailnet name first, then the LAN addresses |
| `p` | The pairing addresses: the tailnet name first, then the LAN addresses the listener uses |
| `fp` | The SHA256 fingerprint of the ssh host key, as `ssh-keygen -lf` prints it |
| `t` | 16 random bytes in base64url without padding. It works one time |

The phone sends `POST /v1/pair` to an address in `p`, with a `Content-Length`
and a JSON body of at most 8 KiB:

```json
{"device": "phone", "key": "ecdsa-sha2-nistp256 AAAA...", "mac": "..."}
```

`mac` is base64url, without padding, of HMAC-SHA256. The HMAC key is the 16
bytes that `t` decodes to. The message is these three lines, joined with
`\n`, with no newline at the end:

```
tuios-pair-v1
phone
ecdsa-sha2-nistp256 AAAA...
```

##### The check code

Both screens show a check code of six digits. The phone computes it before it
sends the request, and shows it while the person answers the question here.

1. Compute HMAC-SHA256 with the 16 bytes of `t` as the key. The message is
   `tuios-pair-v1-check`, a `\n`, and the `key` field of the request, byte
   for byte.
2. Read the first 4 bytes of the result as a big-endian unsigned 32-bit
   integer.
3. Take that number modulo 1000000.
4. Write it as 6 decimal digits, with leading zeros.

A person who scanned the code and sent their own key gets another check code
than the phone shows.

##### The reply

The reply to a good request:

```json
{"ok": true, "device": "phone", "user": "gaurav", "command": "/usr/bin/tuios stdio-proxy --as phone",
 "host_key": "ssh-ed25519 AAAA...", "mac": "...", "check": "482916"}
```

The reply `mac` is made the same way over `tuios-pair-v1-ok`, the device
name and `host_key`. The phone checks this `mac` and checks that the
fingerprint of `host_key` is `fp`. Then it keeps `host_key` as the host key
for the addresses in `s`. `check` is the check code of the request. The phone
compares it with the code it computed. A refused request gets
`{"ok": false, "error": "..."}` and an HTTP status of 400, 403, 404, 405,
409, 410, 411, 413, 429 or 500.

### `tuios hosts test`

Open one link to a host and report what happened.

```sh
tuios hosts test build                    # dial build and report
tuios hosts test build --start            # start the daemon on build if it does not run
tuios hosts test build --start --dry-run  # show what --start does, and change nothing
tuios hosts test build --speed            # how fast a copy to build can be
```

| Flag | What it does |
|------|--------------|
| `--speed` | Measure the daemon's link to the host: the round trip, and bytes a second each way |
| `--start` | Start the daemon on the host when it does not run |
| `--dry-run` | Show what `--start` would do and change nothing |
| `--json` | Print the result as JSON |

When the host is up and no daemon runs there, the status is `no_daemon`. The
output gives the command to run on the host, with the tuios binary that the
link found:

```
build  gaurav@buildbox  no_daemon
The host is up and no tuios daemon is running on it.
To start the daemon, run this command on the host:
  /home/gaurav/.local/bin/tuios start-server
Or start it from this machine:
  tuios hosts test build --start
```

`--start` runs that command over the same ssh that the link uses. Then it
dials the host again and reports the new state. When a daemon already runs,
`--start` does nothing. When tuios is missing on the host, `--start` starts
nothing: run `tuios hosts sync NAME --start` to install tuios and then start
the daemon. The JSON is the host report, with `action` (`daemon started`,
`would start daemon`, `none` or `start failed`), `before` (the status before
the start) and `start_command`.

`--speed` measures the link that the daemon holds to the host, the way a copy
uses it. It needs a running daemon and a link that is up. It takes the middle
of five round trips of a small call. Then it sends 64 MiB of random bytes up
and 64 MiB down, on the same bulk streams that a copy uses. Random bytes do
not compress, so the result is the speed of the link itself:

```
build: round trip 12.4 ms, up 48.2 MiB/s, down 51.7 MiB/s (64.0 MiB each way, random bytes).
```

With `--json` the result has `host`, `bytes` (each way), `rtt_ms`, `up` and
`down` (bytes a second), `up_ms` and `down_ms`. The protocol verb is
`host-speed-test` (see [protocol.md](protocol.md#files-and-transfers)).

### `tuios hosts sync`

Install the tuios version of this machine on the hosts in the `[hosts]` table.

```sh
tuios hosts sync --dry-run          # the plan, and no change
tuios hosts sync --dev              # install a build of this checkout on every host
tuios hosts sync build lab          # only these hosts
tuios hosts sync build --restart    # install, then restart the daemon on build
tuios hosts sync build --start      # install if needed, then start the daemon if it does not run
tuios hosts sync --restart --yes --json
```

| Flag | What it does |
|------|--------------|
| `--dev` | Build the binary from a tuios checkout: `--src DIR`, or else the folder you are in. The version is `dev+COMMIT`, and `dev+COMMIT-dirty.HASH` for a tree with changes |
| `--src DIR` | The checkout to build. Sets `--dev` |
| `--binary PATH` | Send this binary. A host with a different system fails |
| `--restart` | Restart each daemon whose version is different |
| `--start` | Start the daemon on each host where it does not run |
| `--yes`, `-y` | Restart without a question. Needed for `--restart` without a terminal |
| `--dry-run` | Show the plan and change nothing |
| `--json` | Print the result as JSON |
| `--local` | Sync this machine too. Naming `local` does the same |
| `--ghostty` | Refused: the ghostty backend cannot be cross-compiled |

First, sync reads every host over ssh at once, four at a time: the system
(`uname -sm`), the tuios that the link finds there, and its version. Then it
reads the daemon over a link of its own. It reads the sessions of the daemon and the
panes that run a program. A pane runs a program when the foreground process of
its terminal is not its shell, or when the pane process is not a shell.

The binary for a release build is the archive of that release for each host
system. sync checks it against the published `checksums.txt` and sends it
over ssh, so the host needs no internet. Without a release, the command
builds the checkout you are in, or asks for `--src` or `--binary`. A build
for each system is made once, with the release flags (`CGO_ENABLED=0`,
`-trimpath`, `-ldflags "-s -w"`), and only for the systems that need it.

The binary goes where the host has tuios, when you can write that folder, and
a configured `command` is where it goes. Otherwise it goes to
`~/.local/bin/tuios`, and sync warns when a login shell on the host does not
find it there. sync never uses sudo. It writes the binary to a temporary file
in the same folder, checks its size and sha256, runs `--version` on it, and
then renames it into place. A daemon that runs the old file keeps running.

sync never restarts a daemon by default. The row says that the daemon still
runs the old version, and gives the command that restarts it. A client of the
new version can refuse to connect to an old daemon when the protocol changed.
With `--restart`, sync lists the sessions on each daemon that it will restart
and the panes with a running program, and asks. A restart is `kill-server`,
which saves every session, then `start-server`, which restores them. The
layouts come back with new shells, and the programs in them end. A daemon with
no sessions restarts without a question. A daemon that already runs the new
version is never restarted. On this machine, sync does not restart the daemon
of the pane it runs in.

With `--start`, sync starts the daemon on each host where it does not run,
with the binary that the host has after the install. On a host with no
tuios, sync installs tuios first and then starts the daemon. The row says
`daemon started`, and with `--dry-run` it says `would start daemon`. In
`--json`, `daemon.started` is true. Without `--start`, the row for a host
with no daemon gives the command that starts it.

One host that fails does not stop the others. The exit status is 1 when a host
failed. The table has one row per host: the system, the version before and
after, the daemon, and what was done.

All ssh calls of one run to a host use one shared connection, through a
private socket in `$XDG_RUNTIME_DIR` that is removed when the run ends. When
Tailscale SSH in check mode holds the login, one approval covers the run. On a
terminal, sync lists the link to open for each host, and asks to wait up to 5
minutes. Each host continues when you approve its login. Without a terminal,
or with `--json`, the host fails at once. Its row says `needs approval`, and
in `--json` it has `"error_kind": "tailscale_check"` and `approval_url`. A
login the tailnet policy refuses has `"error_kind": "tailscale_policy"`. See
[Tailscale SSH check mode](SESSIONS.md#tailscale-ssh-check-mode).

### `tuios cp`

Copy files and folders between this machine and the hosts in `tuios hosts`.

**Usage:**
```bash
tuios cp [flags] SRC... DST
```

The daemon runs the copy. A closed terminal does not stop it, and it goes on
after a dropped link or a daemon restart. `tuios cp` starts the daemon when
none runs. Every file is checked with sha256 before it is put in place.

**Examples:**
```bash
tuios cp ./build.tar build:                        # to the receive folder on build
tuios cp build:~/logs ./                           # a folder from build to here
tuios cp build:/var/log/app.log gpu:/tmp/          # from one host to another
tuios cp -m ./dist build:~/www/                    # move: remove the original after the check
tuios cp --contents ./site/ build:~/www/           # what is inside site, not site itself
tuios cp --json --conflict replace ./a.bin build:~/  # for a script
tuios cp --detach ./big.iso build:~/iso/           # start the copy and return
```

#### Paths

| Path | What it names |
|------|---------------|
| `/abs/path`, `./rel`, `~/x`, `rel` | A path on this machine. A relative path is relative to the folder you run the command in |
| `HOST:/abs/path` | An absolute path on the host |
| `HOST:~/x` | A path under the home folder on the host |
| `HOST:rel` | A relative path on a host is under its home folder: `build:logs` is `~/logs` on build |
| `HOST:` | The receive folder of the host (see below) |
| `local:PATH` | A path on this machine. Use it for a path with a colon in it, or write the path as `./a:b` |

The word before the first colon is a host when it is the name of a host in
`[hosts]`, or `local`. A path that starts with `/`, `.` or `~` is always on
this machine. A word before a colon that can be a host name, and is not the
name of a host, is an error with exit code 2. The message suggests the
nearest host name. Write such a path on this machine as `./a:b`.

`HOST:` alone is the receive folder of the host: `~/Downloads/tuios`, or the
first folder of `files_roots` in the config on that host. A host lets this
machine write only in its `files_roots`. So a copy to `build:~/` needs
`files_roots = ["~"]` in the config on build (see
[CONFIGURATION.md](CONFIGURATION.md#what-another-machine-may-do-here)).

#### Files and folders

The rules are the rules of `cp`:

- A DST that is a folder, or that ends in `/`, gets each SRC inside it.
- A DST that does not exist, with one SRC, is the new name.
- Several SRCs need a DST that is a folder and exists.
- A folder copies with all that it holds. `-r` is accepted and changes nothing.
- `--contents` copies what is inside a SRC folder instead of the folder.
- A folder into a folder that exists merges into it, file by file.

Links, named pipes, sockets and devices in a folder are not copied. The
summary names them.

#### Files that are there

A file that is there with the same bytes (sha256) is never copied again. So a
second run of the same copy is a quick check. A file that is there and
differs follows `--conflict`:

| Policy | Short flag | What it does |
|--------|------------|--------------|
| `ask` | | Ask for each file. The default when stdin and stderr are a terminal, without `--json` |
| `skip` | `-n` | Leave the file there as it is. The default in other cases, and always with `--detach` |
| `replace` | `-f` | Replace the file there |
| `keep-both` | `-b` | Keep the file there, and give the copy a new name |

`keep-both` names a copy from another machine `name (from HOST).ext`, such as
`report (from build).pdf`. A copy on one machine gets a number:
`report 2.pdf`. Give one policy only. Two of `--conflict`, `-n`, `-f` and `-b`
with different policies are an error.

`ask` shows each file, which one is newer and how the sizes differ:

```
~/www/index.html is there on build. The new one is newer, and the new one is 1.20 KiB larger.
Replace it, keep both, or skip? [r/k/s, or R/K/S for all files]
```

An upper case letter gives the same answer for every file of the copy. Another
key is not an answer, and the command asks again. Ctrl+C at the question
cancels the copy and gives no answer. When the terminal cannot be read, the
command also cancels the copy. `ask` needs a terminal. Without one, the
command stops with exit code 2.

#### What a copy keeps

A copy keeps the permission bits and the modification time of each file.
A file that arrives over a link is the exception. It gets the permission bits
under the receiving machine's umask, and never group or world write. The
execute bits stay. A copy from this machine to a host arrives over a link.
`--no-perms` gives each file the default permission bits. `--no-times` gives
each file the time of the copy. A copy never keeps the owner.

On a link the daemon compresses the bytes of a file that compresses well.
`--no-compress` turns this off. `--bwlimit` sets the most bytes a second, such
as `500K` or `5M`. `K`, `M` and `G` are 1024, 1024² and 1024³.

#### Flags

| Flag | What it does |
|------|--------------|
| `-m`, `--move` | Remove each original after its copy is checked. A folder move removes only what it copied |
| `-r`, `--recursive` | Accepted. A folder always copies with all that it holds |
| `--contents` | Copy what is inside a SRC folder, not the folder itself |
| `--conflict POLICY` | What to do with a file that is there and differs: `ask`, `skip`, `replace` or `keep-both` |
| `-n`, `--no-clobber` | The same as `--conflict skip` |
| `-f`, `--force` | The same as `--conflict replace` |
| `-b`, `--keep-both` | The same as `--conflict keep-both` |
| `--no-perms` | Do not copy permission bits |
| `--no-times` | Do not copy modification times |
| `--no-compress` | Do not compress the bytes on a link |
| `--bwlimit RATE` | At most this many bytes a second, such as `500K` or `5M` |
| `--json` | Print the events of the copy as JSON lines on stdout |
| `-q`, `--quiet` | Print only errors |
| `--detach` | Start the copy, print its id, and return |
| `--timeout DURATION` | Exit 5 when a host stays unreachable this long. The copy goes on |
| `--cancel-on-timeout` | With `--timeout`, cancel the copy too |

#### Output

On a terminal, `tuios cp` draws the progress on stderr: the copy, a bar, the
rate and the time left. A folder copy also shows the file it copies now.
Without a terminal it prints one line for each change of state, and at most
one progress line each ten seconds. At the end it prints one line on stdout
for each copy:

```
Copied 1,204 files, 38.2 MiB, to build:~/www/site (checked).
```

The lines after it name the files that were not copied, and why.

`--detach` prints the id of each copy on stdout and returns. Follow the copy
with `tuios transfers wait ID`. A detached copy has nobody to answer a
question, so its default `--conflict` is `skip`.

#### JSON events

`--json` prints one JSON object on each line of stdout. The `event` field names
the kind:

| `event` | Fields |
|---------|--------|
| `started` | `id`, `src`, `dst`, `files`, `bytes` |
| `progress` | `id`, `state`, `done`, `size`, `rate`, `eta_ms`, `files`, `files_done`, `current`, `wire_bytes`. At most four a second for each copy |
| `file` | `id`, `rel`, `state` (`done`, `same`, `skipped`, `conflict` or `failed`), `sha256`, `code` |
| `waiting` | `id`, `host`, `retry_in_ms`, `message`. A host is not reachable. The copy goes on when it is back |
| `conflict` | `id`, `rel`, `path`, `src_size`, `src_mtime`, `dst_size`, `dst_mtime`. Only with `--conflict ask` |
| `done` | `id`, `dst`, `files`, `files_done`, `bytes`, `wire_bytes`, `same`, `conflicts_skipped`, `conflicts_left`, `skipped`, `verified`, `sha256`, `exit` |
| `failed`, `cancelled` | `id`, `code`, `message`, `exit`. A copy that did not start has `src` instead of `id` |
| `timeout` | `exit` (5). A host was not reachable for `--timeout` |

```json
{"event":"started","id":"3f9a1c2b7d00","src":{"path":"/home/me/a.bin"},"dst":{"host":"build","path":"~/"},"files":1,"bytes":52428800}
{"event":"done","id":"3f9a1c2b7d00","dst":"build:~/a.bin","files":1,"files_done":1,"bytes":52428800,"wire_bytes":52428800,"same":0,"conflicts_skipped":0,"conflicts_left":0,"skipped":0,"verified":true,"sha256":"9f2c...","exit":0}
```

`exit` is the exit code this copy gives. The command exits with the worst of
them.

#### A host that goes away

When a host is not reachable, the copy waits for it in the daemon. It goes on
from where it stopped when the host is back. `--timeout 10m` makes the
command exit 5 when a host stays unreachable for ten minutes. The copy goes
on waiting in the daemon, and the command says that it still waits. Add
`--cancel-on-timeout` to cancel the copy too.

#### Ctrl+C

On a terminal, Ctrl+C asks a question:

```
Cancel the copy, or keep it running? [c/k]
```

`k` keeps the copy running in the daemon, and the command returns. Follow the
copy with `tuios transfers`. `c`, or a second Ctrl+C, cancels the copy, and the
command exits 130. Without a terminal, with `--json`, or on SIGTERM, the
command cancels the copy at once.

#### In a pane

A copy started in a pane carries the name of the pane, and the pane grants
decide if the copy may start. `admin` may copy anything. `files` may copy only
inside the folder of the pane, and under the home folders or to the receive
folders of the hosts (see
[`tuios pane-grants`](#tuios-pane-grants)).

#### Exit codes of tuios cp

| Code | What it means |
|------|---------------|
| `0` | Every file was copied, or was there with the same bytes |
| `1` | The copy failed. The message says why and what to do |
| `2` | The command line is wrong, or a host name is not known |
| `3` | The copy is done, but some items were not copied: files skipped by the default `--conflict`, links, pipes and devices, or files made at the destination during the copy |
| `4` | Refused: the pane grants or the link policy of the host do not allow the copy |
| `5` | A host was not reachable for `--timeout` |
| `6` | A file did not match its original twice, or the file changed during the copy |
| `130` | Cancelled with Ctrl+C |

A file skipped by a `--conflict` policy that you gave does not give exit 3.

### `tuios transfers`

List the copies that the daemon runs, and control them. `tuios copies` is the
same command.

**Usage:**
```bash
tuios transfers [--json]
tuios transfers pause ID... [--json]
tuios transfers resume ID... [--json]
tuios transfers cancel ID... [--json]
tuios transfers wait [ID...] [--json] [-q]
tuios transfers clear [ID...] [--json]
```

The list has the copies that `tuios cp` started and the copies that other
clients started. A copy that ended stays in the list for 30 minutes, or until
`tuios transfers clear`. In a pane that holds the `files` grant and not
`admin`, the list has only the copies that the pane started. The other
subcommands act only on those copies.

```
╭──────────────┬─────────┬─────────┬──────────────────┬─────────────────────┬───────────────────────────────────────────┬────────────┬──────╮
│ ID           │ STATE   │ NAME    │ FROM             │ TO                  │ DONE                                      │ RATE       │ LEFT │
├──────────────┼─────────┼─────────┼──────────────────┼─────────────────────┼───────────────────────────────────────────┼────────────┼──────┤
│ 3f9a1c2b7d00 │ running │ big.iso │ /home/me/big.iso │ build:~/iso/big.iso │ 1.20 GiB / 4.00 GiB                       │ 48.0 MiB/s │ 59s  │
│ 8c01de4f9a77 │ done    │ site/   │ /home/me/site    │ build:~/www/site    │ 38.2 MiB / 38.2 MiB, 1,204 of 1,204 files │            │      │
╰──────────────┴─────────┴─────────┴──────────────────┴─────────────────────┴───────────────────────────────────────────┴────────────┴──────╯
```

The states are `queued`, `running`, `verifying`, `waiting` (for a host that
went away), `paused`, `conflict` (waits for an answer), `done`, `failed` and
`cancelled`.

| Subcommand | What it does |
|------------|--------------|
| `pause ID...` | Pause copies. What they copied stays |
| `resume ID...` | Go on with paused copies, try waiting copies now, or try failed copies again from where they stopped |
| `cancel ID...` | Cancel copies, and remove the part of the file in flight |
| `wait [ID...]` | Wait for the copies named, or for every copy that did not end. Show the progress as `tuios cp` does |
| `clear [ID...]` | Remove the copies that ended from the list, or only the copies named |

`pause`, `resume` and `cancel` exit 1 when one id fails. `--json` prints the
new rows. `clear --json` prints `{"cleared": N}`.

`wait` takes `--json` and `-q` as `tuios cp` does, and prints the same events.
Its exit code is the code `tuios cp` gives for the worst of the copies: `0`,
`1`, `3`, `4`, `6`, or `130` for a cancelled copy. An id that no copy has
exits 1. A copy that waits for a host has not ended, so `wait` goes on
waiting. `wait` cannot see the `--conflict` policy of a copy. So a file that
was there and differs always gives exit 3, as with the default policy of
`tuios cp`.

**Examples:**
```bash
tuios transfers
tuios transfers --json
tuios transfers pause 3f9a1c2b7d00
tuios transfers resume 3f9a1c2b7d00
tuios transfers cancel 3f9a1c2b7d00
tuios transfers wait 3f9a1c2b7d00 --json
tuios transfers clear
```

### `tuios pane-grants`

Show what the pane this command runs in may do through tuios.

**Usage:**
```bash
tuios pane-grants [--json]
tuios set-pane-grants [-s <session>] [-w <window>] (--grants <grant>[,<grant>...] | --reset) [--json]
```

Every pane holds grants, and the daemon checks every call from a pane against
them, however it was made:

| Grant | What the pane may do |
|-------|----------------------|
| `read` | Read its own session and its fan group, with `list-windows`, `get-window`, `capture-pane` and the rest |
| `write` | Type into the panes of its own session that hold nothing it does not, and leave mail there |
| `fan` | Write in its fan group and start agents with `fan` and `start-agent` |
| `respond` | Answer another pane's prompt with `respond`, without the person, and type into a pane waiting on a prompt |
| `files` | Copy files with `tuios cp`: a copy whose ends on this machine are inside the folder of the pane, and whose ends on a host are under its home folder or are its receive folder. It sees and controls only its own copies |
| `task` | Add, claim, finish, stage, block and release the task cards of its own session with `tuios task`. It claims only for itself and changes only the card it holds |
| `admin` | Everything else, as every pane could before grants, such as `run-command`, `attach` and `tuios task rm`. Includes `read`, `write`, `fan`, `files` and `task`, never `respond` |

A pane without `admin` types (`send-text`, `send-keys`, `run`, `ask-agent`,
`queue`) into another pane only when that pane holds nothing it does not,
since what it types runs with the target's grants, and into a pane on
`needs_input` only when it holds `respond`. A message it queues is checked
again against its grants as they are when the message is typed, and dropped
if they no longer cover the target. Its `send-keys` go to the target's
terminal, never through an attached client, so they cannot drive the window
manager.

A pane holds the grants it was started with (`--grants` on `start-agent`,
`fan` and `new-window`), the ones `set-pane-grants` gave it, or else the
default of `[agents.permissions]` (see
[CONFIGURATION.md](CONFIGURATION.md#what-a-pane-may-do)): `admin` under
`mode = "open"`, the default, and the `grants` list under `mode = "strict"`.
A call the grants do not cover fails with `forbidden`, and the message names
the grant it needed.

`set-pane-grants` from outside every pane may give anything. From a pane it
may change only that pane's own grants unless the pane holds `admin`, and
never give more than the pane holds, so an agent cannot widen itself, and it
cannot type into a pane that holds more to have that pane do it.

**Output:**
```
Pane a1b2c3d4 in session work holds read, write, fan (the default of [agents.permissions], mode strict).
```

**Examples:**
```bash
# From inside an agent's pane
tuios pane-grants

# Let the reviewer only read
tuios set-pane-grants -w reviewer --grants read

# Drop this pane's grants, then start an agent in it
tuios set-pane-grants --grants read,write && exec claude
```

---

## Scripting Examples

These remote control and inspection commands enable powerful scripting workflows.

### Create and Focus Windows

```bash
#!/bin/bash
# Create a development layout

# Create windows and capture their IDs
EDITOR_ID=$(tuios run-command --json NewWindow "editor" | jq -r '.window_id')
TERMINAL_ID=$(tuios run-command --json NewWindow "terminal" | jq -r '.window_id')
LOGS_ID=$(tuios run-command --json NewWindow "logs" | jq -r '.window_id')

# Enable tiling
tuios run-command ToggleTiling

# Send commands to each window
tuios send-keys --literal --raw "nvim ." && tuios send-keys Enter
tuios run-command FocusWindow "$TERMINAL_ID"
tuios run-command FocusWindow "$LOGS_ID"
tuios send-keys --literal --raw "tail -f /var/log/system.log" && tuios send-keys Enter
```

### Query and React to State

```bash
#!/bin/bash
# Wait for a specific condition

# Wait until there are at least 3 windows
while true; do
    WINDOW_COUNT=$(tuios session-info --json | jq '.window_count')
    if [ "$WINDOW_COUNT" -ge 3 ]; then
        echo "Ready with $WINDOW_COUNT windows"
        break
    fi
    sleep 0.5
done
```

### Run a Command and Wait for It

When the pane's shell marks its commands with OSC 133, one call does it and
exits with the build's own status:

```bash
tuios new-window build
tuios run -w build --timeout 120000 --lines 40 -- go build ./...
```

Without shell integration, assemble a marker:

```bash
#!/bin/bash
# Open a window, run a build in it, and block until it finishes.
# The marker is assembled by printf so the literal BUILD_OK never appears in
# the command line the pane echoes, which would match the wait immediately.

tuios new-window build
tuios send-text -w build 'go build ./... ; printf "BUILD_%s %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
```

### Integration with Other Tools

```bash
#!/bin/bash
# Use fzf to select and focus a window

WINDOW=$(tuios list-windows --json | \
    jq -r '.windows[] | "\(.display_name)\t\(.window_id)"' | \
    fzf --with-nth=1 | \
    cut -f2)

if [ -n "$WINDOW" ]; then
    tuios run-command FocusWindow "$WINDOW"
fi
```

### Automated Testing

```bash
#!/bin/bash
# Run a command and verify output

tuios send-keys --literal --raw "echo 'test-marker-12345'" && tuios send-keys Enter
sleep 0.5

# The marker shows twice once the command ran: in the echoed command line and
# in its output
COUNT=$(tuios capture-pane | grep -c 'test-marker-12345')
if [ "$COUNT" -ge 2 ]; then
    echo "command ran"
fi
```

---

### `tuios tml`

Show a TML document in tuios: a dashboard, a test result or a question. TML is
a markup for terminal surfaces: a tree of known components, such as text,
tables, stats, charts, tabs and buttons, with a JSON state. tuios draws it with
your theme's colours. Keys and the mouse work in it. The daemon keeps the
surface, so it stays when you detach and comes back when you attach.

**Usage:**
```bash
tuios tml show FILE [--popup | --pane] [--wait] [--width W] [--height H]
tuios tml show FILE --events
tuios tml patch SURFACE OPS
tuios tml replace SURFACE FILE [--keep-state]
tuios tml get SURFACE
tuios tml list [-s SESSION]
tuios tml close SURFACE [VALUE]
tuios tml validate FILE
tuios tml render FILE [--width N] [--height N] [--state JSON] [--tab ID] [--ansi]
```

FILE is a TML text or TML JSON file, or `-` for standard input.

`tml show` checks the document, opens it and prints the surface id and the
window id. A popup floats over the panes and needs an attached client. Press
`esc` to close it, unless the document uses `esc`. A pane (`--pane`) is tiled
like any pane.

With `--wait` the command stays open until the surface closes. It prints the
value the document closed with as JSON, such as `"rerun"`, and exits with
status 0. It prints `null` and exits with status 1 when the person closed the
surface without a value. It exits with status 2 when a program closed it with
`tml close`: the value it prints is then not the person's answer.

With `--events` the command prints the answer, then one JSON line for each
`tml-event` of the surface: an `emit` action the person ran, and the close,
which is the last line. A script that reads them is the surface's owner. It
answers with `tml patch`, a JSON Patch on the state (`-` reads it from standard
input), or `tml replace`, a new document. A patch with a `test` that no longer
matches is refused: read the state with `tml get` and send it again.
`tml list` names the open surfaces of a session.

`tml close` closes a surface. VALUE is JSON, and a waiting `tml show` prints
it.

From a pane, these commands need the `write` grant, and `tml patch`,
`tml replace` and `tml close` work only on the surfaces that pane opened. A
button's `pane('send-text', ...)` runs with the opening pane's grants, and tuios
asks the person before a surface first types into a pane. `tml validate` prints each problem with its line, the node and the fix,
and exits with status 1 when the document has errors. It needs no daemon.

`tml render` prints the document drawn as text, as tuios draws it in a pane,
and opens nothing. The width is the terminal's width, or 100 when standard
output is not a terminal. Without `--height` the document gets the rows it
takes. `--state` replaces the state, `--tab` opens a tab by its id, and `--ansi`
keeps the colours as ANSI escape sequences. It exits with status 1 and prints
the problems when the document is not valid. It needs no daemon.

`tuios capture-pane` on a TML window prints the surface as drawn, at the
window's size, with its state and the view of the client that last reported
one: the open tab, the cursor rows and the scroll place.

**Flags of `tml show`:**
- `-s, --session <name>`: Target session (default: this pane's session, else the most recently active)
- `--popup`: Show it as a popup (the default)
- `--pane`: Show it as a tiled pane
- `--name <name>`: Name for the window (default: the document's title)
- `--width`, `--height`: Popup size in cells or percent (default: 80% and 60%)
- `--workspace <n>`: Workspace to open it on
- `--wait`: Stay open until the surface closes, and print its value
- `--timeout <ms>`: With `--wait`, how long to wait
- `--json`: Output the result as JSON
- `--events`: Print the surface's events as JSON lines until it closes

**Examples:**
```bash
# Show a report as a popup
tuios tml show report.tml

# Show a dashboard as a pane, from standard input
some-generator | tuios tml show - --pane

# Ask a question and use the answer
answer=$(tuios tml show confirm.tml --wait)

# Own a dashboard from a script: answer each rerun with a patch
tuios tml show dash.tml --events | while IFS= read -r line; do
  case $line in
    *'"type":"tml_opened"'*) id=$(printf '%s' "$line" | jq -r .surface) ;;
    *'"name":"rerun"'*) tuios tml patch "$id" '[{"op":"replace","path":"/runs","value":2}]' ;;
  esac
done
```

A small document:

```xml
<tml version="1" title="Deploy">
  <state>{"tag": "v0.11.0"}</state>
  <col pad="1" gap="1">
    <text>Deploy <b>{state.tag}</b> to production?</text>
    <row gap="2">
      <button key="y" kind="primary" on-press="close('yes')">Deploy</button>
      <button key="n" on-press="close('no')">Cancel</button>
    </row>
  </col>
</tml>
```

The person can move a surface between a popup and a pane: `ctrl+b t f`, the
`dock` control on a popup's top border, or `float` on the pane's title bar.
The document keeps its state. Each document a pane shows is also listed in
the agents view, on the agent's Artifacts tab.

The verbs behind these commands are `tml-open`, `tml-patch`, `tml-replace`,
`tml-get`, `tml-list`, `tml-close`, `tml-place` and `tml-validate`, in
[protocol.md](protocol.md). The events are `tml-event`.

### `tuios mermaid`

Draw the Mermaid diagrams of a file in the terminal, or save them as SVG or PNG.

**Usage:**
```bash
tuios mermaid FILE [--format svg|png|kitty|text] [-o FILE] [--diagram N] [--theme NAME] [--background theme|none] [--fit]
```

FILE is a Mermaid source (`.mmd`), a Markdown file, or `-` for standard input.
A Markdown file gives each of its `mermaid` code blocks.

| Output | When |
|--------|------|
| `kitty` | The terminal shows kitty graphics: kitty itself, or tuios on such a terminal. The picture fits the terminal width |
| `text` | Any other terminal. Box-drawing characters draw the diagram, and the labels are text |
| `svg` | The output is not a terminal |

tuios draws eight diagram types itself: flowcharts, sequence diagrams, state
diagrams, class diagrams, ER diagrams, gantt charts, pie charts and mindmaps.
The sketch plugin draws the other types, such as timelines, git graphs and
sankey diagrams. Install it with `tuios plugins install sketch`. Then
`tuios mermaid` runs the plugin for such a diagram, with `--format`, `--out`,
`--cols`, `--diagram` and `--theme`. Without the plugin, the command says what
to run and exits 3. `--watch` and `--demo` draw the eight types only. A TML
panel draws another type with the plugin too. Without the plugin it shows the
source, and a notice says what to run.

`text` draws every type of the eight. Another type is written as its source,
with a note on stderr. A drawing wider than the terminal
is written at its full width, with a note on stderr.

The text of a `kitty` picture has the size of the terminal's text, so the
diagrams of a file have one text size. A small diagram is not made larger. A
diagram wider than the terminal is made smaller to fit the width. A diagram
taller than the terminal keeps its size and goes up into the scrollback: scroll
up to see its top. `--fit` also makes it smaller to fit the height, two rows
shorter than the terminal at most. The picture takes a fixed box of cells, so
the next diagram starts under it. A blank line goes between two diagrams.

A `kitty` or `png` picture has the background colour of the theme.
`--background none`, or `background = "none"` in `[mermaid]`, leaves the
background clear, so the diagram is on the background of your terminal. The
labels keep their contrast against the theme's background colour, so use a
theme that matches your terminal. An SVG has no background.

`-o FILE` saves to a file, as SVG or PNG from its extension. With more than one
diagram, the files get `-2`, `-3` and so on. `--scale` sets the pixels per SVG
unit of a PNG, 2 by default. `--cols` and `--rows` set the size in cells.

The colours come from your tuios theme, held to contrast floors against the
terminal background. `--theme NAME`, or `theme` in `[mermaid]`, picks another
theme:

| Theme | From |
|-------|------|
| `tuios` | Your tuios theme. This is the default |
| `pele` | pele's own colours |
| `flexoki`, `flexoki-dark` | The pele.run site, light and dark |
| `nord`, `everforest`, `gruvbox`, `rose-pine` | pele's launch video |
| `catppuccin-mocha`, `catppuccin-latte`, `tokyo-night`, `dracula`, `solarized-light`, `kanagawa` | Those terminal themes |

Text in a theme colour that lands on a fill the diagram sets itself changes to
the theme's text or background colour, where that reads better.

tuios does not typeset math. A label with `$$...$$` shows its TeX source as text.

**Live view:**
```bash
tuios mermaid FILE --watch [--split]
tuios mermaid [FILE] --demo [--loop]
```

`--watch` fills the terminal with the diagram and draws it again each time the
file is saved. In a terminal with kitty graphics the diagram moves to its new
layout: boxes slide and grow, new parts fade in, removed parts fade out. In
other terminals the text drawing is drawn again. `--split` shows the source
beside the diagram, or above it on a tall terminal. `--motion` sets the length
of a motion, 260ms by default.

`--demo` types a diagram one character at a time, for a recording. With FILE it
types that diagram line by line, or the diagrams of a Markdown file one after
the other. Without FILE it types a built-in flowchart. `--loop` starts again
two seconds after the end. Press `r` to start again and `q` to quit.

The live view sends no frames and uses no CPU while nothing moves.
tuios.dev/sketch draws the diagrams. It is a Go port of pele
and draws flowcharts, sequence diagrams, state diagrams, class diagrams, ER diagrams, pie charts, mindmaps, gantt charts, XY charts, timelines, quadrant charts, user journeys, kanban boards, git graphs, sankey diagrams, block diagrams, architecture diagrams, requirement diagrams, C4 diagrams, packet diagrams, radar charts, treemaps, info diagrams, tree views, Ishikawa diagrams, Cynefin diagrams, event models, Venn diagrams, Wardley maps, railroad diagrams, use case diagrams, agent flows and swimlane diagrams now. A diagram of another type gives
an error and its source. The command exits 1 when a diagram cannot be drawn.

---

### `tuios mcp`

Serve tuios to an agent harness as a Model Context Protocol server over stdin
and stdout. The harness starts it; nobody runs it by hand.

```bash
tuios mcp [--write] [--scope own|all]
```

**Flags:**

- `--write`: Also list the tools that type into panes: `tuios_send_text`,
  `tuios_send_keys`, `tuios_ask_agent`, `tuios_respond` and `tuios_fan`
- `--scope`: `own` (the default) reaches only the session of the pane the
  server runs in, its fan group, and the sessions a `fan` from it started.
  `all` reaches every session, for a harness that runs outside tuios

**Tools, by default:** `tuios_list_agents`, `tuios_list_windows`,
`tuios_get_agent_state`, `tuios_capture_pane`, `tuios_peek_prompt`,
`tuios_wait_for`, `tuios_read_agent_messages`, `tuios_send_agent_message`,
`tuios_set_agent_state`, `tuios_set_agent_meta` and `tuios_events`. Four of
them change state. `tuios_set_agent_state` and `tuios_set_agent_meta` change
the caller's own record. `tuios_send_agent_message` sends mail.
`tuios_read_agent_messages` marks the mail it returns as read. No default tool
types into a pane. Each is a
daemon verb, and its input schema is generated from the verb table, so it takes
the verb's own parameters. `tuios_events` follows the event stream: it returns
what happened since `after_seq`, or waits up to `wait_ms` for the next events,
and answers with the `last_seq` and `boot_id` to pass to the next call.
`last_seq` is where the daemon's stream stood when the call returned, even when
none of the events since were ones the call may see, so a server held to a
quiet session still moves forward. Only when `max_events` cuts the replay
short is it the seq of the last event returned.

**How it is held to its grant:** every tool call opens its own connection to
the daemon and calls `restrict-connection` on it first, so the daemon refuses
what the flags do not grant, with `forbidden`. The server finds its pane from
the kernel's record of its pid, and where the kernel cannot say, from
`TUIOS_PANE_ID` and `TUIOS_PANE_TOKEN`. A server with `--scope own` that runs
in no pane reaches nothing. A daemon too old to know `restrict-connection` runs
nothing, and the tool says to restart it. Text read from a pane or a message is
marked as data, not instructions. See [restrict-connection](protocol.md#restrict-connection).

The daemon's socket is `TUIOS_SOCKET` when the harness passes it, else the one
`tuios` always uses. A harness that starts its MCP servers without
`XDG_RUNTIME_DIR` still finds the daemon under `/run/user/<uid>` on Linux, as
every command does.

**Registering it:**

```bash
# Hooks and the MCP server without the tools that type into panes
tuios integration install claude-code --mcp

# With the tools that type into panes
tuios integration install codex --mcp-write

# By hand, in Claude Code
claude mcp add --scope user tuios -- tuios mcp
```

---

### `tuios ssh`

Run TUIOS as an SSH server for remote access.

By default, SSH sessions connect to the TUIOS daemon for persistent sessions with multi-client support. This means:
- Sessions persist even when clients disconnect
- Multiple clients can view/control the same session simultaneously
- Session state (windows, workspaces) is preserved across reconnections

**Usage:**
```bash
tuios ssh [flags]
```

**Flags:**
- `--host <string>`: SSH server host (default: "localhost")
- `--port <string>`: SSH server port (default: "2222")
- `--key-path <string>`: Path to SSH host key (auto-generated if not specified)
- `--default-session <string>`: Default session name for all connections
- `--ephemeral`: Run in ephemeral mode (standalone, no daemon)
- `--authorized-keys <string>`: Path to the public keys allowed to connect (default: `~/.config/tuios/authorized_keys`). Keys with options are not accepted
- `--no-auth`: Give every connection a shell without checking who it is (trusted networks only)
- `--handshake-timeout <duration>`: Close a connection that does not log in within this time (default: `2m0s`). `0` turns the limit off
- `--idle-timeout <duration>`: Close a connection after this time with no traffic (default: `0`, off)
- `--max-handshakes <int>`: Close a new connection at once when this many connections are logging in (default: `32`). `0` turns the limit off
- `--max-sessions <int>`: Refuse a new session when this many sessions are open (default: `64`). `0` turns the limit off

The four limit flags replace the same values in the `[ssh]` section of the
config file. A limit flag that you do not give keeps the value in the file. See
[SSH server limits](CONFIGURATION.md#ssh-server-limits).

**Who can connect:**

Every connection gets a shell on the machine running the server, so the server
checks who is connecting. It reads public keys from
`~/.config/tuios/authorized_keys`. It does not read `~/.ssh/authorized_keys`
unless you name that file with `--authorized-keys`.

- With keys: only the holders of those keys connect. Add a key while the server
  runs and it works on the next connection.
- With no keys file: the server does not start, on `localhost` too. It prints
  three ways to start: add your public key to
  `~/.config/tuios/authorized_keys`, pass
  `--authorized-keys ~/.ssh/authorized_keys`, or pass `--no-auth`.
- With `--no-auth`: every connection is accepted and the server prints one
  warning at startup. On `localhost`, every user on this machine can connect.
  On any other host, use it only on a network you trust.

TUIOS does not read `~/.ssh/authorized_keys` by itself. TUIOS does not apply
the rules in `sshd_config` to those keys.

A keys file that cannot be read, does not parse, or holds no key stops startup.
Only an absent file means "no keys are configured".

TUIOS does not accept a key that has options, such as `command=`, `from=` or
`restrict`. TUIOS cannot apply these options, and every session is a full
TUIOS. The server writes the line numbers of these keys to its log. A file
that holds only keys with options stops startup. To let such a key in, add it
again with no options to `~/.config/tuios/authorized_keys`.

```bash
# Let one key in. Use your public key file, for example ~/.ssh/id_ed25519.pub
mkdir -p ~/.config/tuios
cat ~/.ssh/id_ed25519.pub >> ~/.config/tuios/authorized_keys
tuios ssh --host 0.0.0.0 --port 2222

# Use the keys that sshd accepts
tuios ssh --host 0.0.0.0 --authorized-keys ~/.ssh/authorized_keys
```

The interface flags (`--theme`, `--border-style`, `--dockbar-position`,
`--ascii-only`, and the rest of the appearance set) apply to every served
session, layered over the server's config file the same way a local run
layers them.

Settings changed from the in-app settings page apply to that session only;
the server operator's config file is never written from an SSH client.

**Session Selection Priority:**
1. `--default-session` flag (if specified)
2. SSH username (if not generic like "tuios", "root", "anonymous")
3. SSH command argument (e.g., `ssh host attach mysession`)
4. First available session or create new

**Examples:**
```bash
# Start SSH server on default port (daemon mode). Needs
# ~/.config/tuios/authorized_keys, --authorized-keys or --no-auth
tuios ssh

# Start on custom port
tuios ssh --port 8022

# Listen on all interfaces
tuios ssh --host 0.0.0.0 --port 2222

# Read the allowed public keys from somewhere else
tuios ssh --authorized-keys /etc/tuios/authorized_keys

# Use custom host key
tuios ssh --key-path /path/to/host_key

# All clients share a single session
tuios ssh --default-session shared

# Run in ephemeral mode (no session persistence)
tuios ssh --ephemeral
```

**Connecting:**
```bash
# Basic connection
ssh -p 2222 localhost

# Connect to a specific session via username
ssh -p 2222 mysession@localhost

# Connect to a specific session via command
ssh -p 2222 localhost attach mysession
```

**Multi-Client Behavior:**
- When multiple clients connect to the same session, `window_size` in `[daemon]` sets the size of the session: the client that last had input (the default), the smallest client, or the largest client. See [SESSIONS.md](SESSIONS.md#session-size-with-more-than-one-client)
- State changes (window create/move, workspace switch, etc.) are broadcast to all clients in real-time
- Clients are notified when others join or leave the session

---

## `tuios-web` (Separate Binary)

**Security Notice:** The web terminal functionality has been extracted to a separate binary (`tuios-web`) to provide better security isolation. This prevents the web server from being used as a potential backdoor in the main TUIOS binary.

By default, web sessions connect to the TUIOS daemon for persistent sessions with multi-client support. This means:
- Sessions persist even when browser tabs close
- Multiple browsers/tabs can view/control the same session simultaneously
- Session state (windows, workspaces) is preserved across reconnections
- Settings changed from the in-app settings page apply to that session only; the server's config file is never written from a browser

**Installation:**
```bash
# Homebrew
brew install tuios-web

# AUR
yay -S tuios-web-bin

# Go install
go install github.com/Gaurav-Gosain/tuios/cmd/tuios-web@latest
```

**Usage:**
```bash
tuios-web [flags]
```

**Flags:**
- `--host <string>`: Web server host (default: "localhost")
- `--port <string>`: Web server port (default: "7681")
- `--read-only`: Disable input from clients (view only mode). A read-only client does not set the session size under `window_size` `largest` or `latest`. See [SESSIONS.md](SESSIONS.md#session-size-with-more-than-one-client)
- `--max-connections <int>`: Maximum concurrent connections (default: 0 = unlimited)
- `--cert <path>`: TLS certificate in PEM form (serves HTTPS; required to bind a non-loopback host)
- `--key <path>`: TLS private key in PEM form (required with `--cert`)
- `--auto-tls`: Generate and serve a self-signed certificate (managed with `tuios-web cert`)
- `--insecure`: Serve a non-loopback host over plain HTTP, unencrypted (trusted networks only)
- `--random-password`: Make a new password at start and print it
- `--password-file <path>`: Read the password from the first line of this file. The file must be yours, with mode 600 or 400 (on Windows, only you, SYSTEM and Administrators may read it)
- `--user <string>`: User name the browser must give with the password (default: "tuios")
- `--no-auth`: Serve a non-loopback host with no password (trusted networks only). Not with `0.0.0.0` or `::`
- `--allow-host <name>`: On a loopback `--host`, also accept this host name (no port) in the Host header, for example for a reverse proxy. Needs a password or `--no-auth`. You can give it more than one time
- `--touch <auto|on|off>`: Touch support and the on-screen key bar (default: auto-detect)
- `--default-session <string>`: Default session name for all connections (creates shared session)
- `--ephemeral`: Disable daemon mode (sessions don't persist)
- `--theme <name>`: Color theme forwarded to TUIOS instances
- `--show-keys`: Enable showkeys overlay
- `--ascii-only`: Use ASCII characters instead of Nerd Font icons
- `--border-style <style>`: Window border style
- `--dockbar-position <pos>`: Dockbar position
- `--hide-window-buttons`: Hide window control buttons
- `--window-button-style <style>`: Window control style: `pill`, `dots`
- `--window-button-position <position>`: Which end they sit on: `right`, `left`
- `--scrollback-lines <int>`: Scrollback buffer size
- `--no-animations`: Disable UI animations
- `--debug`: Enable debug logging

**Who can connect:**

Every browser that opens tuios-web gets a shell on this machine, and the
session switcher reaches every session. Set a password to control who
connects. The browser asks for the user name and the password.

- `--random-password`: tuios-web makes a new password at start and prints it
  with a URL that holds it.
- `--password-file <path>`: tuios-web reads the password from the first line
  of the file. The file must belong to you, with mode 600 or 400. On Windows,
  only you, SYSTEM and Administrators may read or change it.
- `TUIOS_WEB_PASSWORD`: tuios-web reads the password from this environment
  variable. It does not pass the variable to panes. But your own processes
  can still read it from `/proc`. Use `--password-file` instead.

There is no flag that takes the password itself. Other users can see command
line arguments in `ps`. A password from a file or from `TUIOS_WEB_PASSWORD`
that is shorter than 12 characters gets a warning at start, because
tuios-web does not slow down wrong guesses.

- On `localhost`: the password is optional. With no password, other users on
  this machine can connect. tuios-web prints one line at start to say so. Use
  `--random-password` to stop this. tuios-web accepts a session only when the
  Host header names this machine, such as `localhost` or `127.0.0.1`. This
  stops a web page that points its own name at 127.0.0.1 (DNS rebinding).
- Behind a reverse proxy on this machine: use `--allow-host <name>` to accept
  the proxy's host name. Give the name with no port. A proxied setup needs a
  password, so `--allow-host` does not start without a password or
  `--no-auth`. It works only with a loopback `--host`.
- On any other host: tuios-web does not start without a password. TLS
  encrypts the connection, but it does not check who connects. Pass
  `--no-auth` to serve anyway, on a network you trust. `--no-auth` does not
  work with `0.0.0.0` or `::`. These addresses also listen on this machine,
  where a web page in your browser can open a shell. Give the address of one
  interface.

**Subcommands:**
- `tuios-web cert`: Show the status of the self-signed TLS certificate `--auto-tls` uses
- `tuios-web cert new|info|path|remove`: Rotate, explain, locate, or delete it

**Features:**
- Full TUIOS experience in the browser
- WebGL-accelerated rendering via xterm.js for smooth 60fps
- WebSocket and WebTransport (HTTP/3 over QUIC) protocols
- Bundled JetBrains Mono Nerd Font for proper icon rendering
- Settings panel for transport, renderer, and font size preferences
- Cell-based mouse event deduplication (80-95% traffic reduction)
- Automatic reconnection with exponential backoff
- Self-signed TLS certificate generation for development
- No CGO dependencies (pure Go)
- **Persistent sessions via daemon mode** (default)
- **Multi-client support**: multiple browsers share the same session

**Examples:**
```bash
# Start web server on default port (daemon mode)
tuios-web

# Start on custom port
tuios-web --port 8080

# Reach the server from a phone on the same network, over TLS with a
# self-signed certificate tuios-web generates and keeps for you, and a
# password that tuios-web makes and prints
tuios-web --host 0.0.0.0 --port 7681 --auto-tls --random-password

# Or bring your own certificate and keep the password in a file
mkdir -p ~/.config/tuios
(umask 077; head -c 18 /dev/urandom | base64 > ~/.config/tuios/web-password)
tuios-web --host 0.0.0.0 --port 7681 --cert tuios-cert.pem --key tuios-key.pem \
  --password-file ~/.config/tuios/web-password

# Same, on a network you trust, with nothing encrypted and no password.
# --no-auth needs the address of one interface. It does not work with 0.0.0.0
tuios-web --host 192.168.1.20 --port 7681 --insecure --no-auth

# Start in read-only mode (view only)
tuios-web --read-only

# Start with theme and show-keys overlay
tuios-web --theme dracula --show-keys

# Limit concurrent connections
tuios-web --max-connections 10

# All clients share a single session
tuios-web --default-session shared

# Run in ephemeral mode (no session persistence)
tuios-web --ephemeral
```

**Multi-Client Behavior:**
- When multiple clients connect to the same session, `window_size` in `[daemon]` sets the size of the session: the client that last had input (the default), the smallest client, or the largest client. See [SESSIONS.md](SESSIONS.md#session-size-with-more-than-one-client)
- State changes (window create/move, workspace switch, etc.) are broadcast to all clients in real-time
- Clients are notified when others join or leave the session

**Accessing:**
```bash
# Open in browser
open http://localhost:7681

# For HTTPS/WebTransport (development with self-signed cert)
open https://localhost:7681

# Note: Your browser will show a security warning for the self-signed certificate.
# Click "Advanced" and proceed to accept the certificate.
```

**Protocol Selection:**
The client automatically selects the best available transport:
1. **WebTransport (HTTP/3 over QUIC)**: Lower latency, better multiplexing (requires HTTPS)
2. **WebSocket (fallback)**: Broad browser compatibility

For complete documentation, see [Web Terminal Mode](WEB.md).

---

### `tuios config`

Manage TUIOS configuration file.

**Subcommands:**
- `tuios config path`: Print configuration file path
- `tuios config edit`: Edit configuration in $EDITOR
- `tuios config reset`: Reset configuration to defaults
- `tuios config apply`: Apply `config.toml` to the running daemon and clients now
- `tuios config browse`: Search the settable options and set one, in an explorer
- `tuios config files`: List the files the config is read from
- `tuios config origin`: Show which file sets each key
- `tuios config prune`: Remove the keys of config.toml that have their default value

#### `tuios config apply`

Apply `config.toml` to the running daemon now, including the changes that give
panes or other machines more than they had.

Every tuios client on this machine also applies the file as it is now.

A process in a pane can write `config.toml`, so the daemon applies a change to
the bounds of panes and links at once only when the change gives less: a
narrower `[agents.permissions]` default or `[hosts]` link policy. A wider
policy, a new host to dial and a new `[notify]` destination wait for this
command or for a daemon restart. Run it from a terminal outside tuios. From
inside a pane it is refused.

```bash
tuios config apply
```

#### `tuios config path`

Print the location of the TUIOS configuration file.

**Example:**
```bash
tuios config path
# Output: /Users/username/.config/tuios/config.toml
```

#### `tuios config edit`

Open the configuration file in your default editor.

**Requirements:** The `$EDITOR` or `$VISUAL` environment variable must be set. Falls back to vim, vi, nano, or emacs if found.

**Example:**
```bash
export EDITOR=vim
tuios config edit
```

#### `tuios config browse`

Open the settable options in an explorer you can search. Each option shows its
type, default, current value and source. These are what
`tuios list-options --json` and `tuios get-config --json` print. Press `enter`
on an option to set it. The explorer sets it the way `tuios set-config` does,
with the same refusals, and shows the error `set-config` prints. It needs a
running daemon.

```bash
tuios config browse [-s session]
```

Press `/` to search, the arrow keys or `j` and `k` to move, and `tab` or a
click on a tab to show one group. `J` and `K` scroll the detail pane. `q` or
`esc` leaves it. An explorer opens only with its own flag or subcommand, never
because the output is a terminal, so a script or an agent in a pane always gets
the plain output.

#### `tuios config files`

List the files the config is read from, from lowest to highest precedence:
the files in the `include` list, the files in `config.d`, then config.toml. A
file that tuios cannot write shows as read-only. An include that names a
missing file or makes a cycle shows as a warning.

```bash
tuios config files [--json]
```

#### `tuios config origin`

Show which file sets each key, and the earlier files that set the same key.
Give a key to show that key and the keys under it only. A key that no file sets
has its default value.

```bash
tuios config origin [key] [--json]
tuios config origin hosts
```

See [Split the config into several files](CONFIGURATION.md#split-the-config-into-several-files).

#### `tuios config prune`

Remove the keys of config.toml that have their default value. An older tuios
wrote every key into config.toml, and config.toml wins over the files it
includes and the files in `config.d`. After the prune, a key that another file
sets takes the value of that file. The command lists those keys first and asks
before it changes the file. `--yes` skips the question, and a run with no
terminal needs it. The `[startup]` keys stay. The command keeps comments and
the `include` list.

```bash
tuios config prune --dry-run   # show the keys, change nothing
tuios config prune
tuios config prune --yes       # do not ask
```

#### `tuios config reset`

Reset the configuration file to default settings.

**Warning:** This will overwrite your existing configuration after confirmation.
The new config.toml is the one a first start writes: comments, `[startup]`
tiled and daemon on, and no other setting. It keeps the `include` list, and
lists the other files that still apply.

**Example:**
```bash
tuios config reset
# Prompts: Are you sure you want to reset to defaults? (yes/no):
```

---

### `tuios keybinds`

List the keybindings, check them for conflicts, and change them in
`config.toml`.

**Aliases:** `keys`, `kb`

**Subcommands:**
- `tuios keybinds list`: List every keybinding and the action it runs
- `tuios keybinds list-custom`: List the keybindings that differ from the defaults
- `tuios keybinds browse [search]`: Search the keybindings in an explorer
- `tuios keybinds doctor`: Report each key that two actions claim, and each key tuios takes from the pane
- `tuios keybinds explain <key>`: Say what tuios does with one key
- `tuios keybinds unbind <action> [key]`: Take a key off one action
- `tuios keybinds free <key>`: Hand a key back to the program in the pane

#### `tuios keybinds list`

List every action and the keys that run it, as your `config.toml` sets them.

**Flags:**
- `--json`: Print the rows as a JSON array

**Example:**
```bash
tuios keybinds list

# The keys of one action
tuios keybinds list --json | jq -r '.[] | select(.action == "toggle_tiling") | .keys[]'
```

**Output:** One table for each scope, in this order. Each table has the
columns Keys, Action and Description.
- The scopes: Global, Window mode, Terminal mode, Sidebar, Sidebar files,
  Sidebar agents, Inbox, Inbox prompt, Mailbox, Prefix, each prefix menu with
  its chord (Window, Minimize, Workspace, Debug, Tape and Layout), and Script
  playback. A key in a prefix menu shows with its chord, such as `ctrl+b L 5`.
- Commands: the `[[keybindings.command]]` entries, by description. See
  [KEYBINDINGS.md](KEYBINDINGS.md#command-keys).
- The fixed keys, which tuios reads itself and you cannot rebind: Copy mode
  (with the `[[keybindings.copy_pipe]]` entries), Hints mode, Message view,
  Spotlight, Lists and panels, Mouse and Sidebar mouse. The help overlay shows
  the same rows.
- No key: the actions that have no key. Bind one in `config.toml`, or run it
  from the command palette.

An action that a config leaves with no key shows `(none)` in its scope.

**JSON output:** An array of rows. Each row has these fields:
- `scope`: where the keys act, such as `window`, `prefix.layout`,
  `sidebar.files`, `copy_mode`, `mouse`, or `unbound`
- `scope_name`: the title of the table
- `chord`: what you press to reach the scope, such as `ctrl+b L`. Empty for a
  mode
- `section`: the `config.toml` table, `command`, `copy_pipe`, or empty for a
  fixed key
- `action`: the action name. Empty for a fixed key with no action
- `keys`: the keys that run the action, with the chord
- `description`: what the keys do
- `fixed`: true for a key that no table binds
- `unbound`: true for an action with no key
- `shadowed`: keys that the config gives the action, which a different action
  in the scope takes first

#### `tuios keybinds browse`

Open every keybinding in an explorer you can search. The rows are the rows of
`tuios keybinds list --json`, and the tabs are their scopes. A search given on
the command line starts the explorer with it.

```bash
tuios keybinds browse
tuios keybinds browse spotlight
```

Press `/` to search, the arrow keys or `j` and `k` to move, and `tab` or a
click on a tab to show one group. `J` and `K` scroll the detail pane. `q` or
`esc` leaves it. An explorer opens only with its own flag or subcommand, never
because the output is a terminal, so a script or an agent in a pane always gets
the plain output.

#### `tuios keybinds list-custom`

List only the keybindings that your `config.toml` changes.

**Example:**
```bash
tuios keybinds list-custom
```

**Output:** Three-column table showing:
- Action name
- Default keybinding
- Your custom keybinding

#### `tuios keybinds unbind`

Take a key off one action and write the change to `config.toml`.

```bash
# Stop w closing a window, leaving x
tuios keybinds unbind close_window w

# Leave the action with no key at all
tuios keybinds unbind close_window
```

An action with no keys is written as an empty list:

```toml
[keybindings.window_management]
close_window = []
```

That is not the same as leaving the action out of the file. An action the file
does not mention gets its default back the next time tuios starts. An empty list
stays empty.

#### `tuios keybinds free`

Take one key off every action in every scope, so the program in your pane
receives it.

```bash
# Give alt+left back to your shell
tuios keybinds free alt+left
```

Every scope at once is the point. A key tuios still claims anywhere is a key the
program never sees. Two keys cannot be freed this way: the leader key, which is
`keybindings.leader_key` and is moved rather than unbound, and a handful of keys
the input path reads directly. The command says so instead of reporting success.

You can do both from inside tuios as well. Open the keybind manager with the
leader key then `k`, or from the command palette, and press `ctrl+d` on a
binding to remove it or `ctrl+x` to take its key off every action. Typing `#`
in the command palette searches actions rather than commands: `Enter` runs the
action and `ctrl+e` opens the keybind manager on it.

---

### `tuios notify test`

Send a test notification through each provider in the `[notify]` table, and
say the result for each provider. See
[CONFIGURATION.md](CONFIGURATION.md#push-notifications-to-your-phone).

**Usage:**
```bash
tuios notify test [--json]
```

This command sends from its own process, not from the daemon. It reads a
`token_env` variable from your shell. The daemon reads it from its own
environment. The output shows the host of each provider and never a token
or the full address. It sends the same way the daemon does. The command
exits with 1 when a provider fails.

**Output:**
```
ntfy (ntfy.sh): sent.
pushover (api.pushover.net): sent.
webhook (hooks.example.com): failed. The server answered 401 Unauthorized. Check the token.
```

**Flags:**
- `--json`: Output a list with `provider`, `host`, `ok` and `error` for each provider

---

### `tuios notify push`

Register, list and remove the phones that get Inbox items by Web Push. See
[CONFIGURATION.md](CONFIGURATION.md#web-push-to-a-phone).

**Usage:**
```bash
tuios notify push register --device NAME --subscription FILE [--kind KIND]... [--json]
tuios notify push ls [--json]
tuios notify push rm NAME [--json]
```

Each command holds a presence on its own connection to the daemon, and sends
the nonce of that presence. Run them in a terminal outside tuios. From a pane
the daemon refuses them.

`register` reads the phone's push subscription from `FILE`, or from stdin
when `FILE` is `-`. The subscription holds secrets, so the command line never
takes them: other processes can read it. The file is JSON, in the shape that
`PushSubscription.toJSON()` gives:

```json
{"endpoint": "https://push.example.net/s/abc", "keys": {"p256dh": "BKZ91bcH...", "auth": "GT7vKYlZ..."}}
```

`register` also reads `endpoint`, `p256dh` and `auth` at the top level.
Give `--kind` once for each Inbox kind to push. Without it the phone gets
`approval`, `plan`, `ask` and `question`. A second `register` with the same
`--device` replaces the phone. The Inbox shows an item for each
registration.

`ls` shows each phone with the origin of its push service and its kinds,
and the daemon's VAPID public key. A phone app needs the key before it
subscribes.

**Output:**
```
$ tuios notify push ls
pixel: https://push.example.net, approval, plan, ask, question
VAPID public key: BCM4cML1lw6X1BHn3-nOS6-QtjYUql5FDx-etpdO8RHCTTipUMWpGY46YBB4bLwbc31yGx_O9LQVABj-B0Dqvp0
```

**Flags:**
- `--json`: Output the daemon's reply as JSON
- `--human-nonce`: Use this nonce instead of a presence of the command's own

---

### `tuios status`

Write one OSC 7501 report, the Program Status Protocol, for a script. tuios
shows it as the pane's agent state, in the rail and in the Inbox. Other
terminals that read the protocol show it too. The command needs no daemon. See
[PROGRAM_STATUS.md](PROGRAM_STATUS.md).

**Usage:**
```bash
tuios status [idle|working|done|blocked|error] [flags]
```

The report goes to the controlling terminal, so it is not lost when the
output of the script goes to a file or a pipe. The command refuses a report
that a terminal must discard, and says why.

**Flags:**
- `--kind <kind>`: What a blocked program waits for: `permission`, `question` or `auth`. Only with `blocked`
- `--progress <n>`: Progress from 0 to 100. Only with `working` or `blocked`
- `--app <name>`: The program's name, such as `cargo`. 1 to 32 letters, digits, `.`, `_`, `+` or `-`
- `--title <text>`: A short label for the record, at most 192 bytes
- `--msg <text>`: One line that says what the program does or waits for, at most 2048 bytes
- `--id <id>`: The record to address, such as `build/test`. Empty for the main record
- `--clear`: Remove the record and the records under it. Without `--id`, remove all records
- `--stdout`: Write the report to standard output, not to the terminal

**Examples:**
```bash
tuios status working --app build --msg 'Compiling' --progress 40
tuios status blocked --kind permission --app deploy --msg 'Approve deploy to production?'
tuios status done --app build --msg 'Built 12 crates'
tuios status --clear --id eu-west
```

---

### `tuios update`

Replace this tuios with the newest published release.

```bash
# See whether there is a newer release, without installing it
tuios update --check

# Install it
tuios update

# Include prereleases
tuios update --check --pre
```

**Flags:**
- `--check`: Report what would be installed and change nothing
- `--pre`: Count a prerelease as the newest release

**What it will and will not replace.** This only updates a binary that came from
a release archive, which is what the [install script](#quick-install-script-linuxmacos)
downloads. Every other way of installing tuios has something that owns the file,
and overwriting one of those leaves its records describing a file that is no
longer there. The command detects where the binary came from and refuses with
the right command instead:

| Installed by | `tuios update` | What to run |
| --- | --- | --- |
| Install script, or a release archive unpacked by hand | Updates it | `tuios update` |
| Homebrew | Refuses | `brew upgrade tuios`, or `brew upgrade --cask tuios-ghostty` for the ghostty cask |
| AUR or another system package | Refuses | `yay -S tuios-bin` |
| Nix | Refuses | `nix profile upgrade tuios` |
| `go install` | Refuses | `go install github.com/Gaurav-Gosain/tuios/cmd/tuios@latest` |
| `scripts/install.sh` from a checkout | Refuses | `git pull && ./scripts/install.sh` |

**tuios-web** is updated at the same time when it sits beside `tuios`. The two
talk to one daemon and it compares their versions, so they move together or not
at all: both are downloaded and verified before either is put in place.

**Checksums.** Every download is checked against the release's `checksums.txt`.
A file that does not match is discarded, nothing is installed, and the old
binary is untouched.

**The running daemon** keeps the old build. Sessions you have open go on
working. To move them to the new build, run `tuios restart-server`. Panes
are restored; the programs that were running in them are not.

On macOS and Linux, `tuios daemon upgrade` moves the running daemon to the installed build instead, with every pane's program still running. See [`tuios daemon upgrade`](#tuios-daemon-upgrade).

Set `GITHUB_TOKEN` or `GH_TOKEN` to raise the release lookup's rate limit. It is
never required and no token is created for you.

The lookup and the download need no other program. They honour `HTTPS_PROXY`
and `NO_PROXY`. A download follows redirects to `https` addresses only. The
token goes in a request header and is not sent to the host a download
redirects to.

---

### `tuios layout`

Manage saved layout templates.

**Subcommands:**
- `tuios layout list`: List all saved layout templates (`--json` for a script: `name`, `windows`, `tiled`, `created_at`)
- `tuios layout delete <name>`: Delete a saved layout template
- `tuios layout dir`: Print the layout templates directory path
- `tuios layout export <name>`: Print a layout template as a tape script

#### `tuios layout list`

List all saved layout templates.

**Example:**
```bash
tuios layout list
```

#### `tuios layout delete`

Delete a saved layout template by name.

**Usage:**
```bash
tuios layout delete <name>
```

**Example:**
```bash
tuios layout delete dev-layout
```

#### `tuios layout dir`

Print the path to the layout templates directory.

**Example:**
```bash
tuios layout dir
# Output: /home/user/.config/tuios/layouts
```

#### `tuios layout export`

Print a saved layout template as a tape script on stdout. The script turns
tiling on or off as the layout had it, opens one window per saved window,
renames each window that had a name, and types the `cd` and startup command
each window was saved with. Run it with `tuios tape play` or, against a
running session, `tuios tape exec`.

The template itself is a JSON file in the directory `tuios layout dir` prints;
copy that file to share the layout as it is stored.

**Usage:**
```bash
tuios layout export <name>
```

**Example:**
```bash
tuios layout export dev-layout > dev-layout.tape
tuios tape play dev-layout.tape
```

---

### `tuios completion`

Generate shell completion scripts for command-line autocompletion.

**Supported shells:**
- bash
- zsh
- fish
- powershell

**Usage:**
```bash
tuios completion [shell]
```

**Examples:**

**Bash:**
```bash
# Generate and install completion
tuios completion bash > /etc/bash_completion.d/tuios

# Or for user-specific completion
tuios completion bash > ~/.local/share/bash-completion/completions/tuios
source ~/.bashrc
```

**Zsh:**
```bash
# Generate and install completion
tuios completion zsh > "${fpath[1]}/_tuios"

# Or add to your .zshrc
echo "autoload -U compinit; compinit" >> ~/.zshrc
tuios completion zsh > ~/.zsh/completions/_tuios
```

**Fish:**
```bash
# Generate and install completion
tuios completion fish > ~/.config/fish/completions/tuios.fish
```

**PowerShell:**
```bash
# Generate completion script
tuios completion powershell > tuios.ps1

# Add to your PowerShell profile
echo ". $(pwd)/tuios.ps1" >> $PROFILE
```

---

### `tuios help`

Get help about any command.

**Usage:**
```bash
tuios help [command] [--json] [-i]
```

**Flags:**

- `--json`: Print the command and every command under it as JSON: each
  command's path, usage line, short and long help, examples, aliases and flags
- `-i`, `--interactive`: Open the same command tree in an explorer you can
  search. The detail pane shows the command's usage, help and flags

Press `/` to search, the arrow keys or `j` and `k` to move, and `tab` or a
click on a tab to show one group. `J` and `K` scroll the detail pane. `q` or
`esc` leaves it. An explorer opens only with its own flag or subcommand, never
because the output is a terminal, so a script or an agent in a pane always gets
the plain output.

**Examples:**
```bash
tuios help              # Show general help
tuios help ssh          # Show help for ssh command
tuios help config edit  # Show help for config edit subcommand
tuios help --json       # Every command as JSON
tuios help -i           # Search the commands in an explorer
```

---

## Global Flags

The root command's flags are listed under [Root Command](#root-command).
`--debug` is accepted by every subcommand too. `--cpuprofile` and `--pprof` are accepted by every subcommand and honoured by the commands that keep running (see the flags under [Root Command](#root-command)).

---

## Common Usage Examples

### Basic Usage

Start TUIOS normally:
```bash
tuios

# Start with showkeys overlay for screencasting
tuios --show-keys
```

### Theming

```bash
# Start with a specific theme
tuios --theme dracula

# List all available themes
tuios --list-themes

# Preview a theme before using it
tuios --preview-theme nord

# Interactive theme selection with fzf
tuios --theme $(tuios --list-themes | fzf --preview 'tuios --preview-theme {}')

# Use ASCII mode (no Nerd Font required)
tuios --ascii-only

# Combine theme with ASCII mode
tuios --theme gruvbox_dark --ascii-only
```

### Configuration Management

```bash
# Find config file location
tuios config path

# Edit configuration
tuios config edit

# View all keybindings
tuios keybinds list

# View your customizations
tuios keybinds list-custom

# Reset to defaults
tuios config reset
```

### Daemon Mode (Session Persistence)

```bash
# Create a new persistent session
tuios new mysession

# List all sessions
tuios ls

# Attach to an existing session
tuios attach mysession

# Detach from session (inside TUIOS)
# Press Ctrl+B d

# Kill a session
tuios kill-session mysession

# Stop the daemon (kills all sessions)
tuios kill-server
```

### SSH Server Setup

```bash
# Add your public key first. The server does not start without keys,
# on localhost too. Use your public key file.
mkdir -p ~/.config/tuios
cat ~/.ssh/id_ed25519.pub >> ~/.config/tuios/authorized_keys

# Start SSH server on default port
tuios ssh

# Start on custom port with remote access
tuios ssh --host 0.0.0.0 --port 8022

# Connect from another machine, with the matching private key
ssh -p 8022 your-server-hostname
```

### Web Terminal Setup (tuios-web)

```bash
# Start web terminal on default port
tuios-web

# Start on custom port with remote access, over TLS with a password
tuios-web --host 0.0.0.0 --port 8080 --auto-tls --random-password

# Open in browser
open http://localhost:7681

# Start in read-only mode for demonstrations
tuios-web --read-only

# Start with theme and overlay
tuios-web --theme dracula --show-keys

# Limit connections for production use
tuios-web --max-connections 50 --host 0.0.0.0 --auto-tls --password-file ~/.config/tuios/web-password
```

### Development & Debugging

```bash
# Run with debug logging
tuios --debug
# Then press Ctrl+L during runtime to view logs

# CPU profiling
tuios --cpuprofile cpu.prof
# Use the application, then exit
go tool pprof cpu.prof

# Screencasting with showkeys overlay
tuios --show-keys
# Or toggle during runtime with: Ctrl+B D k
```

### Shell Completions

```bash
# Install bash completion
tuios completion bash | sudo tee /etc/bash_completion.d/tuios

# Install zsh completion
tuios completion zsh > "${fpath[1]}/_tuios"

# Install fish completion
tuios completion fish > ~/.config/fish/completions/tuios.fish
```

---

## Environment Variables

### `$EDITOR` / `$VISUAL`

Used by `tuios config edit` to determine which editor to open.

**Example:**
```bash
export EDITOR=vim
export VISUAL=code
tuios config edit
```

**Fallback order:** `$EDITOR` → `$VISUAL` → vim → vi → nano → emacs

### `XDG_RUNTIME_DIR`, and `TUIOS_SOCKET`

`XDG_RUNTIME_DIR` chooses the daemon a command reaches: its socket is
`$XDG_RUNTIME_DIR/tuios/tuios.sock` (`%LOCALAPPDATA%\tuios\tuios.sock` on
Windows). When the variable is unset, the socket is
`/run/user/<uid>/tuios/tuios.sock` on Linux if `/run/user/<uid>` is yours and
has mode `0700`, and `/tmp/tuios-<uid>/tuios.sock` otherwise. So a command over
ssh reaches the same daemon as your desktop. See
[One daemon per user](SESSIONS.md#one-daemon-per-user). Set it, with
`XDG_STATE_HOME` for separate saved sessions, to run a separate daemon. See
[Running a separate daemon](SESSIONS.md#running-a-separate-daemon).

`TUIOS_SOCKET` does not choose the daemon. It is set in every pane to the
socket of the daemon that runs it. A command refuses when `TUIOS_SOCKET` names a
different socket with no daemon listening, since that is an attempt to select a
daemon that would otherwise reach the one `XDG_RUNTIME_DIR` names. `tuios mcp`
is the one reader: it connects to `TUIOS_SOCKET` when it is set, see below.

### `TUIOS_NO_DAEMON`

Set to `1` to make a plain `tuios` run a standalone session without the daemon,
the same as `--standalone`, for every run in that shell.

```bash
export TUIOS_NO_DAEMON=1
tuios
```

### `TUIOS_AGENT`

Set on a wrapper that runs an agent tuios cannot see, such as one in a
container or a VM, to name its harness. The daemon reads it from the pane's
foreground process when nothing else identifies the process, and attributes
the pane to that harness, so its screen and title rules run. `tuios agent-hook`
ignores a hook from a different harness than the one it names, which may be any
harness tuios recognises, one with no integration included. The plugins tuios
installs report only when `TUIOS_ENV` or `TUIOS_AGENT` is set.

```bash
TUIOS_AGENT=claude-code docker run -it sandbox claude
```

### Variables tuios sets in a pane

`TUIOS_ENV`, `TUIOS_SOCKET`, `TUIOS_PANE_ID`, `TUIOS_WINDOW_ID`,
`TUIOS_SESSION`, `TUIOS_HOST`, `TUIOS_PANE_TOKEN` and `TUIOS_PANE_GRANTS`. See
[Environment](AGENT_STATE.md#environment) for what each one means.

### Agent detection

`TUIOS_AGENT_AUTODETECT`, `TUIOS_AGENT_DETECT_SECONDS`,
`TUIOS_AGENT_BINARIES` and `TUIOS_AGENT_STALL_SECONDS`, read by the daemon as
it starts. See
[Turning detection off or widening it](AGENT_STATE.md#turning-detection-off-or-widening-it)
and [The stall heuristic](AGENT_STATE.md#the-stall-heuristic).

### `TUIOS_WORKTREE_DIR`

Where the daemon puts the worktrees `tuios worktree new` and `tuios fan`
create, instead of `$XDG_DATA_HOME/tuios/worktrees`. Set it in the daemon's
environment, before it starts. A `[worktree] path` in the config wins over it
(see [Where worktrees go](CONFIGURATION.md#where-worktrees-go)).

### `TUIOS_LOG_LEVEL`

The daemon's log level from the start: `off`, `errors`, `basic`, `messages`,
`verbose` or `trace` (or `0` to `5`). It wins over `daemon.log_level`.
`tuios logs` reads what it records.

### `TUIOS_NO_SOUND`

Any value silences the agent alert sounds, whatever
`notifications.agent.sound` says. For a CI job or a recording.

### `TUIOS_SSH`

The ssh program to run instead of `ssh` on `PATH`: for the daemon's links to
the `[hosts]` machines (set it where the daemon starts), and for `--ssh`,
`tuios hosts test` and `tuios hosts sync`.

### `TUIOS_HOST_RECONNECT_BUDGET`

How long a client attached to a session on another machine keeps dialing a
dropped link before it gives up, as a Go duration (`10m`). Three minutes when
unset. Read once, when the client starts.

### `TUIOS_CELL_SIZE`

The terminal's cell size in pixels, as `WIDTHxHEIGHT` (`10x20`), for a terminal
that does not answer the pixel geometry query. Images and captures drawn in
cells are sized from it. The SSH server reads the same variable.

### `TUIOS_KITTY_GRAPHICS`, `TUIOS_KITTY_PLACEHOLDERS`, `TUIOS_KITTY_ANIMATION`, `TUIOS_SIXEL_GRAPHICS`

`1` or `0` overrides what tuios detected about the host terminal's kitty
graphics, kitty Unicode placeholders, kitty animation and sixel support.

tuios turns kitty graphics and sixel off on a terminal built on xterm.js, such
as VS Code or Netcatty. That terminal cannot clear an image, so tuios draws
images as block glyphs. Set `TUIOS_KITTY_GRAPHICS=1` or
`TUIOS_SIXEL_GRAPHICS=1` to turn a protocol on again.

### `$SHELL`

TUIOS uses your default shell from this variable. If not set, it attempts to detect the appropriate shell for your platform.

### `COLORTERM`

For best color support, set this to `truecolor`:
```bash
export COLORTERM=truecolor
```

tuios draws its chrome for the colour depth it detects: truecolor, 256 or 16
colours (see [THEMES.md](THEMES.md#colour-depth)).

Without it, tuios falls back to 256 colours unless `TERM` names a terminal
known to have 24-bit colour. **Mosh** is the common case: mosh 1.4 and
later pass 24-bit colour through, but mosh-server sets `TERM=xterm-256color` and does not pass
`COLORTERM` to the remote shell, so tuios sees a 256 colour terminal. If both
ends of your mosh connection are 1.4 or later and your local terminal has
truecolor, set it on the remote host, for example in your shell's startup file:

```bash
export COLORTERM=truecolor
```

tuios does not try to detect mosh. mosh-server sets no variable of its own
that marks it, and the version of the mosh client on the other end, which
decides whether 24-bit colour survives, is not visible from the server. Mosh
also answers no colour queries, so with no theme tuios cannot learn the
terminal's background there; see "Programs that ask" in CONFIGURATION.md.

---

## When Something Goes Wrong

Every failure `tuios` reports answers three questions in order: what failed, the
most likely cause, and the exact command that fixes it. If you meet a message
that does not, it is a bug worth reporting.

### The daemon is not running

There are three distinct versions of this, and they have different fixes:

| Message says | What it means | Fix |
| --- | --- | --- |
| "is not running" | No socket exists. The daemon has never run, or was stopped. | `tuios new` |
| "a stale socket is left over at ..." | The daemon crashed without cleaning up. | `tuios kill-server`, which removes it |
| "Permission denied ... socket" | The socket belongs to another user, or its mode changed. | Check `ls -l` on the path; set `XDG_RUNTIME_DIR` to a directory you own |

### Two daemons on one machine

A session you made on one machine does not show in `tuios ls` on that same
machine, or a host link shows other sessions than your desktop. Two daemons
run for your user, each with its own sessions. Two sessions with one name,
such as `session-0`, can make them look like one.

The cause is an older tuios. It put the socket in `/tmp/tuios-<uid>` when a
command ran without `XDG_RUNTIME_DIR`, as a command over ssh often does. The
desktop used `/run/user/<uid>/tuios`. tuios now uses `/run/user/<uid>/tuios`
for both. See [One daemon per user](SESSIONS.md#one-daemon-per-user).

To find the daemons, look at both sockets:

```bash
ls -l /run/user/$(id -u)/tuios/tuios.sock /tmp/tuios-$(id -u)/tuios.sock
```

When both daemons run, tuios uses the one in `/run/user`. A command in a pane
of the daemon in `/tmp` still reaches that daemon. A command at a
terminal says once that the other one runs, and gives its process ID. To move
the sessions of the daemon in `/tmp`:

1. Stop it: `kill $(cat /tmp/tuios-$(id -u)/tuios.sock.pid)`. It saves every
   session when it stops.
2. List what it saved: `tuios resurrect`.
3. Restore each session: `tuios resurrect NAME`.

A session name that both daemons used has one saved file. Rename one of the
two sessions before you stop that daemon if you need both.

Upgrade tuios on every machine. A machine with the older tuios still starts a
daemon in `/tmp` over ssh.

### The daemon is older than the CLI

After upgrading TUIOS, the old daemon keeps running and serving the socket. It
cannot speak the control protocol the new CLI uses, so commands fail:

```
The running TUIOS daemon does not speak this CLI's control protocol (daemon 0.9.0, CLI 1.4.0).
Most likely cause: TUIOS was upgraded while the daemon kept running, so the old daemon is still serving the socket.
Fix: run 'tuios kill-server', then run this command again.
```

Run `tuios restart-server`. It lists what stops and asks first. A restart ends every program running in your panes. Each
session's layout, window names and working directories are saved before the
daemon exits and come back when it next starts, each pane with a new shell;
`tuios resurrect` lists what is restorable.

### A session name is not found

The message lists the sessions that do exist and suggests the closest name:

```
Session "wrok" was not found.
Most likely cause: the name does not match any live session.
Did you mean "work"?
Sessions: notes, work.
Fix: run 'tuios ls' to list sessions, or 'tuios new wrok' to create this one.
```

A session killed with `tuios kill-session` is gone for good: killing is a
deliberate teardown, so its saved state is removed too. A session that merely
outlived its daemon is still restorable with `tuios resurrect`.

### A saved session will not restore

`tuios resurrect <name>` distinguishes three cases: no saved state at all, state
that is corrupt, and state written by a newer TUIOS. Unreadable state is moved
into an archive directory rather than deleted, and the message names that
directory so you can inspect or recover the file.

### The terminal cannot host the interface

`tuios attach`, `tuios new`, and `tuios resurrect` check the terminal before
taking over the screen, and refuse with an explanation when it is too small
(minimum 40x12), when `TERM` is unset or `dumb`, or when stdout is not a
terminal at all. For non-interactive use, drive a session with `tuios send-keys`
and `tuios capture-pane` instead of attaching.

### A session was killed while you were attached

The client exits with a non-zero status and says so, rather than leaving you in a
dead UI:

```
Session "work" was terminated while you were attached.
```

The same applies when the daemon itself goes away, which reports a lost
connection instead.

### Agent features are off

With `[agents] enabled = false` in `config.toml`, tuios keeps only the
multiplexer. Every agent command (`list-agents`, `start-agent`, `fan`, mail,
the Inbox, `respond`, `queue` and the agent conditions of `wait-for`) prints
one line and exits `1`:

```
Agent features are off. Set agents.enabled = true in the config to use this command.
```

With `--json` the error carries `"code": "agents_disabled"`, so a script can
tell it from a failure worth a retry. A call to another machine whose agent
features are off names that machine. Turn the features on from the settings
page or in `config.toml`. A process in a pane cannot set `agents.enabled`.

### Discovering the control protocol

`tuios list-verbs` prints every verb the daemon supports with its parameters,
accepted values, and runnable examples, plus the stable error codes. It is the
discovery entry point that the error hints point at, and `--json` makes it
machine-readable for an agent or a script.

```bash
tuios list-verbs                 # everything
tuios list-verbs capture-pane    # one verb
tuios list-verbs --json          # for scripting
```

---

## Exit Codes

- `0`: Success
- `1`: Error (configuration error, network error, file not found, etc.)
- `2`: `tuios ask-human` returned before an answer, because of `--no-wait` or
  because `--timeout` ran out. The question stays in the Inbox
- `3`: The command needed a daemon and found none running. `tuios ls` lists the
  sessions saved on disk instead, so a script can tell a stopped daemon from a
  running one with no sessions, which exits `0`

`tuios run` exits with the status of the command it ran, and `tuios popup
--wait` with its command's status (`130` when the popup is closed).

`tuios cp` and `tuios transfers wait` have their own exit codes: see
[Exit codes of tuios cp](#exit-codes-of-tuios-cp).

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

---

## Version Information

The `--version` flag shows detailed build information:

```bash
tuios --version
```

**Output:**
```
tuios version 0.8.0 [pure-Go backend]
Commit: a1b2c3d
Built: 2026-09-27T10:30:00Z
By: goreleaser
```

The bracket names the terminal emulator backend the binary was built with.

---

## Command Migration Guide

If you're upgrading from an older version of TUIOS, here's how the commands have changed:

| Old Flag | New Command |
|----------|-------------|
| `--config-path` | `tuios config path` |
| `--edit-config` | `tuios config edit` |
| `--reset-config` | `tuios config reset` |
| `--list-keybinds` | `tuios keybinds list` |
| `--list-custom-keybinds` | `tuios keybinds list-custom` |
| `--ssh` | `tuios ssh` |
| `--ssh --host X --port Y` | `tuios ssh --host X --port Y` |
| `--version` | `tuios --version` |
| `--help` | `tuios --help` or `tuios help` |

---

## Related Documentation

- [Configuration Guide](CONFIGURATION.md): How to customize TUIOS
- [Keybindings Reference](KEYBINDINGS.md): Complete keyboard shortcut reference
- [Architecture Guide](ARCHITECTURE.md): Technical architecture details
- [README](../README.md): Project overview and quick start