---
meta-description: spt-core: a harness-independent core for an agent ecosystem — messaging, live-agent lifecycle, terminal hosting, P2P networking, and the runtime-manifest harness contract.
meta-theme-color: #ffffff
meta-viewport: width=device-width, initial-scale=1
title: CLI reference - SPT developer docs
---

## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

![SVG Image](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0NDggNTEyIj48cGF0aCBkPSJNMCA5NkMwIDc4LjMgMTQuMyA2NCAzMiA2NEg0MTZjMTcuNyAwIDMyIDE0LjMgMzIgMzJzLTE0LjMgMzItMzIgMzJIMzJDMTQuMyAxMjggMCAxMTMuNyAwIDk2ek0wIDI1NmMwLTE3LjcgMTQuMy0zMiAzMi0zMkg0MTZjMTcuNyAwIDMyIDE0LjMgMzIgMzJzLTE0LjMgMzItMzIgMzJIMzJjLTE3LjcgMC0zMi0xNC4zLTMyLTMyek00NDggNDE2YzAgMTcuNy0xNC4zIDMyLTMyIDMySDMyYy0xNy43IDAtMzItMTQuMy0zMi0zMnMxNC4zLTMyIDMyLTMySDQxNmMxNy43IDAgMzIgMTQuMyAzMiAzMnoiIC8+PC9zdmc+)

![SVG Image](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA1NzYgNTEyIj48cGF0aCBkPSJNMzcxLjMgMzY3LjFjMjcuMy0zLjkgNTEuOS0xOS40IDY3LjItNDIuOUw2MDAuMiA3NC4xYzEyLjYtMTkuNSA5LjQtNDUuMy03LjYtNjEuMlM1NDkuNy00LjQgNTMxLjEgOS42TDI5NC40IDE4Ny4yYy0yNCAxOC0zOC4yIDQ2LjEtMzguNCA3Ni4xTDM3MS4zIDM2Ny4xem0tMTkuNiAyNS40bC0xMTYtMTA0LjRDMTc1LjkgMjkwLjMgMTI4IDMzOS42IDEyOCA0MDBjMCAzLjkgLjIgNy44IC42IDExLjZjMS44IDE3LjUtMTAuMiAzNi40LTI3LjggMzYuNEg5NmMtMTcuNyAwLTMyIDE0LjMtMzIgMzJzMTQuMyAzMiAzMiAzMkgyNDBjNjEuOSAwIDExMi01MC4xIDExMi0xMTJjMC0yLjUtLjEtNS0uMi03LjV6IiAvPjwvc3ZnPg==)

- Auto

- Light

- Rust

- Coal

- Navy

- Ayu

![SVG Image](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA1MTIgNTEyIj48cGF0aCBkPSJNNDE2IDIwOGMwIDQ1LjktMTQuOSA4OC4zLTQwIDEyMi43TDUwMi42IDQ1Ny40YzEyLjUgMTIuNSAxMi41IDMyLjggMCA0NS4zcy0zMi44IDEyLjUtNDUuMyAwTDMzMC43IDM3NmMtMzQuNCAyNS4yLTc2LjggNDAtMTIyLjcgNDBDOTMuMSA0MTYgMCAzMjIuOSAwIDIwOFM5My4xIDAgMjA4IDBTNDE2IDkzLjEgNDE2IDIwOHpNMjA4IDM1MmM3OS41IDAgMTQ0LTY0LjUgMTQ0LTE0NHMtNjQuNS0xNDQtMTQ0LTE0NFM2NCAxMjguNSA2NCAyMDhzNjQuNSAxNDQgMTQ0IDE0NHoiIC8+PC9zdmc+)

# SPT developer docs

[![SVG Image](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA1MTIgNTEyIj48cGF0aCBkPSJNMTI4IDBDOTIuNyAwIDY0IDI4LjcgNjQgNjR2OTZoNjRWNjRIMzU0LjdMMzg0IDkzLjNWMTYwaDY0VjkzLjNjMC0xNy02LjctMzMuMy0xOC43LTQ1LjNMNDAwIDE4LjdDMzg4IDYuNyAzNzEuNyAwIDM1NC43IDBIMTI4ek0zODQgMzUydjMyIDY0SDEyOFYzODQgMzY4IDM1MkgzODR6bTY0IDMyaDMyYzE3LjcgMCAzMi0xNC4zIDMyLTMyVjI1NmMwLTM1LjMtMjguNy02NC02NC02NEg2NGMtMzUuMyAwLTY0IDI4LjctNjQgNjR2OTZjMCAxNy43IDE0LjMgMzIgMzIgMzJINjR2NjRjMCAzNS4zIDI4LjcgNjQgNjQgNjRIMzg0YzM1LjMgMCA2NC0yOC43IDY0LTY0VjM4NHptLTE2LTg4Yy0xMy4zIDAtMjQtMTAuNy0yNC0yNHMxMC43LTI0IDI0LTI0czI0IDEwLjcgMjQgMjRzLTEwLjcgMjQtMjQgMjR6IiAvPjwvc3ZnPg==)](../print.html "Print this book") [![SVG Image](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0OTYgNTEyIj48cGF0aCBkPSJNMTY1LjkgMzk3LjRjMCAyLTIuMyAzLjYtNS4yIDMuNi0zLjMuMy01LjYtMS4zLTUuNi0zLjYgMC0yIDIuMy0zLjYgNS4yLTMuNiAzLS4zIDUuNiAxLjMgNS42IDMuNnptLTMxLjEtNC41Yy0uNyAyIDEuMyA0LjMgNC4zIDQuOSAyLjYgMSA1LjYgMCA2LjItMnMtMS4zLTQuMy00LjMtNS4yYy0yLjYtLjctNS41LjMtNi4yIDIuM3ptNDQuMi0xLjdjLTIuOS43LTQuOSAyLjYtNC42IDQuOS4zIDIgMi45IDMuMyA1LjkgMi42IDIuOS0uNyA0LjktMi42IDQuNi00LjYtLjMtMS45LTMtMy4yLTUuOS0yLjl6TTI0NC44IDhDMTA2LjEgOCAwIDExMy4zIDAgMjUyYzAgMTEwLjkgNjkuOCAyMDUuOCAxNjkuNSAyMzkuMiAxMi44IDIuMyAxNy4zLTUuNiAxNy4zLTEyLjEgMC02LjItLjMtNDAuNC0uMy02MS40IDAgMC03MCAxNS04NC43LTI5LjggMCAwLTExLjQtMjkuMS0yNy44LTM2LjYgMCAwLTIyLjktMTUuNyAxLjYtMTUuNCAwIDAgMjQuOSAyIDM4LjYgMjUuOCAyMS45IDM4LjYgNTguNiAyNy41IDcyLjkgMjAuOSAyLjMtMTYgOC44LTI3LjEgMTYtMzMuNy01NS45LTYuMi0xMTIuMy0xNC4zLTExMi4zLTExMC41IDAtMjcuNSA3LjYtNDEuMyAyMy42LTU4LjktMi42LTYuNS0xMS4xLTMzLjMgMi42LTY3LjkgMjAuOS02LjUgNjkgMjcgNjkgMjcgMjAtNS42IDQxLjUtOC41IDYyLjgtOC41czQyLjggMi45IDYyLjggOC41YzAgMCA0OC4xLTMzLjYgNjktMjcgMTMuNyAzNC43IDUuMiA2MS40IDIuNiA2Ny45IDE2IDE3LjcgMjUuOCAzMS41IDI1LjggNTguOSAwIDk2LjUtNTguOSAxMDQuMi0xMTQuOCAxMTAuNSA5LjIgNy45IDE3IDIyLjkgMTcgNDYuNCAwIDMzLjctLjMgNzUuNC0uMyA4My42IDAgNi41IDQuNiAxNC40IDE3LjMgMTIuMUM0MjguMiA0NTcuOCA0OTYgMzYyLjkgNDk2IDI1MiA0OTYgMTEzLjMgMzgzLjUgOCAyNDQuOCA4ek05Ny4yIDM1Mi45Yy0xLjMgMS0xIDMuMy43IDUuMiAxLjYgMS42IDMuOSAyLjMgNS4yIDEgMS4zLTEgMS0zLjMtLjctNS4yLTEuNi0xLjYtMy45LTIuMy01LjItMXptLTEwLjgtOC4xYy0uNyAxLjMuMyAyLjkgMi4zIDMuOSAxLjYgMSAzLjYuNyA0LjMtLjcuNy0xLjMtLjMtMi45LTIuMy0zLjktMi0uNi0zLjYtLjMtNC4zLjd6bTMyLjQgMzUuNmMtMS42IDEuMy0xIDQuMyAxLjMgNi4yIDIuMyAyLjMgNS4yIDIuNiA2LjUgMSAxLjMtMS4zLjctNC4zLTEuMy02LjItMi4yLTIuMy01LjItMi42LTYuNS0xem0tMTEuNC0xNC43Yy0xLjYgMS0xLjYgMy42IDAgNS45IDEuNiAyLjMgNC4zIDMuMyA1LjYgMi4zIDEuNi0xLjMgMS42LTMuOSAwLTYuMi0xLjQtMi4zLTQtMy4zLTUuNi0yeiIgLz48L3N2Zz4=)](https://github.com/SaberMage/spt-releases "Git repository")

![SVG Image](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA1MTIgNTEyIj48cGF0aCBkPSJNMzA0IDQ4YzAtMjYuNS0yMS41LTQ4LTQ4LTQ4cy00OCAyMS41LTQ4IDQ4czIxLjUgNDggNDggNDhzNDgtMjEuNSA0OC00OHptMCA0MTZjMC0yNi41LTIxLjUtNDgtNDgtNDhzLTQ4IDIxLjUtNDggNDhzMjEuNSA0OCA0OCA0OHM0OC0yMS41IDQ4LTQ4ek00OCAzMDRjMjYuNSAwIDQ4LTIxLjUgNDgtNDhzLTIxLjUtNDgtNDgtNDhzLTQ4IDIxLjUtNDggNDhzMjEuNSA0OCA0OCA0OHptNDY0LTQ4YzAtMjYuNS0yMS41LTQ4LTQ4LTQ4cy00OCAyMS41LTQ4IDQ4czIxLjUgNDggNDggNDhzNDgtMjEuNSA0OC00OHpNMTQyLjkgNDM3YzE4LjctMTguNyAxOC43LTQ5LjEgMC02Ny45cy00OS4xLTE4LjctNjcuOSAwcy0xOC43IDQ5LjEgMCA2Ny45czQ5LjEgMTguNyA2Ny45IDB6bTAtMjk0LjJjMTguNy0xOC43IDE4LjctNDkuMSAwLTY3LjlTOTMuNyA1Ni4yIDc1IDc1cy0xOC43IDQ5LjEgMCA2Ny45czQ5LjEgMTguNyA2Ny45IDB6TTM2OS4xIDQzN2MxOC43IDE4LjcgNDkuMSAxOC43IDY3LjkgMHMxOC43LTQ5LjEgMC02Ny45cy00OS4xLTE4LjctNjcuOSAwcy0xOC43IDQ5LjEgMCA2Ny45eiIgLz48L3N2Zz4=)

# [CLI reference](#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](#spt)

    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 [OPTIONS] [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:
          --json     Emit machine-readable JSON instead of the human view. Honored by the read/status
                     commands (list, whoami, status, description, role, the *-list queries, how-to);
                     action commands ignore it
      -h, --help     Print help
      -V, --version  Print version

## [spt adapter](#spt-adapter)

    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 [OPTIONS] <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
      version          Print a registered adapter's declared version — the [adapter].version from its
                       manifest. Resolves the option's merged view like the other adapter commands; exit
                       1 if the adapter is not registered
      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. 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
      translate-proof  Prove an adapter's [message-idle-translation-binary] against an inbound event.
                       Spawns and feeds the declared translation binary exactly as the daemon does at
                       idle-delivery — sends the init line then the --event envelope and reads back
                       the emitted keystroke-command stream ({key}/{text}/{delay_ms}/{commit}),
                       printed author-readable. This is the EMIT half ONLY: it proves the binary's
                       spawn-feed-emit contract; it does NOT exercise the daemon's atomic PTY apply or
                       controller buffering. Fills {id} and {session_id} into the envelope the same
                       way the daemon does (use --session to pin the session id). Exit 1 if the binary
                       fails to spawn, emits nothing, emits no commit, or emits an unparseable line
      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)
      update           Update registered adapters that ship from their own GitHub releases: compare each
                       [update] avenue = "gh_release" adapter's latest release version against the
                       installed one and, when newer, fetch the release archive, verify it against the
                       declared signing key if any (else trusting HTTPS + GitHub), and re-register. With
                       no name, sweeps every gh_release adapter; with a name, updates just that one
      use              Set or clear the active-profile pointer — the default <adapter>[:profile] a
                       harness session binds to when no --adapter is given. spt adapter use
                       <adapter>[:profile] points every host binary the adapter declares at it (run
                       once per host binary you support); --clear <adapter|binary> drops the pointer
                       (resolution falls back to the freshest-registered adapter). Never changed by
                       install or update
      help             Print this message or the help of the given subcommand(s)

    Options:
          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

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

### [spt adapter add](#spt-adapter-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

    Usage: spt adapter add [OPTIONS] [PATH]

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

    Options:
          --github <GITHUB>    GitHub source user/repo — shallow-clone the repo and register the clone
                               root. Manifest-first, then install via the declared [update] avenue
          --json               Emit machine-readable JSON instead of the human view. Honored by the
                               read/status commands (list, whoami, status, description, role, the *-list
                               queries, how-to); action commands ignore it
          --release <RELEASE>  GitHub release source user/repo — fetch the adapter archive asset from
                               the release and register it: ships built binaries, source-free and
                               versioned (the pattern for a monorepo whose adapter is a subdir)
          --tag <TAG>          Release tag for --release (default: the latest release)
          --asset <ASSET>      Release asset name for --release (default: adapter.spt — a tar archive
                               whose root holds manifest.toml + strings/ + binaries)
          --gh                 Force the gh CLI transport for --release (the private-repo path; gh
                               honors OAuth + GH_TOKEN, so spt custodies no token). Mutually exclusive
                               with --https. Default: auto (gh when installed+authed, else HTTPS)
          --https              Force direct HTTPS transport for --release (public repos). Mutually
                               exclusive with --gh. Default: auto
      -h, --help               Print help

### [spt adapter remove](#spt-adapter-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

    Usage: spt adapter remove [OPTIONS] <NAME>

    Arguments:
      <NAME>  

    Options:
          --force  Conduct the manifest uninstall template now, without waiting for quiesce
          --json   Emit machine-readable JSON instead of the human view. Honored by the read/status
                   commands (list, whoami, status, description, role, the *-list queries, how-to);
                   action commands ignore it
      -h, --help   Print help

### [spt adapter list](#spt-adapter-list)

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

    Usage: spt adapter list [OPTIONS]

    Options:
          --json  Emit machine-readable JSON instead of the human view. Honored by the read/status
                  commands (list, whoami, status, description, role, the *-list queries, how-to); action
                  commands ignore it
      -h, --help  Print help

### [spt adapter version](#spt-adapter-version)

    Print a registered adapter's declared version — the [adapter].version from its manifest. Resolves
    the option's merged view like the other adapter commands; exit 1 if the adapter is not registered

    Usage: spt adapter version [OPTIONS] <OPTION>

    Arguments:
      <OPTION>  <adapter> or <adapter>:<profile>

    Options:
          --json  Emit machine-readable JSON instead of the human view. Honored by the read/status
                  commands (list, whoami, status, description, role, the *-list queries, how-to); action
                  commands ignore it
      -h, --help  Print help

### [spt adapter create-profile](#spt-adapter-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

    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
          --json         Emit machine-readable JSON instead of the human view. Honored by the
                         read/status commands (list, whoami, status, description, role, the *-list
                         queries, how-to); action commands ignore it
      -h, --help         Print help

### [spt adapter delete-profile](#spt-adapter-delete-profile)

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

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

    Arguments:
      <ADAPTER>  
      <NAME>  

    Options:
          --json  Emit machine-readable JSON instead of the human view. Honored by the read/status
                  commands (list, whoami, status, description, role, the *-list queries, how-to); action
                  commands ignore it
      -h, --help  Print help

### [spt adapter get-string](#spt-adapter-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

    Usage: spt adapter get-string [OPTIONS] <OPTION> <KEY>

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

    Options:
          --json  Emit machine-readable JSON instead of the human view. Honored by the read/status
                  commands (list, whoami, status, description, role, the *-list queries, how-to); action
                  commands ignore it
      -h, --help  Print help

### [spt adapter digest-proof](#spt-adapter-digest-proof)

    Prove an adapter's [digest] extractor against a real log sample. 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:
          --json                 Emit machine-readable JSON instead of the human view. Honored by the
                                 read/status commands (list, whoami, status, description, role, the
                                 *-list queries, how-to); action commands ignore it
          --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
          --dir <DIR>            Proof against an on-disk install dir instead of the registered
                                 adapter: binaries resolve in this dir before PATH (the same resolution
                                 the daemon uses) and the manifest defaults to <dir>/manifest.toml. No
                                 full extracted install needed — proof a DEV binary from its build dir
          --manifest <MANIFEST>  Pin the manifest file for the proof (overrides
                                 <dir>/manifest.toml; absent --dir, its parent dir is the install
                                 dir). Lets a bare-file gh_release adapter proof without staging an
                                 extracted install
      -h, --help                 Print help

### [spt adapter translate-proof](#spt-adapter-translate-proof)

    Prove an adapter's [message-idle-translation-binary] against an inbound event. Spawns and feeds
    the declared translation binary exactly as the daemon does at idle-delivery — sends the init line
    then the --event envelope and reads back the emitted keystroke-command stream
    ({key}/{text}/{delay_ms}/{commit}), printed author-readable. This is the EMIT half ONLY: it
    proves the binary's spawn-feed-emit contract; it does NOT exercise the daemon's atomic PTY apply or
    controller buffering. Fills {id} and {session_id} into the envelope the same way the daemon does
    (use --session to pin the session id). Exit 1 if the binary fails to spawn, emits nothing, emits
    no commit, or emits an unparseable line

    Usage: spt adapter translate-proof [OPTIONS] --event <EVENT> <OPTION>

    Arguments:
      <OPTION>  <adapter> or <adapter>:<profile> (must declare [message-idle-translation-binary])

    Options:
          --event <EVENT>        The inbound <EVENT…> envelope to feed. {id} and {session_id}
                                 tokens in it are filled as the daemon fills them
          --json                 Emit machine-readable JSON instead of the human view. Honored by the
                                 read/status commands (list, whoami, status, description, role, the
                                 *-list queries, how-to); action commands ignore it
          --session <SESSION>    The {session_id} to fill into the event envelope (the daemon fills
                                 the live one at runtime). Defaults to a placeholder; pin a real id when
                                 the binary's behavior depends on it
          --dir <DIR>            Proof against an on-disk install dir instead of the registered
                                 adapter: the translation binary resolves in this dir before PATH (the
                                 same resolution the daemon uses) and the manifest defaults to
                                 <dir>/manifest.toml. No full extracted install needed — proof a DEV
                                 binary from its build dir
          --manifest <MANIFEST>  Pin the manifest file for the proof (overrides
                                 <dir>/manifest.toml; absent --dir, its parent dir is the install
                                 dir). Lets a bare-file gh_release adapter proof without staging an
                                 extracted install
      -h, --help                 Print help

### [spt adapter set-string](#spt-adapter-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)

    Usage: spt adapter set-string [OPTIONS] <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:
          --json  Emit machine-readable JSON instead of the human view. Honored by the read/status
                  commands (list, whoami, status, description, role, the *-list queries, how-to); action
                  commands ignore it
      -h, --help  Print help

### [spt adapter update](#spt-adapter-update)

    Update registered adapters that ship from their own GitHub releases: compare each `[update] avenue =
    "gh_release"` adapter's latest release version against the installed one and, when newer, fetch the
    release archive, verify it against the declared signing key if any (else trusting HTTPS + GitHub),
    and re-register. With no name, sweeps every gh_release adapter; with a name, updates just that one

    Usage: spt adapter update [OPTIONS] [NAME]

    Arguments:
      [NAME]  A single registered adapter to update (all gh_release adapters if omitted)

    Options:
          --json  Emit machine-readable JSON instead of the human view. Honored by the read/status
                  commands (list, whoami, status, description, role, the *-list queries, how-to); action
                  commands ignore it
      -h, --help  Print help

### [spt adapter use](#spt-adapter-use)

    Set or clear the active-profile pointer — the default <adapter>[:profile] a harness session
    binds to when no --adapter is given. spt adapter use <adapter>[:profile] points every host
    binary the adapter declares at it (run once per host binary you support); --clear <adapter|binary>
    drops the pointer (resolution falls back to the freshest-registered adapter). Never changed by
    install or update

    Usage: spt adapter use [OPTIONS] <TARGET>

    Arguments:
      <TARGET>  <adapter>[:profile] to make active — or, with --clear, the <adapter> or host
                <binary> whose pointer to drop

    Options:
          --clear  Clear the pointer for target instead of setting it
          --json   Emit machine-readable JSON instead of the human view. Honored by the read/status
                   commands (list, whoami, status, description, role, the *-list queries, how-to);
                   action commands ignore it
      -h, --help   Print help

## [spt daemon](#spt-daemon)

    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 [OPTIONS] [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). Refuses with a warning if it hosts live
              sessions (they would be killed) — pass --force to stop anyway
      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:
          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

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

### [spt daemon run](#spt-daemon-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

    Usage: spt daemon run [OPTIONS]

    Options:
          --json  Emit machine-readable JSON instead of the human view. Honored by the read/status
                  commands (list, whoami, status, description, role, the *-list queries, how-to); action
                  commands ignore it
      -h, --help  Print help

### [spt daemon start](#spt-daemon-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

    Usage: spt daemon start [OPTIONS]

    Options:
          --json  Emit machine-readable JSON instead of the human view. Honored by the read/status
                  commands (list, whoami, status, description, role, the *-list queries, how-to); action
                  commands ignore it
      -h, --help  Print help

### [spt daemon stop](#spt-daemon-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). Refuses with a warning if it hosts live sessions
    (they would be killed) — pass --force to stop anyway

    Usage: spt daemon stop [OPTIONS]

    Options:
          --force  Stop even when the daemon hosts live sessions (which the stop kills). Without it, a
                   daemon with live hosted sessions refuses and names them
          --json   Emit machine-readable JSON instead of the human view. Honored by the read/status
                   commands (list, whoami, status, description, role, the *-list queries, how-to);
                   action commands ignore it
      -h, --help   Print help

### [spt daemon status](#spt-daemon-status)

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

    Usage: spt daemon status [OPTIONS]

    Options:
          --json  Emit machine-readable JSON instead of the human view. Honored by the read/status
                  commands (list, whoami, status, description, role, the *-list queries, how-to); action
                  commands ignore it
      -h, --help  Print help

## [spt grant](#spt-grant)

    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 [OPTIONS] <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:
          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

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

### [spt grant add](#spt-grant-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

    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:
          --json                   Emit machine-readable JSON instead of the human view. Honored by the
                                   read/status commands (list, whoami, status, description, role, the
                                   *-list queries, how-to); action commands ignore it
          --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](#spt-grant-revoke)

    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:
          --json                   Emit machine-readable JSON instead of the human view. Honored by the
                                   read/status commands (list, whoami, status, description, role, the
                                   *-list queries, how-to); action commands ignore it
          --qualifier <QUALIFIER>  
      -h, --help                   Print help

### [spt grant list](#spt-grant-list)

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

    Usage: spt grant list [OPTIONS] [AGENT]

    Arguments:
      [AGENT]  

    Options:
          --json  Emit machine-readable JSON instead of the human view. Honored by the read/status
                  commands (list, whoami, status, description, role, the *-list queries, how-to); action
                  commands ignore it
      -h, --help  Print help

## [spt notif](#spt-notif)

    Inspect and acknowledge notifications.

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

    Usage: spt notif [OPTIONS] <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:
          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

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

### [spt notif list](#spt-notif-list)

    List notifications (all member subnets, or one)

    Usage: spt notif list [OPTIONS]

    Options:
          --json             Emit machine-readable JSON instead of the human view. Honored by the
                             read/status commands (list, whoami, status, description, role, the *-list
                             queries, how-to); action commands ignore it
          --subnet <SUBNET>  Limit to one subnet
      -h, --help             Print help

### [spt notif dismiss](#spt-notif-dismiss)

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

    Usage: spt notif dismiss [OPTIONS] <NOTIF_ID>

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

    Options:
          --json  Emit machine-readable JSON instead of the human view. Honored by the read/status
                  commands (list, whoami, status, description, role, the *-list queries, how-to); action
                  commands ignore it
      -h, --help  Print help

## [spt rc](#spt-rc)

    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:
          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

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

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

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

## [spt subnet](#spt-subnet)

    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 [OPTIONS] [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:
          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

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

### [spt subnet status](#spt-subnet-status)

    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:
          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

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

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

### [spt subnet create](#spt-subnet-create)

    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 [OPTIONS] <NAME>

    Arguments:
      <NAME>
              The new subnet's name

    Options:
          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

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

### [spt subnet show-code](#spt-subnet-show-code)

    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 [OPTIONS] [NAME]

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

    Options:
          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

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

### [spt subnet join](#spt-subnet-join)

    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)

          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

          --verbose
              Print a detailed discovery trace (rendezvous attempts, elapsed vs deadline, the last
              concrete error) when the search struggles or fails — for diagnosing a join that can't find
              a member

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

### [spt subnet leave](#spt-subnet-leave)

    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 [OPTIONS] <NAME>

    Arguments:
      <NAME>
              The held subnet to leave

    Options:
          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

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

### [spt subnet prune](#spt-subnet-prune)

    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 [OPTIONS] <NODE>

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

    Options:
          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

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

### [spt subnet revoke](#spt-subnet-revoke)

    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)

          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

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

### [spt subnet detach](#spt-subnet-detach)

    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:
          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

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

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

### [spt subnet attach](#spt-subnet-attach)

    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:
          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

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

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

### [spt subnet notify](#spt-subnet-notify)

    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:
          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

          --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](#spt-update)

    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 [OPTIONS] <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:
          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

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

### [spt update apply](#spt-update-apply)

    Apply the staged, verified self-update now

    Usage: spt update apply [OPTIONS]

    Options:
          --finish  Finish onto the new version in one step: install it, then restart the daemon so both
                    the coordinator and every live agent run the new version. Hosted sessions come back
                    automatically — no manual restart. Without this flag, install alone leaves the
                    running daemon on the previous version until you restart it yourself
          --json    Emit machine-readable JSON instead of the human view. Honored by the read/status
                    commands (list, whoami, status, description, role, the *-list queries, how-to);
                    action commands ignore it
      -h, --help    Print help

### [spt update fetch](#spt-update-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

    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
          --json               Emit machine-readable JSON instead of the human view. Honored by the
                               read/status commands (list, whoami, status, description, role, the *-list
                               queries, how-to); action commands ignore it
          --tag <TAG>          Fetch a specific release tag (e.g. v0.3.1) instead of the latest
          --apply              Fetch then install in one step — apply the staged update even if the
                               latest was already downloaded. The one-shot "get me to the latest"
      -h, --help               Print help

## [spt api](#spt-api)

    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] <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
      psyche-download  Emit the agent's resume context (durable role/live/project tiers + any
                       not-yet-synthesized commune/signoff drop as pending slices) to stdout, for the
                       harness adapter's SessionStart hook to inject as additional context
      worker-start     Create a nested worker perch under a parent. The worker id is minted by spt-core
                       ({parent}-w{N}) and echoed as the bare id on stdout — the caller does NOT pass
                       one. --agent-id/--agent-type are optional correlation metadata, never the
                       perch identity
      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
      endpoint-info    Emit an endpoint's identity, where it runs, and which node (if any) is driving
                       it, as JSON. With no id, reports the caller's own endpoint (like whoami); an
                       explicit id reports that endpoint. Read-only
      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
      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
      drive-poll       Take-and-clear a Shell's pending drive frame: the shell-side drain of the
                       owner→shell ephemeral control channel. REST-only, exactly-once — the daemon
                       serves the single latest frame and ONLY when the link matches the slot's
                       write-time stamp (no stale-control replay on relink). The link token is the auth
                       (mirrors emit). The frame, if any, prints to stdout
      tunnel           Use the shell end of the opaque byte TUNNEL: a held, reliable-ordered QUIC stream
                       the channel taxonomy never reinterprets (first consumer: USB/IP URB traffic).
                       send pipes raw stdin into the tunnel; recv drains buffered bytes to raw
                       stdout. The link token is the auth (mirrors drive-poll); the stream resolves
                       only under the live link generation. Poll-drained at the surface
      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. Optional: an explicit name[:profile]
              override for adapter dev/iteration. Omitted, listen resolves the owning adapter/profile
              at bind from the seed's parent pid (host_binaries → active-profile pointer →
              registered_at_ms)

          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

          --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](#spt-api-seed)

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

    Usage: spt api seed [OPTIONS] --pid <PID> --session-id <SESSION_ID>

    Options:
          --json                     Emit machine-readable JSON instead of the human view. Honored by
                                     the read/status commands (list, whoami, status, description, role,
                                     the *-list queries, how-to); action commands ignore it
          --pid <PID>  
          --session-id <SESSION_ID>  
      -h, --help                     Print help

### [spt api listen](#spt-api-listen)

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

    Usage: spt api listen [OPTIONS] <ID>

    Arguments:
      <ID>  

    Options:
          --json                     Emit machine-readable JSON instead of the human view. Honored by
                                     the read/status commands (list, whoami, status, description, role,
                                     the *-list queries, how-to); action commands ignore it
          --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)
          --session-id <SESSION_ID>  Bind from this session id when the ephemeral seed is gone (a
                                     session going live late, or after a daemon restart). With no live
                                     seed and no session id, listen refuses (NO_SEED)
      -h, --help                     Print help

### [spt api bind](#spt-api-bind)

    Post-spawn bind of a session to its perch

    Usage: spt api bind [OPTIONS] <ID>

    Arguments:
      <ID>  

    Options:
          --json                           Emit machine-readable JSON instead of the human view. Honored
                                           by the read/status commands (list, whoami, status,
                                           description, role, the *-list queries, how-to); action
                                           commands ignore it
          --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. 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](#spt-api-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

    Usage: spt api bind-shell [OPTIONS] --link <LINK_TOKEN>

    Options:
          --json               Emit machine-readable JSON instead of the human view. Honored by the
                               read/status commands (list, whoami, status, description, role, the *-list
                               queries, how-to); action commands ignore it
          --link <LINK_TOKEN>  The link token the broker minted at launch
      -h, --help               Print help

### [spt api state](#spt-api-state)

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

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

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

    Options:
          --json                     Emit machine-readable JSON instead of the human view. Honored by
                                     the read/status commands (list, whoami, status, description, role,
                                     the *-list queries, how-to); action commands ignore it
          --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](#spt-api-echo-gate)

    Manage the echo-gate sentinel directly

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

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

    Options:
          --json                     Emit machine-readable JSON instead of the human view. Honored by
                                     the read/status commands (list, whoami, status, description, role,
                                     the *-list queries, how-to); action commands ignore it
          --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](#spt-api-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

    Usage: spt api poll [OPTIONS] <ID>

    Arguments:
      <ID>  

    Options:
          --include-deferred  
          --json                     Emit machine-readable JSON instead of the human view. Honored by
                                     the read/status commands (list, whoami, status, description, role,
                                     the *-list queries, how-to); action commands ignore it
          --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 psyche-download](#spt-api-psyche-download)

    Emit the agent's resume context (durable role/live/project tiers + any not-yet-synthesized
    commune/signoff drop as pending slices) to stdout, for the harness adapter's SessionStart hook to
    inject as additional context

    Usage: spt api psyche-download [OPTIONS] <ID>

    Arguments:
      <ID>  

    Options:
          --json                     Emit machine-readable JSON instead of the human view. Honored by
                                     the read/status commands (list, whoami, status, description, role,
                                     the *-list queries, how-to); action commands ignore it
          --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](#spt-api-worker-start)

    Create a nested worker perch under a parent. The worker id is minted by spt-core ({parent}-w{N})
    and echoed as the bare id on stdout — the caller does NOT pass one. --agent-id/--agent-type are
    optional correlation metadata, never the perch identity

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

    Arguments:
      <PARENT>  

    Options:
          --agent-id <AGENT_ID>      Adapter's own agent id (correlation metadata only)
          --json                     Emit machine-readable JSON instead of the human view. Honored by
                                     the read/status commands (list, whoami, status, description, role,
                                     the *-list queries, how-to); action commands ignore it
          --agent-type <AGENT_TYPE>  Adapter's own agent type (correlation metadata only)
          --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](#spt-api-worker-stop)

    Tear down a worker perch

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

    Arguments:
      <ID>  

    Options:
          --json                     Emit machine-readable JSON instead of the human view. Honored by
                                     the read/status commands (list, whoami, status, description, role,
                                     the *-list queries, how-to); action commands ignore it
          --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](#spt-api-worker-poll)

    Drain a worker perch's messages

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

    Arguments:
      <ID>  

    Options:
          --json                     Emit machine-readable JSON instead of the human view. Honored by
                                     the read/status commands (list, whoami, status, description, role,
                                     the *-list queries, how-to); action commands ignore it
          --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](#spt-api-boundary)

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

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

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

    Options:
          --json                        Emit machine-readable JSON instead of the human view. Honored by
                                        the read/status commands (list, whoami, status, description,
                                        role, the *-list queries, how-to); action commands ignore it
          --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](#spt-api-session-end)

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

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

    Arguments:
      <ID>  

    Options:
          --erase  
          --json                     Emit machine-readable JSON instead of the human view. Honored by
                                     the read/status commands (list, whoami, status, description, role,
                                     the *-list queries, how-to); action commands ignore it
          --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](#spt-api-presence)

    Report user/agent presence at this endpoint

    Usage: spt api presence [OPTIONS] <ID>

    Arguments:
      <ID>  

    Options:
          --json                     Emit machine-readable JSON instead of the human view. Honored by
                                     the read/status commands (list, whoami, status, description, role,
                                     the *-list queries, how-to); action commands ignore it
          --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](#spt-api-driven-by)

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

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

    Arguments:
      <ID>  

    Options:
          --json                     Emit machine-readable JSON instead of the human view. Honored by
                                     the read/status commands (list, whoami, status, description, role,
                                     the *-list queries, how-to); action commands ignore it
          --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 endpoint-info](#spt-api-endpoint-info)

    Emit an endpoint's identity, where it runs, and which node (if any) is driving it, as JSON. With no
    id, reports the caller's own endpoint (like whoami); an explicit id reports that endpoint. Read-only

    Usage: spt api endpoint-info [OPTIONS] [ID]

    Arguments:
      [ID]  The endpoint id to report on. Omit to self-resolve the caller's perch

    Options:
          --json  Emit machine-readable JSON instead of the human view. Honored by the read/status
                  commands (list, whoami, status, description, role, the *-list queries, how-to); action
                  commands ignore it
      -h, --help  Print help

### [spt api history-log](#spt-api-history-log)

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

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

    Arguments:
      <ID>  

    Options:
          --json                     Emit machine-readable JSON instead of the human view. Honored by
                                     the read/status commands (list, whoami, status, description, role,
                                     the *-list queries, how-to); action commands ignore it
          --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](#spt-api-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

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

    Arguments:
      <ID>  

    Options:
          --json                     Emit machine-readable JSON instead of the human view. Honored by
                                     the read/status commands (list, whoami, status, description, role,
                                     the *-list queries, how-to); action commands ignore it
          --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](#spt-api-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

    Usage: spt api emit [OPTIONS] --type <TYPE> --link <LINK> <ID> <PAYLOAD>

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

    Options:
          --json         Emit machine-readable JSON instead of the human view. Honored by the
                         read/status commands (list, whoami, status, description, role, the *-list
                         queries, how-to); action commands ignore it
          --type <TYPE>  
          --link <LINK>  Shell link token (the per-link credential from launch)
      -h, --help         Print help

### [spt api drive-poll](#spt-api-drive-poll)

    Take-and-clear a Shell's pending drive frame: the shell-side drain of the owner→shell ephemeral
    control channel. REST-only, exactly-once — the daemon serves the single latest frame and ONLY when
    the link matches the slot's write-time stamp (no stale-control replay on relink). The link token is
    the auth (mirrors emit). The frame, if any, prints to stdout

    Usage: spt api drive-poll [OPTIONS] --link <LINK> <ID>

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

    Options:
          --json         Emit machine-readable JSON instead of the human view. Honored by the
                         read/status commands (list, whoami, status, description, role, the *-list
                         queries, how-to); action commands ignore it
          --link <LINK>  Shell link token (the per-link credential from launch)
      -h, --help         Print help

### [spt api tunnel](#spt-api-tunnel)

    Use the shell end of the opaque byte TUNNEL: a held, reliable-ordered QUIC stream the channel
    taxonomy never reinterprets (first consumer: USB/IP URB traffic). send pipes raw stdin into the
    tunnel; recv drains buffered bytes to raw stdout. The link token is the auth (mirrors
    drive-poll); the stream resolves only under the live link generation. Poll-drained at the surface

    Usage: spt api tunnel [OPTIONS] --link <LINK> <ID> <DIRECTION>

    Arguments:
      <ID>         The shell instance id (must match the link token's instance)
      <DIRECTION>  send (raw stdin → tunnel) or recv (tunnel → raw stdout)

    Options:
          --json         Emit machine-readable JSON instead of the human view. Honored by the
                         read/status commands (list, whoami, status, description, role, the *-list
                         queries, how-to); action commands ignore it
          --link <LINK>  Shell link token (the per-link credential from launch)
      -h, --help         Print help

### [spt api capability](#spt-api-capability)

    Print the adapter's declared capability (hostable_types)

    Usage: spt api capability [OPTIONS]

    Options:
          --json  Emit machine-readable JSON instead of the human view. Honored by the read/status
                  commands (list, whoami, status, description, role, the *-list queries, how-to); action
                  commands ignore it
      -h, --help  Print help

### [spt api hint](#spt-api-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

    Usage: spt api hint [OPTIONS] --session <SESSION>

    Options:
          --json               Emit machine-readable JSON instead of the human view. Honored by the
                               read/status commands (list, whoami, status, description, role, the *-list
                               queries, how-to); action commands ignore it
          --session <SESSION>  The harness session id keying the once-per-session seen-set
      -h, --help               Print help

### [spt api shutdown](#spt-api-shutdown)

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

    Usage: spt api shutdown [OPTIONS] <ID>

    Arguments:
      <ID>  

    Options:
          --json                     Emit machine-readable JSON instead of the human view. Honored by
                                     the read/status commands (list, whoami, status, description, role,
                                     the *-list queries, how-to); action commands ignore it
          --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](#spt-api-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

    Usage: spt api owner-shutdown [OPTIONS] --link <LINK> <ID>

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

    Options:
          --json         Emit machine-readable JSON instead of the human view. Honored by the
                         read/status commands (list, whoami, status, description, role, the *-list
                         queries, how-to); action commands ignore it
          --link <LINK>  Shell link token (the per-link credential from launch)
      -h, --help         Print help

## [spt endpoint](#spt-endpoint)

    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 [OPTIONS] [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
      purge        Permanently remove an endpoint and every record keyed on it
      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:
          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

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

### [spt endpoint list](#spt-endpoint-list)

    Merged endpoint listing (the bare spt endpoint view).

    Every member subnet's endpoints grouped by subnet, with this session's own endpoint pinned at the
    top, AND this node's local perches merged in (so a just-online endpoint not yet advertised still
    shows — spt whoami is a thin alias and must see its own perch). --subnet filters the subnet view
    to one subnet; --detail adds each endpoint's description blurb (the resource-registry yellow-pages
    projection).

    Usage: spt endpoint list [OPTIONS]

    Options:
          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

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

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

          --show-all
              Also show suspended (resting) endpoints, which are hidden by default

          --workers
              Also show worker perches, which are hidden by default (they are process-local machinery
              under a parent agent, not standalone endpoints)

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

### [spt endpoint run](#spt-endpoint-run)

    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

          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

          --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)

          --subnet <SUBNET>
              Home this endpoint to a named subnet. Required on a node that holds more than one subnet
              (the home is assigned at creation and is permanent); the sole subnet is used automatically
              when there is one

          --save
              Also save this run as a startup default: the daemon replays it (a fresh session, same
              adapter and working directory) every time it starts, until the entry is removed from
              daemon.json. One entry per endpoint id — a re-save replaces the prior one. A saved
              endpoint that fails to come up logs the failure and never blocks the daemon

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

### [spt endpoint fork](#spt-endpoint-fork)

    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:
          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

          --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](#spt-endpoint-suspend)

    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 [OPTIONS] <ID>

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

    Options:
          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

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

### [spt endpoint wake](#spt-endpoint-wake)

    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 [OPTIONS] <ID>

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

    Options:
          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

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

### [spt endpoint shutdown](#spt-endpoint-shutdown)

    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 [OPTIONS] [ID]

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

    Options:
          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

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

### [spt endpoint stop](#spt-endpoint-stop)

    Soft-stop a perch (spool preserved).

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

    Usage: spt endpoint stop [OPTIONS] <ID>

    Arguments:
      <ID>
              Perch id to stop

    Options:
          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

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

### [spt endpoint rename](#spt-endpoint-rename)

    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 [OPTIONS] <OLD_ID> <NEW_ID>

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

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

    Options:
          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

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

### [spt endpoint purge](#spt-endpoint-purge)

    Permanently remove an endpoint and every record keyed on it.

    Deletes the perch tree (including its nested companion/worker perches and shells), the registry
    address, the endpoint's context branches, and its node-local trust rows. Local only. Offline-only:
    refuses while the endpoint is online — stop it first, or pass --force to stop-then-purge.
    Irreversible; confirms interactively unless --yes.

    Usage: spt endpoint purge [OPTIONS] <ID>

    Arguments:
      <ID>
              The endpoint id to remove

    Options:
          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

          --yes
              Skip the interactive confirmation (for scripts / CI)

          --force
              Stop the endpoint first if it is online, then purge

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

### [spt endpoint digest](#spt-endpoint-digest)

    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 --follows 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 machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

          --last <LAST>
              Show the last N turns instead of the default window (--last 1 is the latest turn — the
              turn-end output)

          --after <AFTER>
              Cursor: show only entries newer than this seq (the authoritative dedup key from a prior
              pull). If the seq predates the window, the full window is returned with a predates signal

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

### [spt endpoint access](#spt-endpoint-access)

    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 [OPTIONS] <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:
          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

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

### [spt endpoint description](#spt-endpoint-description)

    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 [OPTIONS] [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:
          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

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

### [spt endpoint role](#spt-endpoint-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

    Usage: spt endpoint role [OPTIONS]

    Options:
          --id <ID>                Which local endpoint (auto-detected from the session if omitted)
          --json                   Emit machine-readable JSON instead of the human view. Honored by the
                                   read/status commands (list, whoami, status, description, role, the
                                   *-list queries, how-to); action commands ignore it
          --overwrite <OVERWRITE>  Replace the role with the contents of <file> (the only writer)
      -h, --help                   Print help

## [spt how-to](#spt-how-to)

    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 [OPTIONS] [TOPIC]

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

    Options:
          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

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

## [spt ready](#spt-ready)

    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:
          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

          --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](#spt-ring)

    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)

          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

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

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

## [spt send](#spt-send)

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

    Usage: spt send [OPTIONS] <TARGET>

    Arguments:
      <TARGET>  Target perch id

    Options:
          --from <FROM>          Sender id carried structurally as the message from (auto-detected
                                 from session if omitted)
          --json                 Emit machine-readable JSON instead of the human view. Honored by the
                                 read/status commands (list, whoami, status, description, role, the
                                 *-list queries, how-to); action commands ignore it
          --idle-only            Deliver only when the target is idle (the idle/wake window); hold until
                                 then and never surface to the target's active poll
          --active-only          Deliver only through the target's own poll (the no-interrupt hook
                                 channel); never wakes an idle target. Replaces the old --deferred
          --ephemeral            Drop the message if it cannot be delivered in its window, instead of
                                 spooling until delivered
          --prefer-native        Deliver through the target's translation binary when one is running,
                                 else fall back to the normal channel. Delivers regardless of
                                 idle/active
          --force-native         Deliver ONLY through the target's translation binary — no fallback and
                                 no spooling. If no binary is running the send is reported undelivered
          --json-payload <JSON>  Attach an opaque JSON metadata blob alongside the message body, carried
                                 verbatim for the receiving adapter to parse. Does not replace the body
          --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
      -h, --help                 Print help

## [spt shell](#spt-shell)

    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 [OPTIONS] <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)
      drive     Drive the shell with a typed, EPHEMERAL control payload: the owner→shell mirror of
                sensory. The drive-type is vocabulary-checked against [shell.drive], held in a single
                latest-wins in-memory slot on the daemon, and drained by the shell's api drive-poll
                --link. NEVER spooled — an offline shell drops the payload with a diagnostic (control
                is live-or-drop, never replayed)
      tunnel    Use the shell's opaque byte TUNNEL: a held, reliable-ordered QUIC stream the channel
                taxonomy never reinterprets (first consumer: USB/IP URB traffic). send pipes raw stdin
                bytes into the tunnel; recv drains buffered bytes to stdout. The shell opts in via
                [shell.tunnel]; the tunnel lives for the link (a link-break closes it). Poll-drained
                at the surface
      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:
          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

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

### [spt shell spawn](#spt-shell-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)

    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)
          --json           Emit machine-readable JSON instead of the human view. Honored by the
                           read/status commands (list, whoami, status, description, role, the *-list
                           queries, how-to); action commands ignore it
          --owner <OWNER>  Owning endpoint id (auto-detected from session if omitted)
      -h, --help           Print help

### [spt shell list](#spt-shell-list)

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

    Usage: spt shell list [OPTIONS]

    Options:
          --json           Emit machine-readable JSON instead of the human view. Honored by the
                           read/status commands (list, whoami, status, description, role, the *-list
                           queries, how-to); action commands ignore it
          --owner <OWNER>  
      -h, --help           Print help

### [spt shell teardown](#spt-shell-teardown)

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

    Usage: spt shell teardown [OPTIONS] <SHELL_REF>

    Arguments:
      <SHELL_REF>  Canonical id or alias

    Options:
          --json           Emit machine-readable JSON instead of the human view. Honored by the
                           read/status commands (list, whoami, status, description, role, the *-list
                           queries, how-to); action commands ignore it
          --owner <OWNER>  
      -h, --help           Print help

### [spt shell rename](#spt-shell-rename)

    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:
          --json           Emit machine-readable JSON instead of the human view. Honored by the
                           read/status commands (list, whoami, status, description, role, the *-list
                           queries, how-to); action commands ignore it
          --owner <OWNER>  
      -h, --help           Print help

### [spt shell cmd](#spt-shell-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)

    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:
          --json           Emit machine-readable JSON instead of the human view. Honored by the
                           read/status commands (list, whoami, status, description, role, the *-list
                           queries, how-to); action commands ignore it
          --owner <OWNER>  
      -h, --help           Print help

### [spt shell drive](#spt-shell-drive)

    Drive the shell with a typed, EPHEMERAL control payload: the owner→shell mirror of sensory. The
    drive-type is vocabulary-checked against [shell.drive], held in a single latest-wins in-memory
    slot on the daemon, and drained by the shell's api drive-poll --link. NEVER spooled — an offline
    shell drops the payload with a diagnostic (control is live-or-drop, never replayed)

    Usage: spt shell drive [OPTIONS] --type <DRIVE_TYPE> <SHELL_REF> <PAYLOAD>

    Arguments:
      <SHELL_REF>  Canonical id or alias
      <PAYLOAD>    The opaque control payload (descriptive text / encoded blob reference)

    Options:
          --json               Emit machine-readable JSON instead of the human view. Honored by the
                               read/status commands (list, whoami, status, description, role, the *-list
                               queries, how-to); action commands ignore it
          --type <DRIVE_TYPE>  The drive payload type (vocabulary-checked against [shell.drive])
          --owner <OWNER>  
      -h, --help               Print help

### [spt shell tunnel](#spt-shell-tunnel)

    Use the shell's opaque byte TUNNEL: a held, reliable-ordered QUIC stream the channel taxonomy never
    reinterprets (first consumer: USB/IP URB traffic). send pipes raw stdin bytes into the tunnel;
    recv drains buffered bytes to stdout. The shell opts in via [shell.tunnel]; the tunnel lives for
    the link (a link-break closes it). Poll-drained at the surface

    Usage: spt shell tunnel [OPTIONS] <SHELL_REF> <DIRECTION>

    Arguments:
      <SHELL_REF>  Canonical id or alias
      <DIRECTION>  send (raw stdin → tunnel) or recv (tunnel → raw stdout)

    Options:
          --json           Emit machine-readable JSON instead of the human view. Honored by the
                           read/status commands (list, whoami, status, description, role, the *-list
                           queries, how-to); action commands ignore it
          --owner <OWNER>  
      -h, --help           Print help

### [spt shell send](#spt-shell-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

    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
          --json           Emit machine-readable JSON instead of the human view. Honored by the
                           read/status commands (list, whoami, status, description, role, the *-list
                           queries, how-to); action commands ignore it
          --owner <OWNER>  
      -h, --help           Print help

### [spt shell relink](#spt-shell-relink)

    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:
          --json           Emit machine-readable JSON instead of the human view. Honored by the
                           read/status commands (list, whoami, status, description, role, the *-list
                           queries, how-to); action commands ignore it
          --owner <OWNER>  
      -h, --help           Print help

## [spt whoami](#spt-whoami)

    Print this session's own perch id.

    Resolved from $OWL_SESSION_ID / $SPT_AGENT_ID.

    Usage: spt whoami [OPTIONS]

    Options:
          --json
              Emit machine-readable JSON instead of the human view. Honored by the read/status commands
              (list, whoami, status, description, role, the *-list queries, how-to); action commands
              ignore it

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