CLI reference
Generated from the
sptbinary’s own--helpoutput (cargo run -p xtask -- gen) and drift-gated in CI — this page cannot disagree with the binary. Do not edit by hand.
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 <COMMAND>
Commands:
send Send a message (body read from stdin). Fire-and-forget
ring Send and block for a reply (body read from stdin; reply printed to stdout)
ready Become reachable: register the perch and listen for messages (blocks)
poll Receive messages: drain backlog then listen, printing each to stdout
list List this node's perches (id, state, address, ready, alive)
stop Soft-stop a perch: remove the ready marker + unregister (spool preserved)
whoami Print this session's own perch id (from $OWL_SESSION_ID / $SPT_AGENT_ID)
pair Subnet pairing: show this node's current pairing code (and mint new subnets). Pairing is how machines join a private subnet
digest Show a hosted session's live activity buffer (PTY digest) — the at-a-glance "what is this agent doing now" view. Pulls a snapshot, or `--follow`s the delta-stream. Local endpoints only
rename Rename an endpoint's logical id, rippled across its on-disk state: the endpoint's perch dir, its nested companion/worker perches, and every record naming it. Refuses while the perch is live (stop it first)
access Endpoint access whitelist: 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
grant Consent grant store: which agents hold which gated capabilities on this node. Default-deny (the access whitelist's opposite polarity). An ungranted ask escalates interactively; `add` is the durable allow-always answer
adapter Adapter registration: the node-local registered set — what this node can drive/launch (one command for harness and shell adapters). The registered set feeds creation-time adapter selection, shell discovery, and the self-update ripple
shell Shell instances: mint, list, drive, and tear down 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
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
notif Inspect and acknowledge notifications. Dismissal is the explicit ack — it latches and replicates subnet-wide
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
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)
resources The subnet resource registry: per-endpoint free-text service blurbs — an agent yellow-pages. `set` authors your own, `show` reads a local endpoint's, `list` projects the registry view over visible rows
suspend Rest an endpoint cold: 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
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
shutdown Gracefully shut down an agent's own endpoint: soft-stop the listener, then the suspend edge — the final context save fires and persistent shells cascade offline with it
api Harness-contract inbound surface: the entry points a harness's hooks fire to keep spt-core's on-disk state in sync
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
-V, --version Print version
spt send
Send a message (body read from stdin). Fire-and-forget
Usage: spt send [OPTIONS] [TARGET]
Arguments:
[TARGET] Target perch id. May be omitted when --reply-to is given
Options:
--from <FROM> Sender id written into __REPLY_TO__ (auto-detected from session if omitted)
--reply-to <REPLY_TO> Reply to this sender; sets the target and labels output REPLIED
--deferred Spool only (deferred / hook channel) — no live wake
-h, --help Print help
spt ring
Send and block for a reply (body read from stdin; reply printed to stdout)
Usage: spt ring [OPTIONS] <TARGET>
Arguments:
<TARGET> Target perch id
Options:
--from <FROM> Sender id (auto-detected from session if omitted)
--timeout <TIMEOUT> Seconds to wait for a reply before giving up [default: 60]
-h, --help Print help
spt ready
Become reachable: register the perch and listen for messages (blocks)
Usage: spt ready [OPTIONS] <ID>
Arguments:
<ID> This agent's perch id
Options:
--subnet <SUBNET> Home subnet for a NEW endpoint (required on a multi-subnet node — home is assigned at creation, never guessed)
-h, --help Print help
spt poll
Receive messages: drain backlog then listen, printing each to stdout
Usage: spt poll [OPTIONS] <ID>
Arguments:
<ID> This agent's perch id
Options:
--once Run a single drain+receive cycle, then exit (legacy one-shot)
--subnet <SUBNET> Home subnet for a NEW endpoint (see `ready`)
-h, --help Print help
spt list
List this node's perches (id, state, address, ready, alive)
Usage: spt list
Options:
-h, --help Print help
spt stop
Soft-stop a perch: remove the ready marker + unregister (spool preserved)
Usage: spt stop <ID>
Arguments:
<ID> Perch id to stop
Options:
-h, --help Print help
spt whoami
Print this session's own perch id (from $OWL_SESSION_ID / $SPT_AGENT_ID)
Usage: spt whoami
Options:
-h, --help Print help
spt pair
Subnet pairing: show this node's current pairing code (and mint new subnets). Pairing is how machines join a private subnet
Usage: spt pair <COMMAND>
Commands:
show-totp Show a subnet's current 6-digit pairing code + `otpauth://` URI — gated behind OS elevation (or read the code from your authenticator app). With no flag the node's sole subnet is used; if it holds several, `--subnet <name>` is required (never guessed). `--create-new <name>` mints a fresh subnet first
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
spt pair show-totp
Show a subnet's current 6-digit pairing code + `otpauth://` URI — gated behind OS elevation (or read the code from your authenticator app). With no flag the node's sole subnet is used; if it holds several, `--subnet <name>` is required (never guessed). `--create-new <name>` mints a fresh subnet first
Usage: spt pair show-totp [OPTIONS]
Options:
--subnet <SUBNET> Which subnet's code to show. Required only when the node holds several
--create-new <NAME> Mint a fresh subnet with this name (this node becomes the sole seed-holder), then show its code. Mutually exclusive with `--subnet`
-h, --help Print help
spt digest
Show a hosted session's live activity buffer (PTY digest) — the at-a-glance "what is this agent doing now" view. Pulls a snapshot, or `--follow`s the delta-stream. Local endpoints only
Usage: spt digest [OPTIONS] <ID>
Arguments:
<ID> The (local) endpoint id to read
Options:
--follow Stream live changes instead of a one-shot snapshot (Ctrl-C to stop)
--json Emit structured JSON instead of the human-glanceable render
-h, --help Print help
spt rename
Rename an endpoint's logical id, rippled across its on-disk state: 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 rename <OLD_ID> <NEW_ID>
Arguments:
<OLD_ID> The endpoint's current (bare) id
<NEW_ID> The new (bare) id — charset-validated; `:`/`@` are reserved
Options:
-h, --help Print help
spt access
Endpoint access whitelist: 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 access <COMMAND>
Commands:
allow Whitelist a node for an endpoint (creates the restriction if absent)
revoke Remove a node from an endpoint's whitelist. Never widens: revoking the last node leaves the endpoint locked down (all unsolicited refused)
open Delete an endpoint's restriction entirely — back to default-open
list List restrictions (all endpoints, or one)
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
spt access allow
Whitelist a node for an endpoint (creates the restriction if absent)
Usage: spt access allow <ENDPOINT> <NODE>
Arguments:
<ENDPOINT> The endpoint to restrict
<NODE> The origin node's pubkey hex (as shown by `spt list` / pairing)
Options:
-h, --help Print help
spt access revoke
Remove a node from an endpoint's whitelist. Never widens: revoking the last node leaves the endpoint locked down (all unsolicited refused)
Usage: spt access revoke <ENDPOINT> <NODE>
Arguments:
<ENDPOINT>
<NODE>
Options:
-h, --help Print help
spt access open
Delete an endpoint's restriction entirely — back to default-open
Usage: spt access open <ENDPOINT>
Arguments:
<ENDPOINT>
Options:
-h, --help Print help
spt access list
List restrictions (all endpoints, or one)
Usage: spt access list [ENDPOINT]
Arguments:
[ENDPOINT]
Options:
-h, --help Print help
spt grant
Consent grant store: which agents hold which gated capabilities on this node. Default-deny (the access whitelist's opposite polarity). An ungranted ask escalates interactively; `add` is the durable allow-always answer
Usage: spt grant <COMMAND>
Commands:
add Record a grant: `agent` may exercise `capability` on this node. Refuses the reserved deferred capability ids (remote-exec, instantiate-anywhere) — their gate refuses unconditionally, so a row would only be a footgun-in-waiting
revoke Remove the exact grant row. Never widens or narrows neighbours: only the named (capability, agent, qualifier) tuple goes
list List grant rows (all, or one agent's)
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
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:
--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
Remove the exact grant row. Never widens or narrows neighbours: only the named (capability, agent, qualifier) tuple goes
Usage: spt grant revoke [OPTIONS] <CAPABILITY> <AGENT>
Arguments:
<CAPABILITY>
<AGENT>
Options:
--qualifier <QUALIFIER>
-h, --help Print help
spt grant list
List grant rows (all, or one agent's)
Usage: spt grant list [AGENT]
Arguments:
[AGENT]
Options:
-h, --help Print help
spt adapter
Adapter registration: the node-local registered set — what this node can drive/launch (one command for harness and shell adapters). The registered set feeds creation-time adapter selection, shell discovery, and the self-update ripple
Usage: spt adapter <COMMAND>
Commands:
add Register an adapter from a local path (a dir holding `manifest.toml`, or the manifest file itself) or from GitHub (`--github user/repo`, cloned under `adapters/_github/`). Manifest-first: an invalid manifest registers nothing. Install is the first update — the declared `[update]` avenue is conducted once after recording
remove Soft-deregister: hidden from new-creation/discovery; existing and live instances keep running. The manifest's optional `uninstall` template is conducted only with --force until quiesce detection lands
list List registered adapters (active and soft-deregistered)
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
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)
Options:
--github <GITHUB> GitHub source `user/repo` — manifest-first, then install via the declared `[update]` avenue
-h, --help Print help
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
-h, --help Print help
spt adapter list
List registered adapters (active and soft-deregistered)
Usage: spt adapter list
Options:
-h, --help Print help
spt shell
Shell instances: mint, list, drive, and tear down the driven surfaces this agent owns. `spawn` MINTS a new instance identity (`<adapter>-<n>`) — it is not the online switch; bringing an existing offline instance back is `relink` / `persistent` / wake
Usage: spt shell <COMMAND>
Commands:
spawn Mint a NEW shell instance of a registered `kind="shell"` adapter: canonical id `<adapter>-<n>` (smallest free n; teardown frees slots), starting offline (the launch + bind handshake brings it online)
list List this owner's instances: canonical id, alias, adapter, status
teardown Destroy an instance (perch removed; mint slot + alias freed)
rename Set/replace an instance's alias (owner-unique)
cmd Drive the shell with a typed capability command (the durable command channel): the op + positional args are vocabulary-checked against the manifest's `[shell.capabilities]`, spooled on the shell perch, and drained by the manifest's `command_receipt` mode (relay / stdin)
send Send a text and/or file payload down the durable 2-way text+file channel (agent→shell; the shell answers via ordinary `spt send`). File transfers are progress-queryable by xfer id
relink Bring an existing offline (persistent) instance back online: re-spawns the binary with a fresh link token; the perch onlines at its bind
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
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)
--owner <OWNER> Owning endpoint id (auto-detected from session if omitted)
-h, --help Print help
spt shell list
List this owner's instances: canonical id, alias, adapter, status
Usage: spt shell list [OPTIONS]
Options:
--owner <OWNER>
-h, --help Print help
spt shell teardown
Destroy an instance (perch removed; mint slot + alias freed)
Usage: spt shell teardown [OPTIONS] <SHELL_REF>
Arguments:
<SHELL_REF> Canonical id or alias
Options:
--owner <OWNER>
-h, --help Print help
spt shell rename
Set/replace an instance's alias (owner-unique)
Usage: spt shell rename [OPTIONS] <SHELL_REF> <ALIAS>
Arguments:
<SHELL_REF> Canonical id or current alias
<ALIAS> The new alias
Options:
--owner <OWNER>
-h, --help Print help
spt shell cmd
Drive the shell with a typed capability command (the durable command channel): the op + positional args are vocabulary-checked against the manifest's `[shell.capabilities]`, spooled on the shell perch, and drained by the manifest's `command_receipt` mode (relay / stdin)
Usage: spt shell cmd [OPTIONS] <SHELL_REF> [OP]...
Arguments:
<SHELL_REF> Canonical id or alias
[OP]... The capability op + args (vocabulary-checked against the manifest)
Options:
--owner <OWNER>
-h, --help Print help
spt shell send
Send a text and/or file payload down the durable 2-way text+file channel (agent→shell; the shell answers via ordinary `spt send`). File transfers are progress-queryable by xfer id
Usage: spt shell send [OPTIONS] <SHELL_REF> [TEXT]
Arguments:
<SHELL_REF> Canonical id or alias
[TEXT] The text payload
Options:
--file <FILE> A file to transfer to the shell
--owner <OWNER>
-h, --help Print help
spt shell relink
Bring an existing offline (persistent) instance back online: re-spawns the binary with a fresh link token; the perch onlines at its bind
Usage: spt shell relink [OPTIONS] <SHELL_REF>
Arguments:
<SHELL_REF> Canonical id or alias
Options:
--owner <OWNER>
-h, --help Print help
spt 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
Usage: spt notify [OPTIONS] [BODY]
Arguments:
[BODY] Notification body (read from stdin when omitted)
Options:
--subnet <SUBNET> Which subnet to notify. Required only when the node holds several (never guessed)
--from <FROM> Issuer endpoint id (auto-detected from session if omitted)
-h, --help Print help
spt notif
Inspect and acknowledge notifications. Dismissal is the explicit ack — it latches and replicates subnet-wide
Usage: spt notif <COMMAND>
Commands:
list List notifications (all member subnets, or one)
dismiss Dismiss (ack) a notification by id — latches, replicates subnet-wide
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
spt notif list
List notifications (all member subnets, or one)
Usage: spt notif list [OPTIONS]
Options:
--subnet <SUBNET> Limit to one subnet
-h, --help Print help
spt notif dismiss
Dismiss (ack) a notification by id — latches, replicates subnet-wide
Usage: spt notif dismiss <NOTIF_ID>
Arguments:
<NOTIF_ID> The notif id (as shown by `spt notif list`)
Options:
-h, --help Print help
spt 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 <COMMAND>
Commands:
apply Apply the staged, verified self-update now
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
spt update apply
Apply the staged, verified self-update now
Usage: spt update apply
Options:
-h, --help Print help
spt 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 fork [OPTIONS] --subnet <SUBNET> <SRC> <NEW_ID>
Arguments:
<SRC> The source endpoint (must exist on this node)
<NEW_ID> The fork's id (must differ from the source on the same node)
Options:
--subnet <SUBNET> The fork's home subnet — the target (must be a member)
--delete-source Delete the source endpoint (perch + tracked mind) after the copy
-h, --help Print help
spt resources
The subnet resource registry: per-endpoint free-text service blurbs — an agent yellow-pages. `set` authors your own, `show` reads a local endpoint's, `list` projects the registry view over visible rows
Usage: spt resources <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
list The subnet resource-registry projection: `(id, node, status, blurb)` over VISIBLE rows only (hidden endpoints never appear — discovery leaks nothing a viewer couldn't reach)
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
spt resources set
Author this endpoint's blurb (the agent refines its own at runtime; an empty string clears it back to the node-config seed)
Usage: spt resources set [OPTIONS] <TEXT>
Arguments:
<TEXT> The blurb text ("" clears)
Options:
--id <ID> Which local endpoint (auto-detected from the session if omitted)
-h, --help Print help
spt resources show
Show a local endpoint's authored blurb
Usage: spt resources show [ID]
Arguments:
[ID] The local endpoint id (auto-detected if omitted)
Options:
-h, --help Print help
spt resources list
The subnet resource-registry projection: `(id, node, status, blurb)` over VISIBLE rows only (hidden endpoints never appear — discovery leaks nothing a viewer couldn't reach)
Usage: spt resources list [OPTIONS]
Options:
--subnet <SUBNET> Limit to one subnet (all member subnets otherwise)
-h, --help Print help
spt suspend
Rest an endpoint cold: 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 suspend <ID>
Arguments:
<ID> The endpoint id (qualified `id@node` reaches a paired peer)
Options:
-h, --help Print help
spt 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 wake <ID>
Arguments:
<ID> The endpoint id (qualified `id@node` reaches a paired peer)
Options:
-h, --help Print help
spt shutdown
Gracefully shut down an agent's own endpoint: soft-stop the listener, then the suspend edge — the final context save fires and persistent shells cascade offline with it
Usage: spt shutdown [ID]
Arguments:
[ID] The endpoint id (defaults to the session's own perch)
Options:
-h, --help Print help
spt api
Harness-contract inbound surface: the entry points a harness's hooks fire to keep spt-core's on-disk state in sync
Usage: spt api [OPTIONS] --adapter <ADAPTER> <COMMAND>
Commands:
seed Harness-hosted startup: record an ephemeral seed keyed by parent pid
listen Consume a seed and hold the perch + relay loop (blocks)
bind Post-spawn bind of a session to its perch
bind-shell Shell-binary bind: the type=Shell flavor of `bind`. Resolves the instance **by link token alone** (the spawn template carries only `{link_token}` — "owner from the link") and flips it online. The credential IS the auth: no token, no bind
state Set activity state busy|idle (also arms the echo-gate sentinel)
echo-gate Manage the echo-gate sentinel directly
poll Drain delivered messages (hook channel). With `--link` this is the shell-flavored relay drain: the link token is the auth, and the drained rows are the shell's MAC-stamped command/text/file frames
worker-start Create a nested worker perch under a parent
worker-stop Tear down a worker perch
worker-poll Drain a worker perch's messages
boundary Rebind the perch to a new session_id, preserving identity (a context clear/compact boundary)
session-end Soft teardown (spool/history preserved); `--erase` hard-wipes
presence Report user/agent presence at this endpoint
driven-by Report which node (if any) is remote-driving this endpoint
history-log Append normalized history (body on stdin) to the native history store
emit Emit a Shell sensory payload to the owner's **live** session. REST-only by definition: never spooled, dropped with a diagnostic when the owner isn't live. The link token is the auth
capability Print the adapter's declared capability (`hostable_types`)
shutdown Graceful live-agent signoff: run the final context save BEFORE teardown, then soft-stop. The `spt shutdown` lifecycle path
owner-shutdown A shell suspends its linked owner directly, bypassing agent comms — gated by the manifest `can_shutdown` pre-consent grant, fail-closed. The firing shell cascades offline with its siblings, by design
help Print this message or the help of the given subcommand(s)
Options:
--adapter <ADAPTER> adapter_name — the calling harness adapter. Required on every `api` call
--manifest <MANIFEST> Path to the adapter's runtime manifest (when the command needs it)
-h, --help Print help
spt api seed
Harness-hosted startup: record an ephemeral seed keyed by parent pid
Usage: spt api --adapter <ADAPTER> seed --pid <PID> --session-id <SESSION_ID>
Options:
--pid <PID>
--session-id <SESSION_ID>
-h, --help Print help
spt api listen
Consume a seed and hold the perch + relay loop (blocks)
Usage: spt api --adapter <ADAPTER> listen [OPTIONS] <ID>
Arguments:
<ID>
Options:
--parent-pid <PARENT_PID> Override the parent-pid anchor (defaults to the self-discovered PPID)
--once Drain backlog + one receive cycle, then exit (testability)
--subnet <SUBNET> Home subnet for a NEW endpoint (required on a multi-subnet node — home is assigned at creation, never guessed)
-h, --help Print help
spt api bind
Post-spawn bind of a session to its perch
Usage: spt api --adapter <ADAPTER> bind [OPTIONS] <ID>
Arguments:
<ID>
Options:
--set-session-id <BIND_SESSION> The session id discovered post-spawn, written into the perch record
--subnet <SUBNET> Home subnet for a NEW endpoint (see `listen`)
--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
Shell-binary bind: the type=Shell flavor of `bind`. Resolves the instance **by link token alone** (the spawn template carries only `{link_token}` — "owner from the link") and flips it online. The credential IS the auth: no token, no bind
Usage: spt api --adapter <ADAPTER> bind-shell --link <LINK_TOKEN>
Options:
--link <LINK_TOKEN> The link token the broker minted at launch
-h, --help Print help
spt api state
Set activity state busy|idle (also arms the echo-gate sentinel)
Usage: spt api --adapter <ADAPTER> state [OPTIONS] <STATE> <ID>
Arguments:
<STATE> [possible values: busy, idle]
<ID>
Options:
--no-gate
--token <TOKEN> Capability token proving association to the target perch
--session-id <SESSION_ID> Session id proving association (matches the perch's info.json)
-h, --help Print help
spt api echo-gate
Manage the echo-gate sentinel directly
Usage: spt api --adapter <ADAPTER> echo-gate [OPTIONS] <ACTION> <ID>
Arguments:
<ACTION> [possible values: set, clear]
<ID>
Options:
--token <TOKEN> Capability token proving association to the target perch
--session-id <SESSION_ID> Session id proving association (matches the perch's info.json)
-h, --help Print help
spt api poll
Drain delivered messages (hook channel). With `--link` this is the shell-flavored relay drain: the link token is the auth, and the drained rows are the shell's MAC-stamped command/text/file frames
Usage: spt api --adapter <ADAPTER> poll [OPTIONS] <ID>
Arguments:
<ID>
Options:
--include-deferred
--link <LINK> Shell link token (the relay command-receipt drain)
--token <TOKEN> Capability token proving association to the target perch
--session-id <SESSION_ID> Session id proving association (matches the perch's info.json)
-h, --help Print help
spt api worker-start
Create a nested worker perch under a parent
Usage: spt api --adapter <ADAPTER> worker-start [OPTIONS] <PARENT> <ID>
Arguments:
<PARENT>
<ID>
Options:
--token <TOKEN> Capability token proving association to the target perch
--session-id <SESSION_ID> Session id proving association (matches the perch's info.json)
-h, --help Print help
spt api worker-stop
Tear down a worker perch
Usage: spt api --adapter <ADAPTER> worker-stop [OPTIONS] <ID>
Arguments:
<ID>
Options:
--token <TOKEN> Capability token proving association to the target perch
--session-id <SESSION_ID> Session id proving association (matches the perch's info.json)
-h, --help Print help
spt api worker-poll
Drain a worker perch's messages
Usage: spt api --adapter <ADAPTER> worker-poll [OPTIONS] <ID>
Arguments:
<ID>
Options:
--token <TOKEN> Capability token proving association to the target perch
--session-id <SESSION_ID> Session id proving association (matches the perch's info.json)
-h, --help Print help
spt api boundary
Rebind the perch to a new session_id, preserving identity (a context clear/compact boundary)
Usage: spt api --adapter <ADAPTER> boundary [OPTIONS] --to-session-id <TO_SESSION> <MODE> <ID>
Arguments:
<MODE> [possible values: clear, compact]
<ID>
Options:
--to-session-id <TO_SESSION> The new session id to rebind the perch to
--token <TOKEN> Capability token proving association to the target perch
--session-id <SESSION_ID> Session id proving association (matches the perch's info.json)
-h, --help Print help
spt api session-end
Soft teardown (spool/history preserved); `--erase` hard-wipes
Usage: spt api --adapter <ADAPTER> session-end [OPTIONS] <ID>
Arguments:
<ID>
Options:
--erase
--token <TOKEN> Capability token proving association to the target perch
--session-id <SESSION_ID> Session id proving association (matches the perch's info.json)
-h, --help Print help
spt api presence
Report user/agent presence at this endpoint
Usage: spt api --adapter <ADAPTER> presence [OPTIONS] <ID>
Arguments:
<ID>
Options:
--token <TOKEN> Capability token proving association to the target perch
--session-id <SESSION_ID> Session id proving association (matches the perch's info.json)
-h, --help Print help
spt api driven-by
Report which node (if any) is remote-driving this endpoint
Usage: spt api --adapter <ADAPTER> driven-by [OPTIONS] <ID>
Arguments:
<ID>
Options:
--token <TOKEN> Capability token proving association to the target perch
--session-id <SESSION_ID> Session id proving association (matches the perch's info.json)
-h, --help Print help
spt api history-log
Append normalized history (body on stdin) to the native history store
Usage: spt api --adapter <ADAPTER> history-log [OPTIONS] <ID>
Arguments:
<ID>
Options:
--token <TOKEN> Capability token proving association to the target perch
--session-id <SESSION_ID> Session id proving association (matches the perch's info.json)
-h, --help Print help
spt api 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 --adapter <ADAPTER> emit --type <TYPE> --link <LINK> <ID> <PAYLOAD>
Arguments:
<ID>
<PAYLOAD> The sensory payload (descriptive text / encoded blob reference)
Options:
--type <TYPE>
--link <LINK> Shell link token (the per-link credential from launch)
-h, --help Print help
spt api capability
Print the adapter's declared capability (`hostable_types`)
Usage: spt api --adapter <ADAPTER> capability
Options:
-h, --help Print help
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 --adapter <ADAPTER> shutdown [OPTIONS] <ID>
Arguments:
<ID>
Options:
--token <TOKEN> Capability token proving association to the target perch
--session-id <SESSION_ID> Session id proving association (matches the perch's info.json)
-h, --help Print help
spt api owner-shutdown
A shell suspends its linked owner directly, bypassing agent comms — gated by the manifest `can_shutdown` pre-consent grant, fail-closed. The firing shell cascades offline with its siblings, by design
Usage: spt api --adapter <ADAPTER> owner-shutdown --link <LINK> <ID>
Arguments:
<ID> The shell instance id (must match the link token's instance)
Options:
--link <LINK> Shell link token (the per-link credential from launch)
-h, --help Print help