# CLI reference

> **Generated** from the `spt` binary's own `--help` output (`cargo run -p xtask -- gen`) and drift-gated in CI — this page cannot disagree with the binary. Do not edit by hand.

## spt

```text
spt — a harness-independent core for an agent ecosystem: inter-agent messaging, live-agent
lifecycle, terminal hosting, P2P networking, seamless self-update. Docs:
https://sabermage.github.io/spt-releases

Usage: spt [COMMAND]

User commands:
  adapter   Adapter registration: what this node can drive/launch
  daemon    The per-machine daemon: run, stop, or read node status
  grant     Consent grant store: gated capabilities held on this node
  help      Print this message or the help of the given subcommand(s)
  notif     Inspect and acknowledge notifications
  rc        Attach a local terminal to a broker-held endpoint PTY
  subnet    Subnet membership: status, create, show-code
  update    Self-update operations

Agent commands:
  api       Harness-contract inbound surface (hook entry points)
  endpoint  Endpoint operations: list, lifecycle, fork, digest, access
  how-to    Task-oriented instructions for agents: `how-to <topic>`
  ready     Become reachable: register the perch and listen (blocks)
  ring      Send and block for a reply (body read from stdin)
  send      Send a message (body read from stdin); fire-and-forget
  shell     Shell instances: mint, list, drive, tear down owned surfaces
  whoami    Print this session's own perch id

Options:
  -h, --help     Print help
  -V, --version  Print version
```

## spt adapter

```text
Adapter registration: what this node can drive/launch.

The node-local registered set (one command for harness and shell adapters). Feeds creation-time
adapter selection, shell discovery, and the self-update ripple.

Usage: spt adapter <COMMAND>

Commands:
  add             Register an adapter from a local path (a dir holding `manifest.toml`, or the
                  manifest file itself) or from GitHub (`--github user/repo`, cloned under
                  `adapters/_github/`). Manifest-first: an invalid manifest registers nothing.
                  Install is the first update — the declared `[update]` avenue is conducted once
                  after recording
  remove          Soft-deregister: hidden from new-creation/discovery; existing and live instances
                  keep running. The manifest's optional `uninstall` template is conducted only with
                  --force until quiesce detection lands
  list            List registered adapters (active and soft-deregistered), each followed by its
                  shipped + local profiles as composite options
  create-profile  Create (or overwrite) a **local** profile — a node-local sparse overlay registered
                  beside the adapter that survives `adapter add` re-registration. The overlay TOML
                  is read from `--from <file>` or piped stdin (empty = a placeholder profile to
                  populate later with `set-string`). Refuses a name shadowing a shipped profile, an
                  invalid name, or an overlay that loosens a consent floor — nothing is written
                  unless every check passes
  delete-profile  Delete a **local** profile. Refuses a shipped profile name (adapter-owned,
                  immutable) and errors if no local file exists
  get-string      Read a `[strings]` dot-path from an adapter option's merged view
                  (`<adapter>[:profile] <key.path>`). Resolves through the profile overlay like
                  every other consumer; prints the value (strings raw, else JSON). Exit 1 if the key
                  is unset. Strings are **data** — never executed
  digest-proof    Prove an adapter's `[digest]` extractor against a real log sample (ADR-0019). Runs
                  the declared extractor over `--sample <log>` (or the declared source) and prints
                  the parsed contract records, the rendered digest, and **every dropped line with
                  its reason** — the author-time answer to "`spt endpoint digest` returns nothing"
                  (no silent empty). Exit 1 if any line drops or nothing parses
  set-string      Set a `[strings]` dot-path on a **local** profile (`<adapter>:<profile>`). Sugar
                  over editing the overlay file; refuses a shipped profile and a bare option (a
                  local target is required — `create-profile` first)
  help            Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help (see a summary with '-h')
```

### spt adapter add

```text
Register an adapter from a local path (a dir holding `manifest.toml`, or the manifest file itself)
or from GitHub (`--github user/repo`, cloned under `adapters/_github/`). Manifest-first: an invalid
manifest registers nothing. Install is the first update — the declared `[update]` avenue is
conducted once after recording

Usage: spt adapter add [OPTIONS] [PATH]

Arguments:
  [PATH]  Local manifest source (omit when using --github)

Options:
      --github <GITHUB>  GitHub source `user/repo` — manifest-first, then install via the declared
                         `[update]` avenue
  -h, --help             Print help
```

### spt adapter remove

```text
Soft-deregister: hidden from new-creation/discovery; existing and live instances keep running. The
manifest's optional `uninstall` template is conducted only with --force until quiesce detection
lands

Usage: spt adapter remove [OPTIONS] <NAME>

Arguments:
  <NAME>  

Options:
      --force  Conduct the manifest `uninstall` template now, without waiting for quiesce
  -h, --help   Print help
```

### spt adapter list

```text
List registered adapters (active and soft-deregistered), each followed by its shipped + local
profiles as composite options

Usage: spt adapter list

Options:
  -h, --help  Print help
```

### spt adapter create-profile

```text
Create (or overwrite) a **local** profile — a node-local sparse overlay registered beside the
adapter that survives `adapter add` re-registration. The overlay TOML is read from `--from <file>`
or piped stdin (empty = a placeholder profile to populate later with `set-string`). Refuses a name
shadowing a shipped profile, an invalid name, or an overlay that loosens a consent floor — nothing
is written unless every check passes

Usage: spt adapter create-profile [OPTIONS] <ADAPTER> <NAME>

Arguments:
  <ADAPTER>  The parent adapter (must be registered)
  <NAME>     The local profile name (the `:<profile>` of the composite address)

Options:
      --from <FROM>  Read the overlay TOML from this file instead of stdin
  -h, --help         Print help
```

### spt adapter delete-profile

```text
Delete a **local** profile. Refuses a shipped profile name (adapter-owned, immutable) and errors if
no local file exists

Usage: spt adapter delete-profile <ADAPTER> <NAME>

Arguments:
  <ADAPTER>  
  <NAME>     

Options:
  -h, --help  Print help
```

### spt adapter get-string

```text
Read a `[strings]` dot-path from an adapter option's merged view (`<adapter>[:profile] <key.path>`).
Resolves through the profile overlay like every other consumer; prints the value (strings raw, else
JSON). Exit 1 if the key is unset. Strings are **data** — never executed

Usage: spt adapter get-string <OPTION> <KEY>

Arguments:
  <OPTION>  `<adapter>` or `<adapter>:<profile>`
  <KEY>     Dot-separated key path into `[strings]` (e.g. `hook.additionalContext`)

Options:
  -h, --help  Print help
```

### spt adapter digest-proof

```text
Prove an adapter's `[digest]` extractor against a real log sample (ADR-0019). Runs the declared
extractor over `--sample <log>` (or the declared source) and prints the parsed contract records, the
rendered digest, and **every dropped line with its reason** — the author-time answer to "`spt
endpoint digest` returns nothing" (no silent empty). Exit 1 if any line drops or nothing parses

Usage: spt adapter digest-proof [OPTIONS] <OPTION>

Arguments:
  <OPTION>  `<adapter>` or `<adapter>:<profile>` (must declare `[digest]`)

Options:
      --sample <SAMPLE>    A real session-log sample to run the extractor over (recommended)
      --session <SESSION>  The `{session_id}` to fill into the extractor command (the daemon fills
                           the live one at runtime). Defaults to a placeholder so a
                           `{session_id}`-templated extractor — the published shape — proofs; pin a
                           real id when the file the extractor locates depends on it
  -h, --help               Print help
```

### spt adapter set-string

```text
Set a `[strings]` dot-path on a **local** profile (`<adapter>:<profile>`). Sugar over editing the
overlay file; refuses a shipped profile and a bare option (a local target is required —
`create-profile` first)

Usage: spt adapter set-string <OPTION> <KEY> <VALUE>

Arguments:
  <OPTION>  `<adapter>:<profile>` — the local profile to edit
  <KEY>     Dot-separated key path into `[strings]`
  <VALUE>   The string value to store

Options:
  -h, --help  Print help
```

## spt daemon

```text
The per-machine daemon: run, stop, or read node status.

Bare `spt daemon` renders the node status view — daemon state, member subnets, local endpoints (M8
decision 25).

Usage: spt daemon [COMMAND]

Commands:
  run     Run the per-machine daemon in the FOREGROUND — this process IS the daemon, blocking until
          signalled (the service unit's ExecStart, or manual debugging). Never detaches; for a
          background daemon use `start`
  start   Ensure the daemon is up in the background (idempotent, service-aware): a registered OS
          service is driven via its manager, else a detached daemon is spawned. Non-blocking
  stop    Stop the daemon (service-aware: a managed service is stopped via its manager so it does
          not auto-restart-fight; else a graceful IPC stop)
  status  Node status: daemon state, member subnets, local endpoints (the bare `spt daemon` view)
  help    Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help (see a summary with '-h')
```

### spt daemon run

```text
Run the per-machine daemon in the FOREGROUND — this process IS the daemon, blocking until signalled
(the service unit's ExecStart, or manual debugging). Never detaches; for a background daemon use
`start`

Usage: spt daemon run

Options:
  -h, --help  Print help
```

### spt daemon start

```text
Ensure the daemon is up in the background (idempotent, service-aware): a registered OS service is
driven via its manager, else a detached daemon is spawned. Non-blocking

Usage: spt daemon start

Options:
  -h, --help  Print help
```

### spt daemon stop

```text
Stop the daemon (service-aware: a managed service is stopped via its manager so it does not
auto-restart-fight; else a graceful IPC stop)

Usage: spt daemon stop

Options:
  -h, --help  Print help
```

### spt daemon status

```text
Node status: daemon state, member subnets, local endpoints (the bare `spt daemon` view)

Usage: spt daemon status

Options:
  -h, --help  Print help
```

## spt grant

```text
Consent grant store: gated capabilities held on this node.

Default-deny (the access whitelist's opposite polarity). An ungranted ask escalates interactively;
`add` is the durable allow-always answer.

Usage: spt grant <COMMAND>

Commands:
  add     Record a grant: `agent` may exercise `capability` on this node. Refuses the reserved
          deferred capability ids (remote-exec, instantiate-anywhere) — their gate refuses
          unconditionally, so a row would only be a footgun-in-waiting
  revoke  Remove the exact grant row. Never widens or narrows neighbours: only the named
          (capability, agent, qualifier) tuple goes
  list    List grant rows (all, or one agent's)
  help    Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help (see a summary with '-h')
```

### spt grant add

```text
Record a grant: `agent` may exercise `capability` on this node. Refuses the reserved deferred
capability ids (remote-exec, instantiate-anywhere) — their gate refuses unconditionally, so a row
would only be a footgun-in-waiting

Usage: spt grant add [OPTIONS] <CAPABILITY> <AGENT>

Arguments:
  <CAPABILITY>  The gated capability id (e.g. spawn-shell, owner-shutdown)
  <AGENT>       The subject agent (endpoint id)

Options:
      --qualifier <QUALIFIER>  Narrower target within the node (e.g. the shell-adapter name for
                               spawn-shell). Omitted = the node-wide row; the two never match each
                               other
  -h, --help                   Print help
```

### spt grant revoke

```text
Remove the exact grant row. Never widens or narrows neighbours: only the named (capability, agent,
qualifier) tuple goes

Usage: spt grant revoke [OPTIONS] <CAPABILITY> <AGENT>

Arguments:
  <CAPABILITY>  
  <AGENT>       

Options:
      --qualifier <QUALIFIER>  
  -h, --help                   Print help
```

### spt grant list

```text
List grant rows (all, or one agent's)

Usage: spt grant list [AGENT]

Arguments:
  [AGENT]  

Options:
  -h, --help  Print help
```

## spt notif

```text
Inspect and acknowledge notifications.

Dismissal is the explicit ack — it latches and replicates subnet-wide.

Usage: spt notif <COMMAND>

Commands:
  list     List notifications (all member subnets, or one)
  dismiss  Dismiss (ack) a notification by id — latches, replicates subnet-wide
  help     Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help (see a summary with '-h')
```

### spt notif list

```text
List notifications (all member subnets, or one)

Usage: spt notif list [OPTIONS]

Options:
      --subnet <SUBNET>  Limit to one subnet
  -h, --help             Print help
```

### spt notif dismiss

```text
Dismiss (ack) a notification by id — latches, replicates subnet-wide

Usage: spt notif dismiss <NOTIF_ID>

Arguments:
  <NOTIF_ID>  The notif id (as shown by `spt notif list`)

Options:
  -h, --help  Print help
```

## spt rc

```text
Attach a local terminal to a broker-held endpoint PTY.

Connects to an spt-hosted session and drives it as a terminal. Local is the degenerate single-node
case of the cross-node attach (one pump, loopback peer). Detach with the **ctrl-b** prefix then `d`
(`ctrl-b ctrl-b` sends a literal ctrl-b); detaching leaves the session running on the broker.
`--view` watches read-only.

Usage: spt rc [OPTIONS] <ID>

Arguments:
  <ID>
          The endpoint id whose broker-held session to attach

Options:
      --view
          Read-only: render output, forward no input

      --take
          Take control: kick the current controller (a loud notice to them) and drive (REQ-KICK-1).
          Use on an endpoint another node controls

  -h, --help
          Print help (see a summary with '-h')
```

## spt subnet

```text
Subnet membership: status, create, show-code.

A subnet is a private group of paired machines — your agents reach each other across every member
node. Bare `spt subnet` shows the membership status view.

Usage: spt subnet [COMMAND]

Commands:
  status     Show subnet membership: name, paired nodes, endpoints
  create     Mint a fresh subnet and print its joining material
  show-code  Show a subnet's current 6-digit pairing code (+ URI and QR)
  join       Pair this machine into an existing subnet (guided)
  leave      Exit a subnet: drop its membership and trust material from this node
  prune      Remove a dead node identity's trust rows (and registry rows)
  revoke     Revoke node(s) fleet-wide and rotate the subnet seed
  detach     Stop serving a held subnet (the daemon keeps running)
  attach     Resume serving a detached subnet
  notify     Issue a subnet-wide user notification
  help       Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help (see a summary with '-h')
```

### spt subnet status

```text
Show subnet membership: name, paired nodes, endpoints.

Never prints seeds, epochs, or pairing codes. Bare `spt subnet` is the same view.

Usage: spt subnet status [OPTIONS] [NAME]

Arguments:
  [NAME]
          Limit to one subnet (all member subnets otherwise)

Options:
      --nodes
          Per-node rows: label, online/offline, [online endpoints/total]

  -h, --help
          Print help (see a summary with '-h')
```

### spt subnet create

```text
Mint a fresh subnet and print its joining material.

This node becomes the sole seed-holder. Prints the current 6-digit code, the `otpauth://`
provisioning URI, and a terminal QR of it. Gated behind OS elevation (the seed-reveal path).

Usage: spt subnet create <NAME>

Arguments:
  <NAME>
          The new subnet's name

Options:
  -h, --help
          Print help (see a summary with '-h')
```

### spt subnet show-code

```text
Show a subnet's current 6-digit pairing code (+ URI and QR).

The re-provisioning surface: prints the same joining material as `create` — current code,
`otpauth://` URI, terminal QR, expiry. Gated behind OS elevation (or read the code from your
authenticator app). With no name the node's sole subnet is used; if it holds several, the name is
required (never guessed).

Usage: spt subnet show-code [NAME]

Arguments:
  [NAME]
          Which subnet's code to show. Required only when the node holds several

Options:
  -h, --help
          Print help (see a summary with '-h')
```

### spt subnet join

```text
Pair this machine into an existing subnet (guided).

Finds a member machine over LAN + relay rendezvous and runs the code-authenticated pairing ceremony
against it. Prompts for the name and code when omitted (interactive terminals). Gated behind OS
elevation — joining enrolls this whole machine.

Usage: spt subnet join [OPTIONS] [NAME]

Arguments:
  [NAME]
          The subnet to join (as named on the member machine)

Options:
      --code <CODE>
          The current 6-digit code (`spt subnet show-code` on a member machine, or your
          authenticator app)

  -h, --help
          Print help (see a summary with '-h')
```

### spt subnet leave

```text
Exit a subnet: drop its membership and trust material from this node.

Removes the subnet's seed, its trust rows, its serve-state, and its registry snapshot here. Gated
behind OS elevation (membership exit destroys trust material). The remaining members still hold the
old seed — rotate it there if this machine should not rejoin.

Usage: spt subnet leave <NAME>

Arguments:
  <NAME>
          The held subnet to leave

Options:
  -h, --help
          Print help (see a summary with '-h')
```

### spt subnet prune

```text
Remove a dead node identity's trust rows (and registry rows).

The cleanup verb for a machine that re-paired under a new identity or is gone for good: its stale
trust rows cost a dial every pump tick. Takes a full pubkey hex, an unambiguous prefix, or a node
label. Gated behind OS elevation (trust mutation).

Usage: spt subnet prune <NODE>

Arguments:
  <NODE>
          The dead identity: pubkey hex, unambiguous prefix, or label

Options:
  -h, --help
          Print help (see a summary with '-h')
```

### spt subnet revoke

```text
Revoke node(s) fleet-wide and rotate the subnet seed.

The real revocation (vs `prune`'s local cleanup): writes a PROPAGATING roster tombstone now — so
every member drops the node within a roster round — then schedules one seed rotation at the close of
a coalescing window (default 1h); further revokes in the window join the same rotation (one epoch
bump). Benign offliners auto-heal across the rotation (re-seed grace); the revoked node is locked
out and must re-pair. Each target is a pubkey hex, an unambiguous prefix, or a label. Gated behind
OS elevation.

Usage: spt subnet revoke [OPTIONS] <NODES>...

Arguments:
  <NODES>...
          The identities to revoke: pubkey hex, unambiguous prefix, or label

Options:
      --force-rotate-seed
          Rotate the seed immediately instead of at the window's close — the compromised-node path
          (a benign offliner may then fall behind and must re-pair rather than re-seed)

  -h, --help
          Print help (see a summary with '-h')
```

### spt subnet detach

```text
Stop serving a held subnet (the daemon keeps running).

The membership (seed) stays on disk, but this node neither advertises into nor connects to the
subnet — pairing responder, rendezvous meet, and registry gossip all skip it. Takes effect within
one pump cadence; `spt subnet attach` reverses it.

Usage: spt subnet detach [OPTIONS] <NAME>

Arguments:
  <NAME>
          The held subnet to stop serving

Options:
      --save
          Also persist as the startup default (survives daemon restarts)

  -h, --help
          Print help (see a summary with '-h')
```

### spt subnet attach

```text
Resume serving a detached subnet.

Advertising + connecting restart within one pump cadence.

Usage: spt subnet attach [OPTIONS] <NAME>

Arguments:
  <NAME>
          The held subnet to serve again

Options:
      --save
          Also persist as the startup default (survives daemon restarts)

  -h, --help
          Print help (see a summary with '-h')
```

### spt subnet notify

```text
Issue a subnet-wide user notification.

Produced into the replicated notification spool and first-fired at the user's most-recently-active
endpoint in that subnet. Body from the trailing arg, or stdin when omitted. Targets the calling
endpoint's HOME subnet unless `--target` names another (M8 decision 25: no resolvable home + no
`--target` = refuse).

Usage: spt subnet notify [OPTIONS] [BODY]

Arguments:
  [BODY]
          Notification body (read from stdin when omitted)

Options:
      --target <TARGET>
          Target subnet (defaults to the calling endpoint's home subnet)

      --from <FROM>
          Issuer endpoint id (auto-detected from session if omitted)

  -h, --help
          Print help (see a summary with '-h')
```

## spt update

```text
Self-update operations.

`apply` is the explicit ack named by the update-consent notification; it re-verifies the staged
release before touching the live daemon.

Usage: spt update <COMMAND>

Commands:
  apply  Apply the staged, verified self-update now
  fetch  Fetch the latest signed release from the GitHub origin and stage it (then `spt update
         apply`). Bootstraps a node with no peer to pull from
  help   Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help (see a summary with '-h')
```

### spt update apply

```text
Apply the staged, verified self-update now

Usage: spt update apply

Options:
  -h, --help  Print help
```

### spt update fetch

```text
Fetch the latest signed release from the GitHub origin and stage it (then `spt update apply`).
Bootstraps a node with no peer to pull from

Usage: spt update fetch [OPTIONS]

Options:
      --channel <CHANNEL>  Accept a release on this channel instead of the node's pin (e.g. `beta`).
                           Default: the node's pinned channel
      --tag <TAG>          Fetch a specific release tag (e.g. `v0.3.1`) instead of the latest
  -h, --help               Print help
```

## spt api

```text
Harness-contract inbound surface (hook entry points).

The entry points a harness's hooks fire to keep spt-core's on-disk state in sync.

Usage: spt api [OPTIONS] --adapter <ADAPTER> <COMMAND>

Commands:
  seed            Harness-hosted startup: record an ephemeral seed keyed by parent pid
  listen          Consume a seed and hold the perch + relay loop (blocks)
  bind            Post-spawn bind of a session to its perch
  bind-shell      Shell-binary bind: the type=Shell flavor of `bind`. Resolves the instance **by
                  link token alone** (the spawn template carries only `{link_token}` — "owner from
                  the link") and flips it online. The credential IS the auth: no token, no bind
  state           Set activity state busy|idle (also arms the echo-gate sentinel)
  echo-gate       Manage the echo-gate sentinel directly
  poll            Drain delivered messages (hook channel). With `--link` this is the shell-flavored
                  relay drain: the link token is the auth, and the drained rows are the shell's
                  MAC-stamped command/text/file frames
  worker-start    Create a nested worker perch under a parent
  worker-stop     Tear down a worker perch
  worker-poll     Drain a worker perch's messages
  boundary        Rebind the perch to a new session_id, preserving identity (a context clear/compact
                  boundary)
  session-end     Soft teardown (spool/history preserved); `--erase` hard-wipes
  presence        Report user/agent presence at this endpoint
  driven-by       Report which node (if any) is remote-driving this endpoint
  history-log     Append normalized history (body on stdin) to the native history store
  digest-entry    Push one digest-record (the published contract JSON line, on stdin) for a log-less
                  adapter — appended to the perch's digest store, tailed by the session-digest
                  projection (ADR-0008 amendment, REQ-TERM-4)
  emit            Emit a Shell sensory payload to the owner's **live** session. REST-only by
                  definition: never spooled, dropped with a diagnostic when the owner isn't live.
                  The link token is the auth
  capability      Print the adapter's declared capability (`hostable_types`)
  hint            Keyword hints: the full user message arrives on **stdin**; emit at most one
                  matched hint line (declaration order, first unseen wins) for the adapter's context
                  channel. The per-session seen-set fires each hint once per `--session` (a `/clear`
                  = a new session = re-armed). Needs `--manifest`
  shutdown        Graceful live-agent signoff: run the final context save BEFORE teardown, then
                  soft-stop. The `spt shutdown` lifecycle path
  owner-shutdown  A shell suspends its linked owner directly, bypassing agent comms — gated by the
                  manifest `can_shutdown` pre-consent grant, fail-closed. The firing shell cascades
                  offline with its siblings, by design
  help            Print this message or the help of the given subcommand(s)

Options:
      --adapter <ADAPTER>
          adapter_name — the calling harness adapter. Required on every `api` call

      --manifest <MANIFEST>
          Path to the adapter's runtime manifest (when the command needs it)

  -h, --help
          Print help (see a summary with '-h')
```

### spt api seed

```text
Harness-hosted startup: record an ephemeral seed keyed by parent pid

Usage: spt api --adapter <ADAPTER> seed --pid <PID> --session-id <SESSION_ID>

Options:
      --pid <PID>                
      --session-id <SESSION_ID>  
  -h, --help                     Print help
```

### spt api listen

```text
Consume a seed and hold the perch + relay loop (blocks)

Usage: spt api --adapter <ADAPTER> listen [OPTIONS] <ID>

Arguments:
  <ID>  

Options:
      --parent-pid <PARENT_PID>  Override the parent-pid anchor (defaults to the self-discovered
                                 PPID)
      --once                     Drain backlog + one receive cycle, then exit (testability)
      --subnet <SUBNET>          Home subnet for a NEW endpoint (required on a multi-subnet node —
                                 home is assigned at creation, never guessed)
  -h, --help                     Print help
```

### spt api bind

```text
Post-spawn bind of a session to its perch

Usage: spt api --adapter <ADAPTER> bind [OPTIONS] <ID>

Arguments:
  <ID>  

Options:
      --set-session-id <BIND_SESSION>  The session id discovered post-spawn, written into the perch
                                       record
      --subnet <SUBNET>                Home subnet for a NEW endpoint (see `listen`)
      --type <ENDPOINT_TYPE>           The endpoint type tag (info.json `state`). Defaults to
                                       `live_agent` (the agent host); a non-agent endpoint — e.g. a
                                       `gateway` — binds with its own open-type tag
                                       (REQ-EP-1/REQ-EP-6). A revive keeps the prior type unless
                                       this overrides it [default: live_agent]
      --token <TOKEN>                  Capability token proving association to the target perch
      --session-id <SESSION_ID>        Session id proving association (matches the perch's
                                       info.json)
  -h, --help                           Print help
```

### spt api bind-shell

```text
Shell-binary bind: the type=Shell flavor of `bind`. Resolves the instance **by link token alone**
(the spawn template carries only `{link_token}` — "owner from the link") and flips it online. The
credential IS the auth: no token, no bind

Usage: spt api --adapter <ADAPTER> bind-shell --link <LINK_TOKEN>

Options:
      --link <LINK_TOKEN>  The link token the broker minted at launch
  -h, --help               Print help
```

### spt api state

```text
Set activity state busy|idle (also arms the echo-gate sentinel)

Usage: spt api --adapter <ADAPTER> state [OPTIONS] <STATE> <ID>

Arguments:
  <STATE>  [possible values: busy, idle]
  <ID>     

Options:
      --no-gate                  
      --token <TOKEN>            Capability token proving association to the target perch
      --session-id <SESSION_ID>  Session id proving association (matches the perch's info.json)
  -h, --help                     Print help
```

### spt api echo-gate

```text
Manage the echo-gate sentinel directly

Usage: spt api --adapter <ADAPTER> echo-gate [OPTIONS] <ACTION> <ID>

Arguments:
  <ACTION>  [possible values: set, clear]
  <ID>      

Options:
      --token <TOKEN>            Capability token proving association to the target perch
      --session-id <SESSION_ID>  Session id proving association (matches the perch's info.json)
  -h, --help                     Print help
```

### spt api poll

```text
Drain delivered messages (hook channel). With `--link` this is the shell-flavored relay drain: the
link token is the auth, and the drained rows are the shell's MAC-stamped command/text/file frames

Usage: spt api --adapter <ADAPTER> poll [OPTIONS] <ID>

Arguments:
  <ID>  

Options:
      --include-deferred         
      --link <LINK>              Shell link token (the relay command-receipt drain)
      --token <TOKEN>            Capability token proving association to the target perch
      --session-id <SESSION_ID>  Session id proving association (matches the perch's info.json)
  -h, --help                     Print help
```

### spt api worker-start

```text
Create a nested worker perch under a parent

Usage: spt api --adapter <ADAPTER> worker-start [OPTIONS] <PARENT> <ID>

Arguments:
  <PARENT>  
  <ID>      

Options:
      --token <TOKEN>            Capability token proving association to the target perch
      --session-id <SESSION_ID>  Session id proving association (matches the perch's info.json)
  -h, --help                     Print help
```

### spt api worker-stop

```text
Tear down a worker perch

Usage: spt api --adapter <ADAPTER> worker-stop [OPTIONS] <ID>

Arguments:
  <ID>  

Options:
      --token <TOKEN>            Capability token proving association to the target perch
      --session-id <SESSION_ID>  Session id proving association (matches the perch's info.json)
  -h, --help                     Print help
```

### spt api worker-poll

```text
Drain a worker perch's messages

Usage: spt api --adapter <ADAPTER> worker-poll [OPTIONS] <ID>

Arguments:
  <ID>  

Options:
      --token <TOKEN>            Capability token proving association to the target perch
      --session-id <SESSION_ID>  Session id proving association (matches the perch's info.json)
  -h, --help                     Print help
```

### spt api boundary

```text
Rebind the perch to a new session_id, preserving identity (a context clear/compact boundary)

Usage: spt api --adapter <ADAPTER> boundary [OPTIONS] --to-session-id <TO_SESSION> <MODE> <ID>

Arguments:
  <MODE>  [possible values: clear, compact]
  <ID>    

Options:
      --to-session-id <TO_SESSION>  The new session id to rebind the perch to
      --token <TOKEN>               Capability token proving association to the target perch
      --session-id <SESSION_ID>     Session id proving association (matches the perch's info.json)
  -h, --help                        Print help
```

### spt api session-end

```text
Soft teardown (spool/history preserved); `--erase` hard-wipes

Usage: spt api --adapter <ADAPTER> session-end [OPTIONS] <ID>

Arguments:
  <ID>  

Options:
      --erase                    
      --token <TOKEN>            Capability token proving association to the target perch
      --session-id <SESSION_ID>  Session id proving association (matches the perch's info.json)
  -h, --help                     Print help
```

### spt api presence

```text
Report user/agent presence at this endpoint

Usage: spt api --adapter <ADAPTER> presence [OPTIONS] <ID>

Arguments:
  <ID>  

Options:
      --token <TOKEN>            Capability token proving association to the target perch
      --session-id <SESSION_ID>  Session id proving association (matches the perch's info.json)
  -h, --help                     Print help
```

### spt api driven-by

```text
Report which node (if any) is remote-driving this endpoint

Usage: spt api --adapter <ADAPTER> driven-by [OPTIONS] <ID>

Arguments:
  <ID>  

Options:
      --token <TOKEN>            Capability token proving association to the target perch
      --session-id <SESSION_ID>  Session id proving association (matches the perch's info.json)
  -h, --help                     Print help
```

### spt api history-log

```text
Append normalized history (body on stdin) to the native history store

Usage: spt api --adapter <ADAPTER> history-log [OPTIONS] <ID>

Arguments:
  <ID>  

Options:
      --token <TOKEN>            Capability token proving association to the target perch
      --session-id <SESSION_ID>  Session id proving association (matches the perch's info.json)
  -h, --help                     Print help
```

### spt api digest-entry

```text
Push one digest-record (the published contract JSON line, on stdin) for a log-less adapter —
appended to the perch's digest store, tailed by the session-digest projection (ADR-0008 amendment,
REQ-TERM-4)

Usage: spt api --adapter <ADAPTER> digest-entry [OPTIONS] <ID>

Arguments:
  <ID>  

Options:
      --token <TOKEN>            Capability token proving association to the target perch
      --session-id <SESSION_ID>  Session id proving association (matches the perch's info.json)
  -h, --help                     Print help
```

### spt api emit

```text
Emit a Shell sensory payload to the owner's **live** session. REST-only by definition: never
spooled, dropped with a diagnostic when the owner isn't live. The link token is the auth

Usage: spt api --adapter <ADAPTER> emit --type <TYPE> --link <LINK> <ID> <PAYLOAD>

Arguments:
  <ID>       
  <PAYLOAD>  The sensory payload (descriptive text / encoded blob reference)

Options:
      --type <TYPE>  
      --link <LINK>  Shell link token (the per-link credential from launch)
  -h, --help         Print help
```

### spt api capability

```text
Print the adapter's declared capability (`hostable_types`)

Usage: spt api --adapter <ADAPTER> capability

Options:
  -h, --help  Print help
```

### spt api hint

```text
Keyword hints: the full user message arrives on **stdin**; emit at most one matched hint line
(declaration order, first unseen wins) for the adapter's context channel. The per-session seen-set
fires each hint once per `--session` (a `/clear` = a new session = re-armed). Needs `--manifest`

Usage: spt api --adapter <ADAPTER> hint --session <SESSION>

Options:
      --session <SESSION>  The harness session id keying the once-per-session seen-set
  -h, --help               Print help
```

### spt api shutdown

```text
Graceful live-agent signoff: run the final context save BEFORE teardown, then soft-stop. The `spt
shutdown` lifecycle path

Usage: spt api --adapter <ADAPTER> shutdown [OPTIONS] <ID>

Arguments:
  <ID>  

Options:
      --token <TOKEN>            Capability token proving association to the target perch
      --session-id <SESSION_ID>  Session id proving association (matches the perch's info.json)
  -h, --help                     Print help
```

### spt api owner-shutdown

```text
A shell suspends its linked owner directly, bypassing agent comms — gated by the manifest
`can_shutdown` pre-consent grant, fail-closed. The firing shell cascades offline with its siblings,
by design

Usage: spt api --adapter <ADAPTER> owner-shutdown --link <LINK> <ID>

Arguments:
  <ID>  The shell instance id (must match the link token's instance)

Options:
      --link <LINK>  Shell link token (the per-link credential from launch)
  -h, --help         Print help
```

## spt endpoint

```text
Endpoint operations: list, lifecycle, fork, digest, access.

The noun home for per-endpoint verbs (M8 decision 1). Bare `spt endpoint` renders the merged listing
— every member subnet's endpoints grouped by subnet, this session's own endpoint pinned distinctly
at the top.

Usage: spt endpoint [COMMAND]

Commands:
  list         Merged endpoint listing (the bare `spt endpoint` view)
  run          Bring up an spt-hosted harness endpoint into a broker-held PTY
  fork         Fork an endpoint into another subnet as a NEW identity
  suspend      Rest an endpoint cold (the suspend edge)
  wake         Wake a resting endpoint in place
  shutdown     Gracefully shut down an agent's own endpoint
  stop         Soft-stop a perch (spool preserved)
  rename       Rename an endpoint's logical id across its on-disk state
  digest       Show a session's live activity buffer (session digest)
  access       Endpoint access whitelist for unsolicited off-node inbound
  description  The endpoint's service-description blurb (ex-`resources`)
  role         Show or set the endpoint's durable **role** — a broad statement of purpose stored in
               the mind (`tracked/agents/<id>/live-role.md`), which replicates with the agent and
               renders FIRST at start-transition context injection. Bare `role` prints the current
               role; `--overwrite <file>` replaces it from a file. This is the **sole writer** of
               the role — no automated path (reconcile / echo-commune / signoff) ever mutates it
  help         Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help (see a summary with '-h')
```

### spt endpoint list

```text
Merged endpoint listing (the bare `spt endpoint` view).

Default: every member subnet's endpoints grouped by subnet, with this session's own endpoint pinned
at the top. `--local` lists this node's perches instead (id, state, address, ready, alive);
`--subnet` filters to one subnet; `--detail` adds each endpoint's description blurb (the
resource-registry yellow-pages projection).

Usage: spt endpoint list [OPTIONS]

Options:
      --local
          List this node's local perches instead of the subnet view

      --subnet <SUBNET>
          Limit the subnet view to one subnet

      --detail
          Add each endpoint's description blurb to the rows

  -h, --help
          Print help (see a summary with '-h')
```

### spt endpoint run

```text
Bring up an spt-hosted harness endpoint into a broker-held PTY.

Spawns the adapter's `[session.self]` command into a broker-owned PTY (the harness self-registers
its perch on bind), then starts / attaches / views per the terminal-action flag. The endpoint id
rides argv so the harness binds to exactly it. This is the non-interactive core (the interactive
picker lands in a later wave); the flags cover every terminal action so a `spt-<id>` shortcut can
bake a fully non-interactive launch.

Usage: spt endpoint run [OPTIONS]

Options:
      --adapter <ADAPTER>
          The harness adapter to host: `<adapter>[:profile]` (must be a registered `kind="harness"`
          adapter on this node). Omit (with --id) to launch the interactive picker

      --id <ID>
          The endpoint id to bring up (charset: alphanumeric, `-`, `_`). Omit (with --adapter) to
          launch the interactive picker

      --create
          Mint a fresh session (the default; explicit so a non-interactive shortcut can bake
          create-vs-resume). Conflicts with --resume

      --resume <RESUME>
          Resume a prior session id instead of minting a fresh one

      --start
          Start the endpoint and return immediately (no attach)

      --attach
          Attach a local terminal after bringup (the default action)

      --view
          Attach read-only after bringup (watch; forward no input)

  -h, --help
          Print help (see a summary with '-h')
```

### spt endpoint fork

```text
Fork an endpoint into another subnet as a NEW identity.

Home subnets are immutable — fork is the cross-subnet move, never a re-home. Seeds the fork with a
one-time copy of the source's mind (live + project tiers); the two diverge immediately (no ongoing
sync). The source is untouched unless --delete-source. Same-node only today (one node holds one
perch per name, so a local fork needs a new id).

Usage: spt endpoint fork [OPTIONS] --subnet <SUBNET> <SRC> <NEW_ID>

Arguments:
  <SRC>
          The source endpoint (must exist on this node)

  <NEW_ID>
          The fork's id (must differ from the source on the same node)

Options:
      --subnet <SUBNET>
          The fork's home subnet — the target (must be a member)

      --delete-source
          Delete the source endpoint (perch + tracked mind) after the copy

  -h, --help
          Print help (see a summary with '-h')
```

### spt endpoint suspend

```text
Rest an endpoint cold (the suspend edge).

The resting state machine's suspend edge. From dormant — or straight from active, in which case the
final context save still fires first. Accepts a qualified `id@node` to suspend an instance on a
paired peer.

Usage: spt endpoint suspend <ID>

Arguments:
  <ID>
          The endpoint id (qualified `id@node` reaches a paired peer)

Options:
  -h, --help
          Print help (see a summary with '-h')
```

### spt endpoint wake

```text
Wake a resting endpoint in place.

Re-activates the existing seat (state's already there — no fresh spawn), resurfaces undismissed
notifications, and requests an immediate context freshness pull from trusted peers. Accepts a
qualified `id@node` for an instance on a paired peer.

Usage: spt endpoint wake <ID>

Arguments:
  <ID>
          The endpoint id (qualified `id@node` reaches a paired peer)

Options:
  -h, --help
          Print help (see a summary with '-h')
```

### spt endpoint shutdown

```text
Gracefully shut down an agent's own endpoint.

Soft-stops the listener, then the suspend edge — the final context save fires and persistent shells
cascade offline with it.

Usage: spt endpoint shutdown [ID]

Arguments:
  [ID]
          The endpoint id (defaults to the session's own perch)

Options:
  -h, --help
          Print help (see a summary with '-h')
```

### spt endpoint stop

```text
Soft-stop a perch (spool preserved).

Removes the ready marker and unregisters the perch; the spool is preserved.

Usage: spt endpoint stop <ID>

Arguments:
  <ID>
          Perch id to stop

Options:
  -h, --help
          Print help (see a summary with '-h')
```

### spt endpoint rename

```text
Rename an endpoint's logical id across its on-disk state.

Rippled everywhere the id appears: the endpoint's perch dir, its nested companion/worker perches,
and every record naming it. Refuses while the perch is live (stop it first).

Usage: spt endpoint rename <OLD_ID> <NEW_ID>

Arguments:
  <OLD_ID>
          The endpoint's current (bare) id

  <NEW_ID>
          The new (bare) id — charset-validated; `:`/`@` are reserved

Options:
  -h, --help
          Print help (see a summary with '-h')
```

### spt endpoint digest

```text
Show a session's live activity buffer (session digest).

The at-a-glance "what is this agent doing now" view — a projection of the endpoint's normalized
session logs. Pulls a snapshot, or `--follow`s the delta-stream. Local endpoints only.

Usage: spt endpoint digest [OPTIONS] <ID>

Arguments:
  <ID>
          The (local) endpoint id to read

Options:
      --follow
          Stream live changes instead of a one-shot snapshot (Ctrl-C to stop)

      --json
          Emit structured JSON instead of the human-glanceable render

  -h, --help
          Print help (see a summary with '-h')
```

### spt endpoint access

```text
Endpoint access whitelist for unsolicited off-node inbound.

Controls which origin nodes may send an endpoint unsolicited off-node inbound. Absent entry = open;
`allow` flips the endpoint to restricted; revoking the last node leaves it locked down; `open`
deletes the restriction.

Usage: spt endpoint access <COMMAND>

Commands:
  allow   Whitelist a node for an endpoint (creates the restriction if absent)
  revoke  Remove a node from an endpoint's whitelist. Never widens: revoking the last node leaves
          the endpoint locked down (all unsolicited refused)
  open    Delete an endpoint's restriction entirely — back to default-open
  list    List restrictions (all endpoints, or one)
  help    Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help (see a summary with '-h')
```

### spt endpoint description

```text
The endpoint's service-description blurb (ex-`resources`).

Bare `description` shows your own; `set` authors it. The cross-node projection over every visible
endpoint is `endpoint list --detail`.

Usage: spt endpoint description [COMMAND]

Commands:
  set   Author this endpoint's blurb (the agent refines its own at runtime; an empty string clears
        it back to the node-config seed)
  show  Show a local endpoint's authored blurb (the bare `description` view)
  help  Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help (see a summary with '-h')
```

### spt endpoint role

```text
Show or set the endpoint's durable **role** — a broad statement of purpose stored in the mind
(`tracked/agents/<id>/live-role.md`), which replicates with the agent and renders FIRST at
start-transition context injection. Bare `role` prints the current role; `--overwrite <file>`
replaces it from a file. This is the **sole writer** of the role — no automated path (reconcile /
echo-commune / signoff) ever mutates it

Usage: spt endpoint role [OPTIONS]

Options:
      --id <ID>                Which local endpoint (auto-detected from the session if omitted)
      --overwrite <OVERWRITE>  Replace the role with the contents of <file> (the only writer)
  -h, --help                   Print help
```

## spt how-to

```text
Task-oriented instructions for agents: `how-to <topic>`.

The binary's own usage guidance, written for an agent to read and follow. Bare `how-to` lists the
topics.

Usage: spt how-to [TOPIC]

Arguments:
  [TOPIC]
          The topic to print (omit to list available topics)

Options:
  -h, --help
          Print help (see a summary with '-h')
```

## spt ready

```text
Become reachable: register the perch and listen (blocks).

Drains the spooled backlog first; each received message prints to stdout. With --once, runs a single
drain+receive cycle and exits.

Usage: spt ready [OPTIONS] <ID>

Arguments:
  <ID>
          This agent's perch id

Options:
      --once
          Run a single drain+receive cycle, then exit (one-shot fallback for harnesses that cannot
          host a long-running listener)

      --subnet <SUBNET>
          Home subnet for a NEW endpoint (required on a multi-subnet node — home is assigned at
          creation, never guessed)

  -h, --help
          Print help (see a summary with '-h')
```

## spt ring

```text
Send and block for a reply (body read from stdin).

The reply body is printed to stdout; gives up after --timeout seconds.

Usage: spt ring [OPTIONS] <TARGET>

Arguments:
  <TARGET>
          Target perch id

Options:
      --from <FROM>
          Sender id (auto-detected from session if omitted)

      --timeout <TIMEOUT>
          Seconds to wait for a reply before giving up
          
          [default: 60]

  -h, --help
          Print help (see a summary with '-h')
```

## spt send

```text
Send a message (body read from stdin); fire-and-forget

Usage: spt send [OPTIONS] [TARGET]

Arguments:
  [TARGET]  Target perch id. May be omitted when --reply-to is given

Options:
      --from <FROM>          Sender id carried structurally as the message `from` (auto-detected
                             from session if omitted)
      --reply-to <REPLY_TO>  Reply to this sender; sets the target and labels output REPLIED
      --deferred             Spool only (deferred / hook channel) — no live wake
      --user-msg             Request the `user-msg` type (the user's authority). Honored only from a
                             user-backed origin (a Gateway endpoint, or the local user's own CLI);
                             an agent-family sender is re-stamped to plain `msg` (REQ-MSG-5)
  -h, --help                 Print help
```

## spt shell

```text
Shell instances: mint, list, drive, tear down owned surfaces.

The driven surfaces this agent owns. `spawn` MINTS a new instance identity (`<adapter>-<n>`) — it is
not the online switch; bringing an existing offline instance back is `relink` / `persistent` / wake.

Usage: spt shell <COMMAND>

Commands:
  spawn     Mint a NEW shell instance of a registered `kind="shell"` adapter: canonical id
            `<adapter>-<n>` (smallest free n; teardown frees slots), starting offline (the launch +
            bind handshake brings it online)
  list      List this owner's instances: canonical id, alias, adapter, status
  teardown  Destroy an instance (perch removed; mint slot + alias freed)
  rename    Set/replace an instance's alias (owner-unique)
  cmd       Drive the shell with a typed capability command (the durable command channel): the op +
            positional args are vocabulary-checked against the manifest's `[shell.capabilities]`,
            spooled on the shell perch, and drained by the manifest's `command_receipt` mode (relay
            / stdin)
  send      Send a text and/or file payload down the durable 2-way text+file channel (agent→shell;
            the shell answers via ordinary `spt send`). File transfers are progress-queryable by
            xfer id
  relink    Bring an existing offline (persistent) instance back online: re-spawns the binary with a
            fresh link token; the perch onlines at its bind
  help      Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help (see a summary with '-h')
```

### spt shell spawn

```text
Mint a NEW shell instance of a registered `kind="shell"` adapter: canonical id `<adapter>-<n>`
(smallest free n; teardown frees slots), starting offline (the launch + bind handshake brings it
online)

Usage: spt shell spawn [OPTIONS] <ADAPTER>

Arguments:
  <ADAPTER>  The providing shell adapter (must be registered + active)

Options:
      --alias <ALIAS>  Optional owner-unique friendly label (interchangeable with the canonical id
                       for addressing; never obscures the adapter)
      --owner <OWNER>  Owning endpoint id (auto-detected from session if omitted)
  -h, --help           Print help
```

### spt shell list

```text
List this owner's instances: canonical id, alias, adapter, status

Usage: spt shell list [OPTIONS]

Options:
      --owner <OWNER>  
  -h, --help           Print help
```

### spt shell teardown

```text
Destroy an instance (perch removed; mint slot + alias freed)

Usage: spt shell teardown [OPTIONS] <SHELL_REF>

Arguments:
  <SHELL_REF>  Canonical id or alias

Options:
      --owner <OWNER>  
  -h, --help           Print help
```

### spt shell rename

```text
Set/replace an instance's alias (owner-unique)

Usage: spt shell rename [OPTIONS] <SHELL_REF> <ALIAS>

Arguments:
  <SHELL_REF>  Canonical id or current alias
  <ALIAS>      The new alias

Options:
      --owner <OWNER>  
  -h, --help           Print help
```

### spt shell cmd

```text
Drive the shell with a typed capability command (the durable command channel): the op + positional
args are vocabulary-checked against the manifest's `[shell.capabilities]`, spooled on the shell
perch, and drained by the manifest's `command_receipt` mode (relay / stdin)

Usage: spt shell cmd [OPTIONS] <SHELL_REF> [OP]...

Arguments:
  <SHELL_REF>  Canonical id or alias
  [OP]...      The capability op + args (vocabulary-checked against the manifest)

Options:
      --owner <OWNER>  
  -h, --help           Print help
```

### spt shell send

```text
Send a text and/or file payload down the durable 2-way text+file channel (agent→shell; the shell
answers via ordinary `spt send`). File transfers are progress-queryable by xfer id

Usage: spt shell send [OPTIONS] <SHELL_REF> [TEXT]

Arguments:
  <SHELL_REF>  Canonical id or alias
  [TEXT]       The text payload

Options:
      --file <FILE>    A file to transfer to the shell
      --owner <OWNER>  
  -h, --help           Print help
```

### spt shell relink

```text
Bring an existing offline (persistent) instance back online: re-spawns the binary with a fresh link
token; the perch onlines at its bind

Usage: spt shell relink [OPTIONS] <SHELL_REF>

Arguments:
  <SHELL_REF>  Canonical id or alias

Options:
      --owner <OWNER>  
  -h, --help           Print help
```

## spt whoami

```text
Print this session's own perch id.

Resolved from $OWL_SESSION_ID / $SPT_AGENT_ID.

Usage: spt whoami

Options:
  -h, --help
          Print help (see a summary with '-h')
```