Help catalog¶

42 verified entries in help / catalog.

spex help¶

help:overview

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`b9ba931da16a32038079d8fba1eee5b2489fa1f95d8958832d73eb35ebf96708`
Content role	`help`

spex — SpexCode CLI (spec↔code graph + worktree session state machine)

Usage: spex <noun> <verb> [object] [flags]     the verb is always the token after its noun;
                                               a bare noun prints that drawer's help
       spex help <command>                     one command's usage (or spex <command> --help — always
                                               safe: a help probe never runs the verb)

Project verbs (implicit object = this project)
  graph                 the assembled view: bare = readable tree · --json = the full payload
  init [dir]            adopt SpexCode on a repo: seed .spec + hooks + materialize  --harness <ids> [--preset name]
  materialize           the base pass of harness adaptation: render .spec/.plugins into your harness’s artifacts
  doctor                diagnose spec health and whether the workflow reaches this agent  [--contract|--conflicts]
  uninstall [dir]       remove all derived artifacts + local state; preserve tracked intent  [--hooks]
  serve [api|ui]        api (default) = the backend :8787 · ui = the dashboard :5173 on top of it
  dashboard             ONE dashboard for every project you serve — no --api-port pairing  [--port N=5173]
  guidance              export the immutable guidance catalog index  [--out <path>]

Noun drawers
  spec <verb>           the governance graph: search · owner · lint · ack
  session <verb>        the worktree state machine: new · ls · watch · wait · review · merge · send · …
  eval <verb>           the measurement system: add · ls · scenario ls/write · lint · ok · retract · clean
  issue <verb>          concern threads, local + forge merged: ls · show · open · reply · close · promote · links
  remark <verb>         resolvable pins on a host: add · resolve · retract
  evidence put|get      content-addressed bytes: put stashes & prints the hash, get reads back

Manuals
  guide [topic]         the manuals: setup workflow · spec/eval file formats · spexcode.json · footprint

Conventions (stated once, hold everywhere)
  SEL = session id (or unique id-prefix) | node id | branch — every session read/control verb
  accepts any of the four; inside a session worktree, . means that worktree's session. On the list verbs (ls/watch),
  none (or @all) means every session.
  `.` as a node argument means the node THIS worktree works on (the session's bound node, else the
  node/<id> branch). One-shot payload reads (graph · spec search · session ls/show/review · eval ls ·
  scenario ls · issue ls/show/links) take --json.
  Backend routing: every backend-touching verb accepts --api <url> (--port <n> = localhost sugar) to name
  its backend explicitly — the flag always wins. Bare, it resolves: worker env / the cwd project's live
  recorded backend / fallback / :8787 (spex guide settings → BACKEND ROUTING). A password-gated explicit
  gateway accepts --password <pw> (or SPEXCODE_PASSWORD); its self-signed certificate needs explicit --insecure.
  Mentions: @session · [[node]] work in ANY prompt, issue, or remark body — text passed as a CLI arg included.
  [[node]] names a topic; @session names a retained session for the receiving agent to inspect, contact with
  `spex session send`, or inherit with `/distill`. Mentions are references only: they never send or spawn.

Concepts & best practice live in the guide: spex guide (setup) · guide spec · guide eval · guide settings · guide footprint.
Machine plumbing (hook/launch-script callees) lives under `spex internal` — not part of your vocabulary.

spex help dashboard¶

help:dashboard

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`bf09e483919c37502cdd1e46f54503482153f8f774975b47f2e6b000d68497f9`
Content role	`help`

spex dashboard — ONE dashboard for every project you serve — no --api-port pairing  [--port N=5173]

Usage: spex dashboard [--port N=5173] [--host H=127.0.0.1]

The HOST gateway: serves the built dashboard once and routes to EVERY backend the current user runs —
the multi-project hub engine plus the host registry on top. It continuously reconciles the per-project
endpoint records each `spex serve` publishes (validating each against the live backend's /api/instance
identity), keeps a durable known-project catalog, and proxies each project's API + SSE + terminal
socket under /p/<projectId>/* — the project is named in the path, so nothing is "current" and no
pairing flag exists.

Admin surface (hub-authorized: implicit from loopback until an admin password is set, then cookie
sessions): GET /projects (the validated list + gating state) · GET /projects/stream (SSE) ·
GET /projects/browse?path=… (read-only host folder picker) · POST /projects {root, initGit?, init?}
(explicit setup, then register) · GET|PUT /projects/<id>/config (raw portable
spexcode.json, revision-guarded) · POST /projects/<id>/init|doctor|serve
(run the real `spex init`/`spex doctor`, or start an offline project's backend, detached — a
backend never depends on this gateway staying up) · PUT|DELETE /projects/admin-password and
/projects/<id>/password (the gates). A gated project answers /p/<id>/login with the designed page.

Loopback-only by default; --host widens the bind — the admin surface stays locked to loopback until
an admin password exists, and ungated projects serve open.

see also: spex serve (each project's backend) · spex serve ui (explicit one-backend pairing)

map: spex help · skills: spex guide

spex help doctor¶

help:doctor

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`95bb58d485dc84af20caaaeea011d32ed51440de7261bf251943d308231f9eb4`
Content role	`help`

spex doctor — diagnose spec health and whether the workflow reaches this agent  [--contract|--conflicts]

Usage: spex doctor                spec-health findings + delivery report: preconditions · git-hook floor ·
                                  contract · hooks + handler existence · backend · footprint
       spex doctor --contract     print the composed surface:system text any agent here reads
       spex doctor --conflicts    detect double-delivery (loose artifacts beside the managed ones)

Bare doctor is the opt-in, read-only health surface: it reports altitude and breadth findings without
putting them in the lint gate, then audits workflow delivery. Run it directly or let the tidy workflow
consume the same visible diagnosis.

see also: spex spec lint (deterministic graph/contract gate) · spex materialize (repair delivery artifacts)

map: spex help · skills: spex guide

spex help eval¶

help:eval

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`624484225f1ae78f52a853396994967201f8efb6017b331580fbdc044e8463e2`
Content role	`help`

spex eval — the measurement system: add · ls · scenario ls/write · lint · ok · retract · clean

Usage: spex eval add [<node>|.] [--scenario <name>] (--pass|--fail) [--note <text>]
                    [--image <png> …repeatable] [--result <path|->] [--video <webm|mp4>] [--timeline <json>]
       spex eval ls [<node>|.] [--json]                a node's eval timeline, newest first
       spex eval ls --session <SEL> [--json]           a session's aggregate: its changed nodes' scores
       spex eval ls --session <SEL> --export [--open | --out <path>]
       spex eval scenario ls [<node>|.] [--unmeasured] [--json]   declared scenarios; JSON = canonical index
       spex eval scenario write --mutation <json> < eval.md       propose one canonical metadata mutation
       spex eval lint [--changed]                      measurement-layer findings (advisory, always exit 0)
       spex eval ok <node> [--scenario <name>]         the HUMAN sign-off on the scenario's latest measurement
       spex eval retract [<node>|.] [--scenario <name>] [--last | --ts <iso>] [--note <why>]
       spex eval clean [--keep-latest | --all]         GC the content-addressed evidence cache

add — file an eval of a scenario against its expected: the loss signal the optimizer reads.
Measure through the REAL product surface, never by reasoning about the code. Evidence kind follows
the behaviour: MOVING/timed behaviour records a --video; a STATIC end state screenshots --image;
backend/CLI files a --result transcript. A fix's evidence is a fail→pass pair on the SAME scenario.

ls — node-scoped bare (its per-scenario eval history); session-scoped with an EXPLICIT --session
(never type-sniffed): filed evals are newest-first across nodes and source ownership; own measurements
are ✦-marked, evals filed by other sessions are unmarked, and blind spots follow measured rows. --export writes ONE self-contained
HTML artifact (diff · evidence inlined · gates) for CI/sharing.

scenario ls — the DECLARED contracts, no evals: text may show the latest verdict and --unmeasured is its blind-spot
worklist; --json emits the complete canonical semantic/measurement index with stable hashes and fixed-tree provenance
(--unmeasured is text-only because the JSON projection never reads the eval sidecar).

scenario write — the fixed-tree declaration writer for an external measurement guard: stdin is the authoritative
eval.md, --mutation is one closed JSON insert/delete request for one scenario's test metadata, and stdout is only
the proposed eval.md bytes. It reads no worktree or runner and fails without stdout on malformed or ambiguous input.

lint — the measurement layer's findings: malformed eval.md (eval-schema) · unmeasured (eval-missing) ·
stale (eval-drift) · orphaned remark tracks (eval-dangling) · governed source with no eval.md
(eval-coverage — the same name and shape as spec lint's coverage, one rule per layer) · over-owned
files (eval-owners). --changed scopes to the nodes THIS branch touched. spec lint's errors block
commits; eval lint is PURE ADVISORY, always exit 0 — a measurement gap never blocks anyone.

ok — the human's reviewed-and-agreed mark on the scenario's LATEST measurement: an appended, monotonic
sign-off bound to that one immutable measurement (a newer measurement or staleness releases it on its own —
no un-ok exists). The evals feed default-hides a fresh, ok'd scenario; a governed session is refused
(an agent's judgment on a measurement is a remark, never a self-blessing).

retract — the sanctioned undo for a botched filing: APPENDS a retraction event (traceable, never
deletes a line); the previous eval becomes latest again, or the scenario honestly returns to
unmeasured.

`.` as a node argument means the node THIS worktree works on (the session's bound node, else the
node/<id> branch). One-shot payload reads (graph · spec search · session ls/show/review · eval ls ·
scenario ls · issue ls/show/links) take --json.

see also: spex guide eval (the eval.md scenario format + evidence rules) · spex evidence (bare byte transport)

map: spex help · skills: spex guide

spex help evidence¶

help:evidence

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`14b1861f855e7dd23bff818f8e86b9be628c5075bea253eec6af30fd6bcf5be9`
Content role	`help`

spex evidence — content-addressed bytes: put stashes & prints the hash, get reads back

Usage: spex evidence put <file|->
       spex evidence get <hash> [-o <file>]

put writes bytes into the shared content-addressed evidence cache and prints the hash — transport
only, no eval filed. Use the hash with --evidence on issues/remarks; re-putting the same content
restores pruned or cloned-away evidence.

get is the symmetric read: hash in, bytes out. Local cache first (no backend needed — the evidence
is usually on this disk), then the backend on a local miss; both missing fails loud naming each
path. Bytes go to stdout by default (pipe-friendly); -o writes a file.

see also: spex eval add (file an eval WITH evidence) · spex issue open --evidence <hash>

map: spex help · skills: spex guide

spex help graph¶

help:graph

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`e7c7314c04cd853dfc55b375deb0599d13edd3cc4e2c735b521ed6940ae563a0`
Content role	`help`

spex graph — the assembled view: bare = readable tree · --json = the full payload

Usage: spex graph [--focus <id>] [--depth N] [--json]

The ONE assembled view — merged spec tree + worktree overlay + sessions. Bare it renders the
status-coloured tree (coloured when stdout is a tty; NO_COLOR respected), one line per node: id,
derived status, title, and attention badges (drift:N · stale:N · issues:N · ghost).
  --focus <id>  render just that subtree (unknown id fails loud)
  --depth N     limit levels below the shown root; prunes are counted, never silent
  --json        the full payload (tree · overlay · sessions), identical to GET /api/graph — machine
                food; with --focus/--depth it is that filtered subtree as nested objects instead

see also: spex spec search (find one node by intent) · spex session ls (just the sessions, as a table)

map: spex help · skills: spex guide

spex help guidance¶

help:guidance

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`681615999d2224e8edaefd35c529d182abe4efde6652d3fffe692275de6c75f2`
Content role	`help`

spex guidance — export the immutable guidance catalog index  [--out <path>]

Usage: spex guidance [--out <path>] [--json]

Prints the deterministic, schema-versioned guidance index. Entries point at the authoritative active plugin,
help, and guide sources with exact rendered content, content hashes, and git revision provenance. The derived
effective system-contract view follows materialization order; no separate authoring source is created.
--out writes the same bytes to a file instead of stdout.

see also: spex help · spex guide (the source guidance surfaces)

map: spex help · skills: spex guide

spex help guide¶

help:guide

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`6ad9a4fb0106e3a1624b7765112dd6f6b3ee4ffc93d0c1679aeedbd4208a5204`
Content role	`help`

spex guide — the manuals: setup workflow · spec/eval file formats · spexcode.json · footprint

Usage: spex guide            the human setup workflow (install once, adopt a repo, serve)
       spex guide spec       the spec.md file format + every lint rule
       spex guide eval       the eval.md scenario format + how loss is measured and filed
       spex guide settings   every spexcode.json / spexcode.local.json field, and which file it belongs in
       spex guide footprint  the footprint model: never-tracked artifacts, exclude + content filter, anchors

guide is the SKILL layer — workflows and formats. Command usage lives here in help
(`spex help <cmd>`); guide carries what the commands assume you know.

map: spex help · skills: spex guide

spex help help¶

help:help

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`e310e52974337a2377705d16d46a34c91a3e48a3bbeb8033d70337408c43da0a`
Content role	`help`

Usage: spex help              the command map
       spex help <command>    one command/drawer's usage (same as spex <command> --help)
       spex guide [topic]     the skill layer: workflows, file formats, best practice

map: spex help · skills: spex guide

spex help init¶

help:init

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`25c43590b8649fbff0dc43d778b6f79e7a03e3e3bcf24996355f64d9480d2fb7`
Content role	`help`

spex init — adopt SpexCode on a repo: seed .spec + hooks + materialize  --harness <ids> [--preset name]

Usage: spex init [dir=cwd] --harness <id[,id]|plugin:<folder>> [--preset default]

Scaffolds adoption in one shot: seeds a starter .spec tree (project root + .plugins plugins), plants
spexcode.json, installs the git hooks, and materializes the harness artifacts (contract block +
shims). --harness is REQUIRED — the explicit choice of which harnesses materialize delivers into
(stamped as spexcode.json "harnesses"; only their launchers are seeded); a pre-existing "harnesses"
field satisfies it. Additive — never overwrites your files. --preset picks the .plugins plugin tier (cumulative).
Footprint is fixed: materialized artifacts are never tracked — hidden via the per-clone .git/info/exclude, with
a tracked/mixed CLAUDE.md/AGENTS.md covered by the clean/smudge filter (see spex guide footprint).

see also: spex guide (the full setup workflow) · spex uninstall (the inverse) · spex spec lint (adoption TODO)

map: spex help · skills: spex guide

spex help internal¶

help:internal

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`756c1a85d6f7d6e9711a4de766ec1c767af772d63c8728c33a769de2d46a75ee`
Content role	`help`

Usage: spex internal <sub>

Machine plumbing — called by generated hooks and launch scripts, never typed by a human or agent:
  trunk             print the resolved source-of-truth branch (the pre-commit main-guard captures it)
  commit-surgery    pre-commit footprint anchor: unconditional materialize + staged-index repair
  refresh-footprint quiet materialize — the post-checkout/post-merge freshness anchor
  check-staged      pre-commit eval backstop: reject staged stray evidence files / malformed eval.md
  session-state <st> --session <id>   a lifecycle hook authors the session's state
  session-fail  --session <id>        the StopFailure hook marks the session errored
  session-idle  --session <id>        the idle-prompt hook marks an active session idle
  commit-gate       the Stop gate's deterministic commit check (exit 0 = ready to declare done)
  hook-prompt <name>                  render canonical model-facing text for a runtime hook
  nudge <node>      the post-merge hook prints the issue nudge for a merged node
  shared-runtime-spawn <cwd> <log> <pid> <scope> <cmd> [args…]  detached adapter control plane (launch script)
  codex-launch <sock> <cwd> [prompt…]   backend-owned codex thread/start + first turn (launch script)
  codex-turn   <sock> <threadId> <text…>  fire a follow-up turn on an owned thread (tests/scripts)
  claude-headless-run <id> <runtime> <cmd> -- <tail…>  resident stream-json controller (launch script)
  pi-headless-run <id> <runtime> <cmd> -- <tail…>      resident pi text-mode controller (launch script)

If you reached for one of these by hand, the porcelain you want is probably elsewhere: the trunk
name also lives at GET /api/settings (.layout); sessions are driven with spex session new / session send;
your own state is declared with spex session done|park|ask.

see also: spex help (the porcelain map)

map: spex help · skills: spex guide

spex help issue¶

help:issue

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`c4f181e56ff97a4535dd66d230ebc5ed8e9abcfcd608c367c9c172722e96df5b`
Content role	`help`

spex issue — concern threads, local + forge merged: ls · show · open · reply · close · promote · links

Usage: spex issue ls [--node <id>] [--store local|<host>] [--all] [--json]
       spex issue show <id> [--json]
       spex issue open "<concern>" [--store local|<host>] [--node <id>…] [--evidence <hash>…] [--body -|<text>]
       spex issue reply <id> --body -|<text> [--evidence <hash>…]
       spex issue close <id>
       spex issue promote <id>
       spex issue links [--pending] [--store <host>] [--node <id>] [--json]

ls is the drain view a supervisor reads: ONE store-tagged list, local + forge interleaved by
creation time. `show <id>` is the single-thread detail — the whole thread with its replies (a local
id, or a forge id like github#12). `open` welcomes taste, annotations, and off-mainline smells —
not only bugs; --store <host> opens straight on the forge. `reply` and `close` route by the
issue's store — one verb, local or forge. `promote` moves an OPEN local issue to the forge as one
recorded action. `links` is the read-only forge trace: which open forge issues/PRs serve which
spec node (--pending narrows to threads still awaiting an eval). The issues workflow's
on/off switch is the `issues.enabled` key in spexcode.json (no CLI toggle verb — edit the JSON;
`spex doctor` reports its state).
Mentions: @session · [[node]] work in ANY prompt, issue, or remark body — text passed as a CLI arg included.
[[node]] names a topic; @session names a retained session for the receiving agent to inspect, contact with
`spex session send`, or inherit with `/distill`. Mentions are references only: they never send or spawn.

see also: spex remark (pin a resolvable concern to an issue or scenario) · spex evidence put (stash evidence bytes)

map: spex help · skills: spex guide

spex help materialize¶

help:materialize

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`bc4c3a0525d1a27e2d5d86a69ff4506842252eec2a4f069afe4af3c4f999363a`
Content role	`help`

spex materialize — the base pass of harness adaptation: render .spec/.plugins into your harness’s artifacts

Usage: spex materialize

The base operation of HARNESS ADAPTATION: one pass renders the spec tree's surface nodes into the
artifacts each selected harness auto-discovers — the managed <!-- spexcode --> block of
CLAUDE.md/AGENTS.md, the .claude/.codex shims, the skills/agents — and prints the content hash.
The outputs are derived and never tracked: to change one, edit its source (.plugins, spexcode.json)
and re-materialize — never the artifact. Not a one-time setup: it anchors on git-native events
(init · this verb · session-worktree creation · the pre-commit/post-checkout/post-merge hooks) —
run it by hand after a toolchain update, or in the setup step of any clone that has no spex-planted
hooks yet (CI, a cloud agent): generated and excluded, the artifacts never arrive via git.

see also: spex doctor (verify the materialized artifacts actually reach an agent)

map: spex help · skills: spex guide

spex help remark¶

help:remark

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`9c953f56a1533eacb245c2fd64623f31bc5f1bedc21c334d81b38c7780a81396`
Content role	`help`

spex remark — resolvable pins on a host: add · resolve · retract

Usage: spex remark add <issue-id | <node> --scenario <name>> --body -|<text> [--code-sha <sha>] [--evidence <hash>…]
       spex remark resolve <ref>          (the <thread-id>#<rid> that `spex remark add` printed)
       spex remark retract <ref>

The resolvable interaction primitive: `add` pins a concern to a HOST — a local issue, or a scenario
(`--scenario` present ⇒ the positional is a node; otherwise it is an issue id — the flag decides,
never type-sniffing). A SECOND agent `resolve`s it (never the author); the AUTHOR `retract`s their
own. The whole loop is CLI-first; the dashboard adds no capability.

see also: spex issue (the thread hosts) · spex eval ls (scenario hosts)

map: spex help · skills: spex guide

spex help serve¶

help:serve

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`a93c122d4e81ae84a0c26044201c3e0599a41ef2bb34361178ad3432c2eeee2c`
Content role	`help`

spex serve — api (default) = the backend :8787 · ui = the dashboard :5173 on top of it

Usage: spex serve [api] [--port N=8787]
       spex serve [api] --public --password <pw> [--tls-cert F --tls-key F] [--http]
       spex serve ui [--port N=5173] [--api-port N=8787] [--host H=127.0.0.1]

`serve` (or `serve api`) runs the backend for the repo at cwd behind a zero-downtime supervisor
(hot-reloads on source change; the public port never gaps). On a successful bind it RECORDS its
endpoint in the per-project runtime tier — that's how a bare `spex` run from this project's tree
finds this backend (spex guide settings → BACKEND ROUTING). --public exposes it on a public IP behind
a password + self-signed TLS (own cert via --tls-cert/--tls-key; --http drops TLS).

`serve ui` is a SEPARATE process: it serves the bundled dashboard on its own port and proxies /api +
the terminal socket to a running backend (--api-port pairs with the backend's --port, so many
projects coexist on one host). Loopback-only by default; --host 0.0.0.0 opens it to a LAN/tailnet —
still plain HTTP with no gate, so bind wide only on a network you trust.

see also: GET /health (backend liveness probe)

map: spex help · skills: spex guide

spex help session¶

help:session

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`315cc1d3bea368085e0e63d7da833ca73357d1ca0ec399124eb2b9b8488cd997`
Content role	`help`

spex session — the worktree state machine: new · ls · watch · wait · review · merge · send · …

Manager verbs (dispatch, monitor, land):
  spex session new "<prompt>" [--prompt-file <path>|-] [--launcher <name>] [--name <name>] [--base <commit-ish>]
      Launch a worker in its own node worktree. The materialized system contract reaches it
      automatically; the prompt supplies the task context. Its first [[id]] mention binds the
      session to that node. --prompt-file <path>|- carries a long prompt without shell quoting
      (exclusive with the inline prompt). --name sets the session's initial display name without changing the prompt.
      --base <commit-ish> pins the fork point instead of the source-of-truth branch's current head, so a run can be
      reproduced against a frozen commit; a base that names no commit is refused before anything is created.
      The successful receipt names what to read, monitor, and reply on.
  spex session ls [SEL…] [--status a,b] [--all] [--json]
      One-shot table of living sessions. Shelved sessions ([[archive]]) are hidden; --all includes them, and naming one explicitly always shows it.
  spex session resources [--json]
      Read-only host/process ownership, budgets, shared refs, and findings.
  spex session watch <SEL…>
  spex session watch list
  spex session watch cancel <SEL…>
  spex session watch stream [SEL…] [--as NAME] [--idle] [--interval N=1]
      With a governed caller, watch registers durable send-backed state delivery and exits. list/cancel manage those relations. Without a governed caller it names the background `session wait` fallback. stream is the human-only continuous log view and blocks until killed.
  spex session wait [SEL…] [--timeout S=1200] [--interval S=1] [--idle]
      EDGE-TRIGGERED wait: follows the selected sessions' logs AND your own log, and exits 0 on
      the FIRST thing worth waking for — a followed session TRANSITIONING from a non-actionable
      status into an actionable one (stdout = the observed path, e.g. working→review; read the LAST
      token as the status reached), or a message arriving for you (stdout = message). The arrival
      status is printed immediately on stderr but never returns it: it NEVER returns just because a
      session is actionable ALREADY — for "what is it right NOW" use `session ls` / `session review`.
      It reads files only, so it needs no `spex serve` and costs the sessions it follows nothing.
      --timeout is the guaranteed exit (code 1, observed path on stderr); code 2 = a followed
      session's store is gone.
  spex session review <SEL> [--json]
      Reports ahead · uncommitted · proposal · gates · merge-base diff.
  spex session merge <SEL>
      Dispatches a gated merge to the session's own agent; it does not close the session.
  spex session reparent <child-SEL...> --to <parent-SEL>
      Move one or more governed children to a replacement parent, replacing only the former parent's managed watch relation. It never restarts a child and works when the former parent is offline.

Control another session:
  spex session send <SEL> "<msg>"
  spex session send <SEL> [--api <url> | --port <n>] -- <option-shaped-msg>
  spex session send <SEL> --keys "<keys>"
      Plain send delivers a message once its timeline append succeeds; a dead adapter only delays its context. Routing flags may precede or follow ordinary text; use -- before a message that begins with --. --keys is the LAST RESORT:
      raw nav-mode keystrokes to a TUI dialog ("Up Up Enter", C-/M-/S- combos). The raw key surface
      is UNSTABLE and can confirm dangerous dialogs — try a plain send first; use keys only when text
      provably cannot land.
  spex session interrupt <SEL>
      Hard-interrupt the current turn through native harness control.
  spex session rename <SEL> "<name>"
      Set the display name; an empty name clears it.
  spex session show <SEL> [--capture] [--json]
      The session record: status · node · branch · launcher · the full originating prompt.
      --capture prints the LIVE PANE as text instead (empty pane = exit 0; unknown session = exit 2).
  spex session resume <SEL> [--force]
      Relaunch ONLY if confirmed offline; --force is for a wedged session.
  spex session stop <SEL>
      Soft stop: kill the exact agent and KEEP the worktree resumable.
  spex session archive <SEL>
      Cold-archive it: exact leaf/runtime stopped, worktree and conversation kept.
  spex session unarchive <SEL>
      Deprecated compatibility spelling: same behavior as resume, relaunching the same conversation.
  spex session close <SEL>
      Retire ANOTHER session — one you dispatched — deleting its worktree, branch and record.
      <SEL> names that session; it is never `.` and never your own id. Closing yourself deletes the worktree
      you are running in, mid-turn. Your own ending is a declaration: `done --propose close`.
  spex session quarantine <ID> --adapter <harness> [--thread <native-id>] --tmux <id> --worktree <absent-path> --branch <absent-branch> [--restore]
      Move only an unreadable record after the backend proves every named residue absent. --thread is an adapter-native conversation id, never the SpexCode session id; omit it for Claude. Quarantine and --restore both require the original exact id because corrupt rows are outside selectors.

Worker verbs (declare YOUR OWN state — a claim the graph and your supervisor act on):
  spex session done --propose merge|nothing|close [--note T]
      `merge` declares review: committed work ready for human review, and it is the ONLY declaration that offers a clickable merge. `nothing` is an intended trap: it writes no state and sends the agent to the true merge, close, ask, or park destination. `close` declares close-pending only for settled work: discardable worktree and no outstanding human decision, follow-up, or inspection. The human closes it. This declaration is how a session ends itself; never run `session close` on your own id.
  spex session park --note <what-you-await>
      Declare parked only when a managed watch delivery or real background task will wake your own session. It self-resumes; waiting for a human is asking, not parked.
  spex session ask --note <your-question>
      Declare asking when the session needs a human reply or direction, including an answered exploratory question or handoff awaiting follow-up. It resumes only when the human replies; a background wake-up is parked instead.
  spex session files add <path>
  spex session files ls
  spex session files retract <path>
      Publish, list, or withdraw YOUR session’s live file paths. Posting stores an absolute path beside the session record without copying bytes; the dashboard downloads it only when the human clicks.
  spex session web add <url>
  spex session web ls
  spex session web retract <url>
      Publish, list, or withdraw YOUR session’s live loopback web-service URLs. Posting records no bytes and does not contact the service; the dashboard proxies the current HTTP/WebSocket service only when the human opens its preview.

Human escape hatch:
  spex session attach <SEL>
      Attaches the current terminal to the worker's tmux (detach: C-b d) and blocks until detached.
      LOCAL-only (fails loud on a remote backend); show --capture and send are non-interactive.

SEL = session id (or unique id-prefix) | node id | branch — every session read/control verb
accepts any of the four; inside a session worktree, . means that worktree's session. On the list verbs (ls/watch),
none (or @all) means every session.
Manager verbs that WRITE (send/interrupt/rename/resume/stop/close/merge/reparent) are PROJECT-BOUND: a backend serving
another project's repo refuses loudly — name the target with --api <url> to drive it on purpose.
Mentions: @session · [[node]] work in ANY prompt, issue, or remark body — text passed as a CLI arg included.
[[node]] names a topic; @session names a retained session for the receiving agent to inspect, contact with
`spex session send`, or inherit with `/distill`. Mentions are references only: they never send or spawn.

see also: spex eval ls --session <SEL> (the session’s measured loss) · spex help eval

map: spex help · skills: spex guide

spex help spec¶

help:spec

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`08ce6d25a7ac5e708bc90c6679e8cca5653b8fff00b692999552a019bca3b6d0`
Content role	`help`

spex spec — the governance graph: search · owner · lint · ack

Usage: spex spec search <query…> [--limit N=10] [--json]
       spex spec owner <path> [--actionable]
       spex spec lint [--json]
       spex spec ack <node-id>… --reason "<why the contract still holds>"

search — which spec node GOVERNS a topic, ranked by user-story relevance (which surfaces user-facing
behaviour a code-grep misses). Run it BEFORE touching code: the node's spec.md body is the current
contract. The corpus is English — query in English.

owner — the reverse edge: a file's GOVERNORS (code: — drives drift + eval freshness) and REFERENCERS (related:
— coverage only), with the verdict spelled out (uncovered / related-only / sanely governed /
over-owned → split the file). --actionable prints NOTHING unless action is needed (hook use).

lint — checks the whole spec↔code graph and exits non-zero on errors. Errors: integrity (a
code:/related: file does not exist; a dead/ambiguous/unverifiable `path#symbol` selector; a selector
whose language has no designated extractor or whose extractor can't run here; a duplicate entry, a
base path both bare and scoped, or a selector on a glob/directory) · anchor-drift (a
commit since the spec's version touched an ANCHORED unit's lines, unacked — the blocking tier of
drift; same-file selectors OR'd, one error naming the hit selectors) · one-govern (a node
governs >1 DISTINCT file) · living (a "## vN" changelog heading) · id-format (an
id char outside the whitelist — ascii [a-z0-9-] or a non-ascii unicode letter/number, CJK ok — or a
leaf id reused) · mention (a [[id]] naming no node). Warns: coverage · drift
(UNANCHORED drift — always advisory, never blocks; on a scoped file's MISS, `lint.scopedCodeMiss:
"ignore"` may silence it) · anchor (anchoring a type) · related-drift (a scoped related row warns
per selector HIT, misses silent) · owners (whole-file governors only; scoped don't count) ·
confusable-id (two leaf ids one edit apart). spec lint's errors BLOCK commits (the prepared reference hook; bypass SPEXCODE_SKIP_LINT=1);
contrast `spex eval lint`, which is pure advisory and never blocks anyone. `--json` writes the
versioned machine report to stdout (source candidates + structured findings); its exit code still blocks
on errors.

ack — stamp Spec-OK on HEAD (an empty stamp commit): the drift remedy when only MECHANICS changed
and the spec's contract still holds. --reason is required and recorded in the ack commit's body
(quieting an anchor hit is a strong claim — the why must be durable). If the intent DID change,
edit the spec instead — same commit as the code.

see also: spex guide spec (the file format + every lint rule) · spex graph (browse the whole tree)

map: spex help · skills: spex guide

spex help uninstall¶

help:uninstall

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`ab6392642b05e9cef2299bb2f163eb5d9f68d651a799fb21b24b6711bab216b8`
Content role	`help`

spex uninstall — remove all derived artifacts + local state; preserve tracked intent  [--hooks]

Usage: spex uninstall [dir=cwd] [--hooks]

Removes all SpexCode-derived wiring and project-local state: contract blocks, harness shims,
generated skills/agents, plugin bundles, trust/filter/exclude entries, and the global per-project
store. Your tracked intent (.spec including .plugins, plus spexcode.json) and surrounding user prose
are preserved. Git hooks remain unless --hooks; that flag removes only unmodified canonical copies.

see also: spex init (re-adopt later — your tracked intent survives)

map: spex help · skills: spex guide

spex session archive --help¶

help:session.archive

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`e567e3c46d8da527e496bb212743e293ba487322a2026e4848f24a064c4d2c49`
Content role	`help`

Usage: spex session archive <SEL>

Cold-archive it: exact leaf/runtime stopped, worktree and conversation kept.

SEL = session id (or unique id-prefix) | node id | branch — every session read/control verb
accepts any of the four; inside a session worktree, . means that worktree's session. On the list verbs (ls/watch),
none (or @all) means every session.

see also: spex session (the complete drawer)

map: spex help · skills: spex guide

spex session ask --help¶

help:session.ask

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`a22863de0c4f12bf2a731192deda2a659ca8b977cf56452f61d17e035c6f37f0`
Content role	`help`

Usage: spex session ask --note <your-question>

Declare asking when the session needs a human reply or direction, including an answered exploratory question or handoff awaiting follow-up. It resumes only when the human replies; a background wake-up is parked instead.

see also: spex session (the complete drawer)

map: spex help · skills: spex guide

spex session attach --help¶

help:session.attach

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`40f576eff0b320478c9f3bc526f9931b750e9c0162408e3c87693c28d0e8e5e3`
Content role	`help`

Usage: spex session attach <SEL>

Attaches the current terminal to the worker's tmux (detach: C-b d) and blocks until detached.
LOCAL-only (fails loud on a remote backend); show --capture and send are non-interactive.

SEL = session id (or unique id-prefix) | node id | branch — every session read/control verb
accepts any of the four; inside a session worktree, . means that worktree's session. On the list verbs (ls/watch),
none (or @all) means every session.

see also: spex session (the complete drawer)

map: spex help · skills: spex guide

spex session close --help¶

help:session.close

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`eb97d6613ebf537e49d13b797b7538ef145a6c020d80d112a5fe79d64e873aa8`
Content role	`help`

Usage: spex session close <SEL>

Retire ANOTHER session — one you dispatched — deleting its worktree, branch and record.
<SEL> names that session; it is never `.` and never your own id. Closing yourself deletes the worktree
you are running in, mid-turn. Your own ending is a declaration: `done --propose close`.

SEL = session id (or unique id-prefix) | node id | branch — every session read/control verb
accepts any of the four; inside a session worktree, . means that worktree's session. On the list verbs (ls/watch),
none (or @all) means every session.

Manager verbs that WRITE (send/interrupt/rename/resume/stop/close/merge/reparent) are PROJECT-BOUND: a backend serving
another project's repo refuses loudly — name the target with --api <url> to drive it on purpose.

see also: spex session (the complete drawer)

map: spex help · skills: spex guide

spex session done --help¶

help:session.done

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`f2f8f5fe9ca601f567aaa56deaa1f27e4690e4a28b3e9aaed86b010edc40c7be`
Content role	`help`

Usage: spex session done --propose merge|nothing|close [--note T]

`merge` declares review: committed work ready for human review, and it is the ONLY declaration that offers a clickable merge. `nothing` is an intended trap: it writes no state and sends the agent to the true merge, close, ask, or park destination. `close` declares close-pending only for settled work: discardable worktree and no outstanding human decision, follow-up, or inspection. The human closes it. This declaration is how a session ends itself; never run `session close` on your own id.

see also: spex session (the complete drawer)

map: spex help · skills: spex guide

spex session files --help¶

help:session.files

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`4307a647157fa8649c87aa9de5aa7cab5173a4ad3fe2534089b02ac2ce50081b`
Content role	`help`

Usage: spex session files add <path>
       spex session files ls
       spex session files retract <path>

Publish, list, or withdraw YOUR session’s live file paths. Posting stores an absolute path beside the session record without copying bytes; the dashboard downloads it only when the human clicks.

see also: spex session (the complete drawer)

map: spex help · skills: spex guide

spex session interrupt --help¶

help:session.interrupt

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`3dbac0299b9e0016b0ec2dda0d4ee1313d2b2c166f52ba7d8d0207ca0280b206`
Content role	`help`

Usage: spex session interrupt <SEL>

Hard-interrupt the current turn through native harness control.

SEL = session id (or unique id-prefix) | node id | branch — every session read/control verb
accepts any of the four; inside a session worktree, . means that worktree's session. On the list verbs (ls/watch),
none (or @all) means every session.

Manager verbs that WRITE (send/interrupt/rename/resume/stop/close/merge/reparent) are PROJECT-BOUND: a backend serving
another project's repo refuses loudly — name the target with --api <url> to drive it on purpose.

see also: spex session (the complete drawer)

map: spex help · skills: spex guide

spex session ls --help¶

help:session.ls

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`ae93a6fe428250131405a2fafb9fed87d3c48d2b6204e04219ddeeebe74a3ed0`
Content role	`help`

Usage: spex session ls [SEL…] [--status a,b] [--all] [--json]

One-shot table of living sessions. Shelved sessions ([[archive]]) are hidden; --all includes them, and naming one explicitly always shows it.

SEL = session id (or unique id-prefix) | node id | branch — every session read/control verb
accepts any of the four; inside a session worktree, . means that worktree's session. On the list verbs (ls/watch),
none (or @all) means every session.

see also: spex session (the complete drawer)

map: spex help · skills: spex guide

spex session merge --help¶

help:session.merge

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`0130200ab81253721a5277c91508305ddcc20a74623b48096b52d6ee5eafdaa7`
Content role	`help`

Usage: spex session merge <SEL>

Dispatches a gated merge to the session's own agent; it does not close the session.

SEL = session id (or unique id-prefix) | node id | branch — every session read/control verb
accepts any of the four; inside a session worktree, . means that worktree's session. On the list verbs (ls/watch),
none (or @all) means every session.

Manager verbs that WRITE (send/interrupt/rename/resume/stop/close/merge/reparent) are PROJECT-BOUND: a backend serving
another project's repo refuses loudly — name the target with --api <url> to drive it on purpose.

see also: spex session (the complete drawer)

map: spex help · skills: spex guide

spex session new --help¶

help:session.new

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`2d28c51493e6eeb0301fad8c7bd7db48eb8e29520809194c606c75a20229962a`
Content role	`help`

Usage: spex session new "<prompt>" [--prompt-file <path>|-] [--launcher <name>] [--name <name>] [--base <commit-ish>]

Launch a worker in its own node worktree. The materialized system contract reaches it
automatically; the prompt supplies the task context. Its first [[id]] mention binds the
session to that node. --prompt-file <path>|- carries a long prompt without shell quoting
(exclusive with the inline prompt). --name sets the session's initial display name without changing the prompt.
--base <commit-ish> pins the fork point instead of the source-of-truth branch's current head, so a run can be
reproduced against a frozen commit; a base that names no commit is refused before anything is created.
The successful receipt names what to read, monitor, and reply on.

see also: spex session (the complete drawer)

map: spex help · skills: spex guide

spex session park --help¶

help:session.park

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`04a754839400c6ea660b51a5c085602cc138b55078d8fe2837a938fd30e3f287`
Content role	`help`

Usage: spex session park --note <what-you-await>

Declare parked only when a managed watch delivery or real background task will wake your own session. It self-resumes; waiting for a human is asking, not parked.

see also: spex session (the complete drawer)

map: spex help · skills: spex guide

spex session quarantine --help¶

help:session.quarantine

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`ab3d8c84cceaf8547561a7560e985f1c9a09d8380fbdc555aebabd80119a10bf`
Content role	`help`

Usage: spex session quarantine <ID> --adapter <harness> [--thread <native-id>] --tmux <id> --worktree <absent-path> --branch <absent-branch> [--restore]

Move only an unreadable record after the backend proves every named residue absent. --thread is an adapter-native conversation id, never the SpexCode session id; omit it for Claude. Quarantine and --restore both require the original exact id because corrupt rows are outside selectors.

Manager verbs that WRITE (send/interrupt/rename/resume/stop/close/merge/reparent) are PROJECT-BOUND: a backend serving
another project's repo refuses loudly — name the target with --api <url> to drive it on purpose.

see also: spex session (the complete drawer)

map: spex help · skills: spex guide

spex session rename --help¶

help:session.rename

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`883a3b6ffbd4d6a989b3d084ab257ecbbbf8d618825b780bfb3104a809d4056c`
Content role	`help`

Usage: spex session rename <SEL> "<name>"

Set the display name; an empty name clears it.

SEL = session id (or unique id-prefix) | node id | branch — every session read/control verb
accepts any of the four; inside a session worktree, . means that worktree's session. On the list verbs (ls/watch),
none (or @all) means every session.

Manager verbs that WRITE (send/interrupt/rename/resume/stop/close/merge/reparent) are PROJECT-BOUND: a backend serving
another project's repo refuses loudly — name the target with --api <url> to drive it on purpose.

see also: spex session (the complete drawer)

map: spex help · skills: spex guide

spex session reparent --help¶

help:session.reparent

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`aa12e86e5db682ea60b5b3bcda16224af9032ccbcd6f23dfe96d8f30680a5a93`
Content role	`help`

Usage: spex session reparent <child-SEL...> --to <parent-SEL>

Move one or more governed children to a replacement parent, replacing only the former parent's managed watch relation. It never restarts a child and works when the former parent is offline.

SEL = session id (or unique id-prefix) | node id | branch — every session read/control verb
accepts any of the four; inside a session worktree, . means that worktree's session. On the list verbs (ls/watch),
none (or @all) means every session.

Manager verbs that WRITE (send/interrupt/rename/resume/stop/close/merge/reparent) are PROJECT-BOUND: a backend serving
another project's repo refuses loudly — name the target with --api <url> to drive it on purpose.

see also: spex session (the complete drawer)

map: spex help · skills: spex guide

spex session resources --help¶

help:session.resources

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`bfe81a6cfb706441cdde77de53120621eb177ce4903895bd839dc359a4d18497`
Content role	`help`

Usage: spex session resources [--json]

Read-only host/process ownership, budgets, shared refs, and findings.

see also: spex session (the complete drawer)

map: spex help · skills: spex guide

spex session resume --help¶

help:session.resume

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`ff9cc680748a38cd71a86ed7c28983aba1bd0ad324487b5bb161f539d5b69a0a`
Content role	`help`

Usage: spex session resume <SEL> [--force]

Relaunch ONLY if confirmed offline; --force is for a wedged session.

SEL = session id (or unique id-prefix) | node id | branch — every session read/control verb
accepts any of the four; inside a session worktree, . means that worktree's session. On the list verbs (ls/watch),
none (or @all) means every session.

Manager verbs that WRITE (send/interrupt/rename/resume/stop/close/merge/reparent) are PROJECT-BOUND: a backend serving
another project's repo refuses loudly — name the target with --api <url> to drive it on purpose.

see also: spex session (the complete drawer)

map: spex help · skills: spex guide

spex session review --help¶

help:session.review

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`2d29e34d9bef8dea5ec2b5f42b07c8ca7c18301bf47c99794cb994e5bf6765c7`
Content role	`help`

Usage: spex session review <SEL> [--json]

Reports ahead · uncommitted · proposal · gates · merge-base diff.

SEL = session id (or unique id-prefix) | node id | branch — every session read/control verb
accepts any of the four; inside a session worktree, . means that worktree's session. On the list verbs (ls/watch),
none (or @all) means every session.

see also: spex session (the complete drawer)

map: spex help · skills: spex guide

spex session send --help¶

help:session.send

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`d11e6c3469625ad2adca3661be1462d61247220c7a8daa662058aee6f55074ed`
Content role	`help`

Usage: spex session send <SEL> "<msg>"
       spex session send <SEL> [--api <url> | --port <n>] -- <option-shaped-msg>
       spex session send <SEL> --keys "<keys>"

Plain send delivers a message once its timeline append succeeds; a dead adapter only delays its context. Routing flags may precede or follow ordinary text; use -- before a message that begins with --. --keys is the LAST RESORT:
raw nav-mode keystrokes to a TUI dialog ("Up Up Enter", C-/M-/S- combos). The raw key surface
is UNSTABLE and can confirm dangerous dialogs — try a plain send first; use keys only when text
provably cannot land.

SEL = session id (or unique id-prefix) | node id | branch — every session read/control verb
accepts any of the four; inside a session worktree, . means that worktree's session. On the list verbs (ls/watch),
none (or @all) means every session.

Manager verbs that WRITE (send/interrupt/rename/resume/stop/close/merge/reparent) are PROJECT-BOUND: a backend serving
another project's repo refuses loudly — name the target with --api <url> to drive it on purpose.

see also: spex session (the complete drawer)

map: spex help · skills: spex guide

spex session show --help¶

help:session.show

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`81e05e8d825feaf76e79cb99fe195d010cdec551698b97ba578e595cbee4fb49`
Content role	`help`

Usage: spex session show <SEL> [--capture] [--json]

The session record: status · node · branch · launcher · the full originating prompt.
--capture prints the LIVE PANE as text instead (empty pane = exit 0; unknown session = exit 2).

SEL = session id (or unique id-prefix) | node id | branch — every session read/control verb
accepts any of the four; inside a session worktree, . means that worktree's session. On the list verbs (ls/watch),
none (or @all) means every session.

see also: spex session (the complete drawer)

map: spex help · skills: spex guide

spex session stop --help¶

help:session.stop

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`194ef640148657d771e5f551f5db51c75ee6c9c753f6160baccf2e5a728fc9c3`
Content role	`help`

Usage: spex session stop <SEL>

Soft stop: kill the exact agent and KEEP the worktree resumable.

SEL = session id (or unique id-prefix) | node id | branch — every session read/control verb
accepts any of the four; inside a session worktree, . means that worktree's session. On the list verbs (ls/watch),
none (or @all) means every session.

Manager verbs that WRITE (send/interrupt/rename/resume/stop/close/merge/reparent) are PROJECT-BOUND: a backend serving
another project's repo refuses loudly — name the target with --api <url> to drive it on purpose.

see also: spex session (the complete drawer)

map: spex help · skills: spex guide

spex session unarchive --help¶

help:session.unarchive

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`3f779c336515d0056471f33af7f19949f7d075d7227ba7a18312419e6cd7de0b`
Content role	`help`

Usage: spex session unarchive <SEL>

Deprecated compatibility spelling: same behavior as resume, relaunching the same conversation.

SEL = session id (or unique id-prefix) | node id | branch — every session read/control verb
accepts any of the four; inside a session worktree, . means that worktree's session. On the list verbs (ls/watch),
none (or @all) means every session.

see also: spex session (the complete drawer)

map: spex help · skills: spex guide

spex session wait --help¶

help:session.wait

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`9000221ae4b5139ed1dcd5233beb4b7ecfdcab5ae5963bf345966131e8143e25`
Content role	`help`

Usage: spex session wait [SEL…] [--timeout S=1200] [--interval S=1] [--idle]

EDGE-TRIGGERED wait: follows the selected sessions' logs AND your own log, and exits 0 on
the FIRST thing worth waking for — a followed session TRANSITIONING from a non-actionable
status into an actionable one (stdout = the observed path, e.g. working→review; read the LAST
token as the status reached), or a message arriving for you (stdout = message). The arrival
status is printed immediately on stderr but never returns it: it NEVER returns just because a
session is actionable ALREADY — for "what is it right NOW" use `session ls` / `session review`.
It reads files only, so it needs no `spex serve` and costs the sessions it follows nothing.
--timeout is the guaranteed exit (code 1, observed path on stderr); code 2 = a followed
session's store is gone.

SEL = session id (or unique id-prefix) | node id | branch — every session read/control verb
accepts any of the four; inside a session worktree, . means that worktree's session. On the list verbs (ls/watch),
none (or @all) means every session.

see also: spex session (the complete drawer)

map: spex help · skills: spex guide

spex session watch --help¶

help:session.watch

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`b5ff9182ec0d35055db701f49458c976f1864dbecf83f3da668eeef09e700a5e`
Content role	`help`

Usage: spex session watch <SEL…>
       spex session watch list
       spex session watch cancel <SEL…>
       spex session watch stream [SEL…] [--as NAME] [--idle] [--interval N=1]

With a governed caller, watch registers durable send-backed state delivery and exits. list/cancel manage those relations. Without a governed caller it names the background `session wait` fallback. stream is the human-only continuous log view and blocks until killed.

SEL = session id (or unique id-prefix) | node id | branch — every session read/control verb
accepts any of the four; inside a session worktree, . means that worktree's session. On the list verbs (ls/watch),
none (or @all) means every session.

see also: spex session (the complete drawer)

map: spex help · skills: spex guide

spex session web --help¶

help:session.web

CLI command usage and safety guidance

Field	Value
Source path	`spec-cli/src/help.ts`
Source revision	`6a63deb6be59a992e9e25e193cc72b1d5c27b77e`
Content SHA-256	`60d3ed8ee27b5a94f51839ee0f215c99ade5d5d7e6b73ea1a8c2d7cc2484024f`
Content role	`help`

Usage: spex session web add <url>
       spex session web ls
       spex session web retract <url>

Publish, list, or withdraw YOUR session’s live loopback web-service URLs. Posting records no bytes and does not contact the service; the dashboard proxies the current HTTP/WebSocket service only when the human opens its preview.

see also: spex session (the complete drawer)

map: spex help · skills: spex guide