st command reference
Every st command you run, with its flags and arguments as st 0.3.116 spells them (and what 0.4.0 adds, marked), and the page that explains each.
Every command below is one you or your agents type. st --help prints the
short form of this list from the binary itself; st worker, st task,
st gate and st doc --help print theirs.
Flag values follow a space (--name api-tests, not --name=api-tests).
A version in brackets is the first st with that command or flag. The current
release is 0.3.116; what is marked (st 0.4.0) is in the release candidates
only, on st upgrade --channel rc, until 0.4.0 comes out.
Command scope
- Anywhere.
stitself, the account commands,st hooks,st plugin,st skills,st usage,st history,st status,st ptys,st ci, the maintenance commands andst orch accept-remote. - While st is sharing.
st ls,st url,st attach,st exitandst restartsay "not sharing — run st first" otherwise. - Inside a pane of a session st shares. Every other
st orch,st worker,st taskandst gatecommand. They read the pane they run in ($TMUX_PANE) and refuse elsewhere with "run this inside a tmux pane of a session st shares".st gate askalso needs the pane to be an agent's. st docworks anywhere. Run inside st's tmux it records the pane and agent it came from; with st not running it waits in~/.sophonz/outbox.
Sharing
| Command | What it does | Guide |
|---|---|---|
st | Start sharing and print the link and QR code. Run again while sharing, it shows them again | Share a terminal |
st ls | The sessions and who is on each, then your other machines' sessions (st 0.3.98); a list you move around in, Enter attaches, d disconnects a device (on a session, all of its devices), r refreshes, q leaves. --plain prints it once instead (also what a pipe gets) | Watch it work |
st ui [view] | This machine in one terminal screen: sessions, windows, panes, agents and their runs, the machine tree, documents, CI, plan limits and resources; : runs any st command (st 0.4.0) | st ui |
st url | The join link and its QR code; into a pipe, the link alone | Watch it work |
st status | This machine's terminals (ptys), memory and multiplexer, and an uploads line: what ~/.sophonz/uploads holds, the disk's room, how long uploads are kept. Warns from 80% of the ptys taken, red from 95% or when none is left. The pty count is about, a little high, on macOS; --exact counts them exactly (seconds on a busy Mac) (st 0.3.92) | |
st ptys | Terminals (ptys) nobody can use any more, the ghosts: one line per tty, oldest first. A ghost is a pty whose other end nobody holds, with only idle shells of yours on it (st 0.3.92) | |
st ptys clean <tty>… | What ending those would do; nothing is ended. --all the same for every ghost; --yes ends them: SIGHUP, then SIGTERM, never SIGKILL | |
st attach [name] | Attach this terminal to the shared session, or to name. From inside st's tmux it switches to it instead | Watch it work |
st attach <machine>/<session> [--window <n>] | Put this terminal (iTerm, Warp, any) on a session of another machine of the account, through that machine's tunnel as the apps go; ~. leaves, ~? lists the keys. Inside st's tmux it switches to it instead (st 0.3.98). --window <n> puts window n in front (st 0.4.0) | Watch it work |
st exit | Stop sharing; the sessions keep running. Refused while someone is still connected; --force (-f) stops anyway. st stop is the same | Watch it work |
st restart | Stop sharing and start again on this binary, keeping the session and the address. When the address cannot be kept it asks first; --yes (-y) answers yes | Install |
st takes the flags under Flags for st.
Account
| Command | What it does | Guide |
|---|---|---|
st login | Sign in with a device code, so this machine keeps one link across restarts. --force signs in as someone else | Accounts and links |
st logout | Sign out | Accounts and links |
st whoami | Who is signed in | Accounts and links |
st machines | Every machine on this account, and its link | Accounts and links |
st rename <name> | What this machine is called on the account. st rename <slug> <name> names another of the account's machines; --reset goes back to the hostname | Naming a machine |
Documents
| Command | What it does |
|---|---|
st doc <file> | Hand a .md or .txt file (at most 1 MB) to your phone and tablet. cat notes.md | st doc does the same from a pipe |
st doc <file> --title T | A title of its own (default: its first heading) |
st doc <file> --folder a/b | Into a folder. st doc add <file> is the same as st doc <file> |
st doc ls [folder] [--tree] | The documents this machine keeps |
st doc ls --by where|run|date | The same documents as a tree worked out from them: session / window / agent session, run / worker, or day (st 0.3.113) |
st doc ls --here | Only the documents of this pane's folder (st 0.3.113) |
st doc here | Where this pane's documents go: its session, window, pane and agent, and the vault folder (st 0.3.113) |
st doc cat <doc> | Its text, on standard output (st 0.3.93) |
st doc rm <doc>… | Remove documents (st 0.3.90) |
st doc mv <doc> <folder> | Move one (/ is the top); --title T renames it. <doc> is its id, title or folder/title |
st doc mkdir <folder> | A folder, kept while empty |
st doc mvdir <from> <to> | Rename or move a folder with what is in it |
st doc rmdir <folder> | Remove an empty folder |
st doc migrate | Move the documents into an Obsidian vault, ~/.sophonz/vault/machine: session and window folders, files under their own names. --undo moves them back to ~/.sophonz/docs (st 0.3.113) |
What is kept is a copy in ~/.sophonz/docs (in the vault after st doc migrate); the file itself is read once and
never written to. Documents belong to the machine that ran st doc. See
Documents.
Coding agents
| Command | What it does | Guide |
|---|---|---|
st hooks install [agent…] | Have the coding agents on this machine report to st. Without names, every one st can hook that is here: claude, codex, gemini, opencode, pi, kimi, qwen | Agent hooks |
st hooks uninstall [agent…] | Take st's hooks out again (with Claude Code, the status line too) | Agent hooks |
st hooks status | Every agent found, and whether its hooks are in | Agent hooks |
st hooks auto [on|off] | Whether st brings outdated hooks up to date when it starts | Agent hooks |
st hooks install --usage | Be Claude Code's status line, so its 5-hour and weekly limits reach the apps; your own status line still shows. st hooks uninstall --usage undoes it | AI usage and past sessions |
st usage | The coding agents' own usage limits: used, and when they reset | AI usage and past sessions |
st usage guard on|off|status | Stop a loop's turn (st goal, Claude's /goal) when the weekly limit runs faster than the week, or is nearly out. Claude Code only (st 0.3.113) | AI usage and past sessions |
st goal [set <text>|set --file <f>|clear] | Keep a Claude Code pane working at a goal: each time its turn ends, st's Stop hook hands it the goal again, until st goal clear. Alone, the pane's goal. --pane %N another pane of this tmux server (st 0.3.113) | AI usage and past sessions |
st usage poll on|off | Whether st asks Anthropic and OpenAI itself every few minutes, with the logins Claude Code and Codex keep here (default on) | AI usage and past sessions |
st history | Past Claude Code and Codex sessions, with the line that resumes each. --cwd <dir> (. for this folder), --agent claude|codex | Past sessions |
st ci | The GitHub Actions runs of this checkout's commit, one line each, read with the machine's gh (st 0.3.94) | |
st ci log | The log of a job of this commit's runs. --job <id> that job (any repository's with -R), --failed a failed job when no --job is given, --follow its steps as they go while it runs and the log once it ends, --all every step's lines, not only the failed ones', -R <owner/repo> the repository (HOST/OWNER/REPO off github.com). A job still running has no log yet | |
st plugin install|status|uninstall | The Claude Code plugin (/sophonz:orchestrate) and the Codex skills sophonz-orchestrate and sophonz-worker | Agent skills and the plugin |
st skills get orchestrate|worker|all | The coordinator's and the worker's guide, as this st has them | Agent skills and the plugin |
st --skill | The guide for the agent running it, in one read: the worker's when st started it, the coordinator's otherwise. st skills alone is the same (st 0.4.0) | Agent skills and the plugin |
st awake [off|working|agents] | Keep the machine from sleeping while an agent is working (working) or working or waiting (agents). Alone, the mode now. Off by default | st awake |
st hook and st statusline are run by the agents' hooks and by Claude Code,
not by you.
Orchestration
Usually the coordinating agent runs these, not you. A worker's id is its tmux
pane id (%15); one on another machine has the machine in front
(ci-mac/%15). The name st worker list shows works as an id too
(api-tests, ci-mac/api-tests; st 0.3.90). Every command here takes --json.
st orch
| Command | What it does | Guide |
|---|---|---|
st orch start --objective "<goal>" | This pane coordinates a run. The first st worker start makes one if there is none | Orchestration |
st orch status | The same as st worker list | Orchestration |
st orch accept-remote on|off|status | Whether this machine takes workers from the account's other machines. Off by default | Workers on other machines |
st orch history [--run r-…] [--all] [--limit N] | What was handed to whom and when, who finished, who was told (st 0.3.92), and every change to the tree, adopt, release, rename and about, with who asked (st 0.3.98) | Orchestration |
st orch unarchive <run> | Put a retired run back (~/.sophonz/orch/archive); its agents are found again by their keys (st 0.3.97) | Orchestration |
st project save [<run>] [-o <file>] [--with-conversations] [--force] | Keep a run as one .sophonz file: its record, history, handoff documents, task files, last summaries and conversation ids; --with-conversations adds the transcripts (st 0.3.98) | Workers |
st project archive [<run>] [-o <file>] [--with-conversations] | Save it, then retire the run to ~/.sophonz/orch/archive (st 0.3.98) | Workers |
st project show <file> [--map …] | What the file holds, and what opening it here would do for each agent (st 0.3.98) | Workers |
st project open <file> [--map <saved folder>=<folder here>]… | Make each agent's window again in the same tree; resume a conversation that is here, start one with what st kept where it is not. A folder not here is asked for, or nothing changes and it exits 3 (st 0.3.98) | Workers |
st worker
| Command | What it does | Guide |
|---|---|---|
st worker start --agent claude|codex|opencode|pi --task <file|-> | Start a worker in a new window of this session. --task - reads the task from stdin. opencode from st 0.3.102, pi from st 0.3.109 | Workers |
st worker wait [ids…] | Until workers are done, need input or end their turn; with no ids, every worker of this pane. --brief waits for adopted workers' briefs instead of their work (st 0.3.93). Exits 0 done, 3 one is waiting (a question, a gate), 2 timed out. --check-in 3m comes back after that long with each one's state, how long it has been so and its title, leaving them running (exit 2, as for a timeout) (st 0.4.0) | Workers |
st worker read <id> | Its last answer and its done summary | Workers |
st worker send <id> "<text>" | Type into it, checked to have gone in. Not sent when that pane is not your run's worker (an old id after a restore); it prints your workers' ids, and --force sends anyway (st 0.3.90) | Workers |
st worker send <id> --file <file|-> ["<note>"] | More than a line: st keeps a copy (and a document) and types the worker where it is. --title T the document's title (st 0.3.93) | Workers |
st worker send <id> --doc <doc> | A document this machine keeps, the same way (st 0.3.93). When it cannot be typed now (someone is typing there), it waits in the worker's inbox and st says so (st 0.3.113) | Workers |
st worker done --summary "<line>" | A worker reports it is done (blocked: … when it could not finish). --outcome succeeded|failed says which (st 0.3.113) | Workers |
st worker question [<id>] "<question>" [--timeout 10m] | Ask a pane (by default your coordinator) and wait for the answer; exits 2 when it does not come in time. --resume <question id> waits again (st 0.3.113) | Workers |
st worker reply <question id> "<answer>" | Answer a question st typed to you (st 0.3.113) | Workers |
st worker inbox | What is owed to this pane: work that could not be typed, news not seen to go in. Showing it takes it; --peek only shows, --ack <id> or --ack-all takes them, --wait [--timeout 10m] waits for some (exit 2 if none) (st 0.3.113) | Workers |
st worker list | This pane's workers and theirs, as a tree: id, name, window, state, task (st 0.3.90). --depth 1: only this pane's own. (team N) after a team's lead whose workers are not shown, (parent gone) when its coordinator's pane is gone (st 0.3.88). --all: every worker, other runs and other machines included. Up to st 0.3.87 it listed the whole run | Workers |
st worker stop <id> --yes | Close a worker's pane. Only workers st started, in your run; not adopted ones | Workers |
st worker adopt <id> | An agent already running becomes a worker of this pane, keeping its conversation. --parent <id> makes it another agent's worker; --owns … as below. An agent with workers of its own comes in as a team and keeps its run (st 0.3.88). It is asked for a brief once its turn ends; --role "<why>" gives its role, --no-brief asks for none (st 0.3.93) | Workers |
st worker about <id> "<role>" | An adopted worker's role, shown under its name; --clear takes it off (st 0.3.93) | Workers |
st worker brief --summary "<lines>" | An adopted worker says what it has done, when st asks it to (st 0.3.93) | Workers |
st worker release <id> | An adopted worker is no one's again | Workers |
st worker rename <id> <name> | A worker's name, which is a label: letters, digits and -, 24 at most. A name another worker has, or a machine's, is refused; the tmux window keeps its title (st 0.3.96) | Workers |
st worker own <id> "<paths>" | What a worker may change (comma separated, * and **); --clear lifts it | Tasks, ownership and worktrees |
st worker trees | Every worktree on this machine by its id (<run>/<worker>), its worker done or gone too (st 0.3.107) | Tasks, ownership and worktrees |
st worker diff <id|tree> | What a worker changed in its worktree, committed or not, and from what: a commit, or st's snapshot of a folder with no git. --stat for the summary | Tasks, ownership and worktrees |
st worker merge <id|tree> | Its worktree's branch into this checkout; a conflict merges nothing. --commit commits what it left first, --squash stages it as one change | Tasks, ownership and worktrees |
st worker clean <id|tree> | Remove its worktree and branch. Refused with changes not committed or not merged unless --force; --keep-branch keeps the branch | Tasks, ownership and worktrees |
st worker ask <id|tree> ["<question>"] | A reading agent in its own window in the worktree, with the changes in its first prompt; never the worker itself. Asked again, the same window. --agent claude picks it (st 0.3.107) | Tasks, ownership and worktrees |
st worker start --fan N --agent claude,codex --task <file> | One task to 2–8 workers, each in its own worktree from the same commit; a list in --agent is used in turn. With --machine <machine>, all of them on that machine (pick and diff take this machine's workers only, for now) | Workers |
st worker fan [<id>] | A fan's workers side by side: what each changed, done or not | Workers |
st worker pick <id> | Merge that one; the others' windows and worktrees go. --commit commits what it left first, --keep leaves the others | Workers |
st worker start --machine <machine> … | The worker runs on another machine of the account, which has st orch accept-remote on; its id is <machine>/%N | Workers on other machines |
More flags for st worker start:
--name <name>the window's name and the task file's: lower-case letters, digits and-, cut at 24. Without it, the task's first line names it.--splita pane beside the coordinator instead of a new window.--cwd <dir>the folder it works in (on another machine, a path there).--owns "src/x/**,docs/x.md"what it may change.--worktreeits own git worktree and branchst/<run>/<name>. A folder with no git gets a snapshot under~/.sophonz/shadow/instead; a large one needs--any-size(st 0.3.107).
For st worker wait: --any returns as soon as one matches, --for done,waiting,idle picks the states to wait for (all three by default; exited
always counts). done is a worker that ran st worker done, idle one that
ended its turn without it, so --for done alone may wait out the timeout.
--timeout 15m (the default; running out is a checkpoint, not a failure).
--split is for workers on this machine.
st task
| Command | What it does | Guide |
|---|---|---|
st task create <name> --task <file|-> | A task in order. --deps a,b (tasks that exist already), --agent claude|codex|opencode|pi, --owns "…", --worktree | Tasks, ownership and worktrees |
st task list [--ready] | Every task and where it stands: waiting, ready, running, done or blocked | Tasks, ownership and worktrees |
st task start <name> | A worker takes it; refused until its --deps are done. --agent, --split, --cwd dir | Tasks, ownership and worktrees |
st task wait [--timeout 15m] | Until a task is ready, a worker asks, or all are done. Exits 0 ready or all done, 3 a worker is asking, 4 nothing can move (blocked), 2 timed out | Tasks, ownership and worktrees |
st gate
| Command | What it does | Guide |
|---|---|---|
st gate ask "<question>" --option "<A>" --option "<B>" | Ask a person to decide, from this agent's pane, then stop the turn. Up to nine options; --title "<few words>", --text to allow a written answer. The answer arrives as the agent's next message, "Decision gate <id> answered: …" | Decision gates |
st gate list [--all] | Open gates; with --all, answered and cancelled ones too | Decision gates |
st gate show <id> | One gate and its answer | Decision gates |
st gate answer <id> <n|"text"> | Answer it here (n counts from 1; text after the number is added to it) | Decision gates |
st gate cancel <id> | Take it back | Decision gates |
Maintenance
| Command | What it does | Guide |
|---|---|---|
st upgrade | Replace this binary with the latest release and move the share onto it. st update is the same. --channel rc|stable follows release candidates or releases from then on, kept in ~/.sophonz/upgrade-channel; an rc build follows rc unless told otherwise (st 0.4.0) | Install |
st rollback | Go back to the version before (kept in ~/.sophonz/bin) | Install |
st restore | Set the tmux sessions up again from the last snapshot, and resume the Claude Code and Codex conversations saved on this machine. --list the snapshots, --from <id> an older one, --dry-run (-n) what it would do, --no-resume-agents type the agents' lines without Enter. --pending [--json] the snapshot waiting after a restart, --decline leave it. st restores by itself when the tmux server dies while it runs; after a restart of the computer it waits for you (st 0.3.95). From st 0.3.88 --help prints the help, and a session it could not set up is listed as not restored | Multiplexers |
st service install | Keep the share running: start it at login and whenever it is not running (launchd, or systemd --user). Takes --session, --mux, --command, --no-tunnel, --no-telemetry for the share it starts | Keep the share running |
st service uninstall|status | Stop keeping it running (the share itself keeps running); how it stands | Keep the share running |
st route | Which way this machine is reached, and the others: st route tailscale only from devices on this machine's tailnet, st route cloudflare a Cloudflare quick tunnel from anywhere (the default), st route relay through a relay (on a Pro account the sophonz relay is set up by itself; a relay of your own needs st relay set first), st route cloud sophonz cloud's managed tunnel (Premium, not available yet). Saved for the next start (st restart) (st 0.3.93) | |
st relay | Which way this machine is reached. st relay set <relay> [--token T] goes through a relay and makes it the route (a Pro account's machine fetches the sophonz relay itself from st 0.4.1, so this is for a relay of your own) (the token can come from ST_RELAY_TOKEN, or is asked for); st relay reset drops a relay of your own and picks a Cloudflare quick tunnel and stays there (a tailnet you chose stays as it is). Tailscale is the other way, with st route | |
st set | One setting at a time, for provisioning: st set relay-url <address>, st set relay-token <token> (- reads it from stdin), st set uploads-keep <days> removes uploads older than that, st set uploads-keep forever keeps them until they are removed (the default; st 0.3.94), st set <key> --reset. Alone, every setting and its value | |
st version | Print the version. st --version and st -v are the same |
Flags for st
| Flag | What it does | Guide |
|---|---|---|
--session <name> | The multiplexer session to share (default: default) | Share a terminal |
--mux <name> | tmux, zellij, psmux, none or auto (default: auto, which is tmux, else zellij; on Windows psmux, else zellij; st 0.3.103) | Multiplexers |
--command <program> | What a new session runs instead of your shell, e.g. st --mux none --command python3 | Multiplexers |
--no-tunnel | Local only, no public address | Share a terminal |
--no-telemetry | Send no usage data from the web terminal (or SOPHONZ_TELEMETRY=off) | Telemetry |
--help, -h | The command list |