CLI Reference
Every command runs against the multiplexer the current process is inside (resolved by
detection). Commands that produce data accept --format text|json|agent — human table by default, machine-readable with --format json (JSON) or --format agent (TOON, the cheaper read for an agent). Every failure is a
structured error on stdout with a stable code and an actionable help line — see
AXI for the full output contract, exit codes, and pane-addressing rules.
Pane arguments (<pane>) take either a pane id or a human label — an id is matched
first, and only a locator that matches no id is checked against labels. A label matching more than
one live pane is an ambiguity error (exit 2) naming every candidate; a locator matching nothing is
handed straight to the backend as an id and takes that verb’s own not-found path. See
Pane for the full resolution rules and how to discover ids/labels with
list.
Exit codes, consistent across every verb: 0 success, 1 a well-formed operation that failed
(no pane, no multiplexer, a refused removal), 2 a usage error (missing argument, unknown flag,
conflicting flags, a malformed value) — the fix is a different invocation, not a retry. A group run
without a subcommand (cyber-mux send) is a missing-command error that lists the group’s commands,
and exits 2; --help exits 0.
Flags and positionals can come in any order. A flag that takes a value takes exactly one
(read --lines 5 <pane>); a repeatable flag (--env, --set, --until) takes every value up to the
next flag, so put positionals before it or repeat the flag (--env A=1 --env B=2).
Mounting the verbs in another CLI
Section titled “Mounting the verbs in another CLI”cyber-mux also ships as a clibuilder plugin, so a CLI
built on clibuilder can offer every verb under mux — <host> mux list is cyber-mux list. Install
cyber-mux beside the host and list the plugin in the host’s config:
{ "plugins": ["cyber-mux/plugin"] }The verbs, flags, and exit codes are the same as the standalone binary’s. The host’s clibuilder
prints their answers and errors, so they come out in the host’s output mode and default format: a
clibuilder 12 host answers in TOON unless the caller passes --format text or --format json. A usage
error spells its fix through the host (Usage: <host> mux worktree open <arguments> [options]).
Diagnostics
Section titled “Diagnostics”doctor— probe the multiplexer, self pane, and resolved backend.mode— print just the detected backend name.
Driving panes
Section titled “Driving panes”open— open a new pane/tab/workspace, optionally launching a command.send— type text or press keys, without taking the pane’s turn.submit— take a pane’s turn.read— capture a pane’s output.wait— block until a pane’s output matches, or the timeout elapses.focus— beam the attached client to a pane.close— close a pane.
Inspecting panes
Section titled “Inspecting panes”list— enumerate every live pane.exists— probe whether a single pane is still live.agent—statusa pane’s agent-lifecycle state, orwaitfor it to reach one.