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]
User commands:
adapter Adapter registration: what this node can drive/launch
daemon The per-machine daemon: run, stop, or read node status
grant Consent grant store: gated capabilities held on this node
help Print this message or the help of the given subcommand(s)
notif Inspect and acknowledge notifications
rc Attach a local terminal to a broker-held endpoint PTY
subnet Subnet membership: status, create, show-code
update Self-update operations
Agent commands:
api Harness-contract inbound surface (hook entry points)
endpoint Endpoint operations: list, lifecycle, fork, digest, access
how-to Task-oriented instructions for agents: `how-to <topic>`
ready Become reachable: register the perch and listen (blocks)
ring Send and block for a reply (body read from stdin)
send Send a message (body read from stdin); fire-and-forget
shell Shell instances: mint, list, drive, tear down owned surfaces
whoami Print this session's own perch id
Options:
-h, --help Print help
-V, --version Print version
spt adapter
Adapter registration: what this node can drive/launch.
The node-local registered set (one command for harness and shell adapters). Feeds creation-time
adapter selection, shell discovery, and the self-update ripple.
Usage: spt adapter <COMMAND>
Commands:
add Register an adapter from a local path (a dir holding `manifest.toml`, or the
manifest file itself) or from GitHub (`--github user/repo`, cloned under
`adapters/_github/`). Manifest-first: an invalid manifest registers nothing.
Install is the first update — the declared `[update]` avenue is conducted once
after recording
remove Soft-deregister: hidden from new-creation/discovery; existing and live instances
keep running. The manifest's optional `uninstall` template is conducted only with
--force until quiesce detection lands
list List registered adapters (active and soft-deregistered), each followed by its
shipped + local profiles as composite options
create-profile Create (or overwrite) a **local** profile — a node-local sparse overlay registered
beside the adapter that survives `adapter add` re-registration. The overlay TOML
is read from `--from <file>` or piped stdin (empty = a placeholder profile to
populate later with `set-string`). Refuses a name shadowing a shipped profile, an
invalid name, or an overlay that loosens a consent floor — nothing is written
unless every check passes
delete-profile Delete a **local** profile. Refuses a shipped profile name (adapter-owned,
immutable) and errors if no local file exists
get-string Read a `[strings]` dot-path from an adapter option's merged view
(`<adapter>[:profile] <key.path>`). Resolves through the profile overlay like
every other consumer; prints the value (strings raw, else JSON). Exit 1 if the key
is unset. Strings are **data** — never executed
digest-proof Prove an adapter's `[digest]` extractor against a real log sample (ADR-0019). Runs
the declared extractor over `--sample <log>` (or the declared source) and prints
the parsed contract records, the rendered digest, and **every dropped line with
its reason** — the author-time answer to "`spt endpoint digest` returns nothing"
(no silent empty). Exit 1 if any line drops or nothing parses
set-string Set a `[strings]` dot-path on a **local** profile (`<adapter>:<profile>`). Sugar
over editing the overlay file; refuses a shipped profile and a bare option (a
local target is required — `create-profile` first)
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help (see a summary with '-h')
spt adapter add
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), each followed by its shipped + local
profiles as composite options
Usage: spt adapter list
Options:
-h, --help Print help
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
-h, --help Print help
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 <ADAPTER> <NAME>
Arguments:
<ADAPTER>
<NAME>
Options:
-h, --help Print help
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 <OPTION> <KEY>
Arguments:
<OPTION> `<adapter>` or `<adapter>:<profile>`
<KEY> Dot-separated key path into `[strings]` (e.g. `hook.additionalContext`)
Options:
-h, --help Print help
spt adapter digest-proof
Prove an adapter's `[digest]` extractor against a real log sample (ADR-0019). Runs the declared
extractor over `--sample <log>` (or the declared source) and prints the parsed contract records, the
rendered digest, and **every dropped line with its reason** — the author-time answer to "`spt
endpoint digest` returns nothing" (no silent empty). Exit 1 if any line drops or nothing parses
Usage: spt adapter digest-proof [OPTIONS] <OPTION>
Arguments:
<OPTION> `<adapter>` or `<adapter>:<profile>` (must declare `[digest]`)
Options:
--sample <SAMPLE> A real session-log sample to run the extractor over (recommended)
--session <SESSION> The `{session_id}` to fill into the extractor command (the daemon fills
the live one at runtime). Defaults to a placeholder so a
`{session_id}`-templated extractor — the published shape — proofs; pin a
real id when the file the extractor locates depends on it
-h, --help Print help
spt adapter set-string
Set a `[strings]` dot-path on a **local** profile (`<adapter>:<profile>`). Sugar over editing the
overlay file; refuses a shipped profile and a bare option (a local target is required —
`create-profile` first)
Usage: spt adapter set-string <OPTION> <KEY> <VALUE>
Arguments:
<OPTION> `<adapter>:<profile>` — the local profile to edit
<KEY> Dot-separated key path into `[strings]`
<VALUE> The string value to store
Options:
-h, --help Print help
spt daemon
The per-machine daemon: run, stop, or read node status.
Bare `spt daemon` renders the node status view — daemon state, member subnets, local endpoints (M8
decision 25).
Usage: spt daemon [COMMAND]
Commands:
run Run the per-machine daemon in the FOREGROUND — this process IS the daemon, blocking until
signalled (the service unit's ExecStart, or manual debugging). Never detaches; for a
background daemon use `start`
start Ensure the daemon is up in the background (idempotent, service-aware): a registered OS
service is driven via its manager, else a detached daemon is spawned. Non-blocking
stop Stop the daemon (service-aware: a managed service is stopped via its manager so it does
not auto-restart-fight; else a graceful IPC stop)
status Node status: daemon state, member subnets, local endpoints (the bare `spt daemon` view)
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help (see a summary with '-h')
spt daemon run
Run the per-machine daemon in the FOREGROUND — this process IS the daemon, blocking until signalled
(the service unit's ExecStart, or manual debugging). Never detaches; for a background daemon use
`start`
Usage: spt daemon run
Options:
-h, --help Print help
spt daemon start
Ensure the daemon is up in the background (idempotent, service-aware): a registered OS service is
driven via its manager, else a detached daemon is spawned. Non-blocking
Usage: spt daemon start
Options:
-h, --help Print help
spt daemon stop
Stop the daemon (service-aware: a managed service is stopped via its manager so it does not
auto-restart-fight; else a graceful IPC stop)
Usage: spt daemon stop
Options:
-h, --help Print help
spt daemon status
Node status: daemon state, member subnets, local endpoints (the bare `spt daemon` view)
Usage: spt daemon status
Options:
-h, --help Print help
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 <COMMAND>
Commands:
add Record a grant: `agent` may exercise `capability` on this node. Refuses the reserved
deferred capability ids (remote-exec, instantiate-anywhere) — their gate refuses
unconditionally, so a row would only be a footgun-in-waiting
revoke Remove the exact grant row. Never widens or narrows neighbours: only the named
(capability, agent, qualifier) tuple goes
list List grant rows (all, or one agent's)
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help (see a summary with '-h')
spt grant add
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 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 (see a summary with '-h')
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 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:
--view
Read-only: render output, forward no input
--take
Take control: kick the current controller (a loud notice to them) and drive (REQ-KICK-1).
Use on an endpoint another node controls
-h, --help
Print help (see a summary with '-h')
spt subnet
Subnet membership: status, create, show-code.
A subnet is a private group of paired machines — your agents reach each other across every member
node. Bare `spt subnet` shows the membership status view.
Usage: spt subnet [COMMAND]
Commands:
status Show subnet membership: name, paired nodes, endpoints
create Mint a fresh subnet and print its joining material
show-code Show a subnet's current 6-digit pairing code (+ URI and QR)
join Pair this machine into an existing subnet (guided)
leave Exit a subnet: drop its membership and trust material from this node
prune Remove a dead node identity's trust rows (and registry rows)
revoke Revoke node(s) fleet-wide and rotate the subnet seed
detach Stop serving a held subnet (the daemon keeps running)
attach Resume serving a detached subnet
notify Issue a subnet-wide user notification
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help (see a summary with '-h')
spt subnet status
Show subnet membership: name, paired nodes, endpoints.
Never prints seeds, epochs, or pairing codes. Bare `spt subnet` is the same view.
Usage: spt subnet status [OPTIONS] [NAME]
Arguments:
[NAME]
Limit to one subnet (all member subnets otherwise)
Options:
--nodes
Per-node rows: label, online/offline, [online endpoints/total]
-h, --help
Print help (see a summary with '-h')
spt subnet create
Mint a fresh subnet and print its joining material.
This node becomes the sole seed-holder. Prints the current 6-digit code, the `otpauth://`
provisioning URI, and a terminal QR of it. Gated behind OS elevation (the seed-reveal path).
Usage: spt subnet create <NAME>
Arguments:
<NAME>
The new subnet's name
Options:
-h, --help
Print help (see a summary with '-h')
spt subnet show-code
Show a subnet's current 6-digit pairing code (+ URI and QR).
The re-provisioning surface: prints the same joining material as `create` — current code,
`otpauth://` URI, terminal QR, expiry. Gated behind OS elevation (or read the code from your
authenticator app). With no name the node's sole subnet is used; if it holds several, the name is
required (never guessed).
Usage: spt subnet show-code [NAME]
Arguments:
[NAME]
Which subnet's code to show. Required only when the node holds several
Options:
-h, --help
Print help (see a summary with '-h')
spt subnet join
Pair this machine into an existing subnet (guided).
Finds a member machine over LAN + relay rendezvous and runs the code-authenticated pairing ceremony
against it. Prompts for the name and code when omitted (interactive terminals). Gated behind OS
elevation — joining enrolls this whole machine.
Usage: spt subnet join [OPTIONS] [NAME]
Arguments:
[NAME]
The subnet to join (as named on the member machine)
Options:
--code <CODE>
The current 6-digit code (`spt subnet show-code` on a member machine, or your
authenticator app)
-h, --help
Print help (see a summary with '-h')
spt subnet leave
Exit a subnet: drop its membership and trust material from this node.
Removes the subnet's seed, its trust rows, its serve-state, and its registry snapshot here. Gated
behind OS elevation (membership exit destroys trust material). The remaining members still hold the
old seed — rotate it there if this machine should not rejoin.
Usage: spt subnet leave <NAME>
Arguments:
<NAME>
The held subnet to leave
Options:
-h, --help
Print help (see a summary with '-h')
spt subnet prune
Remove a dead node identity's trust rows (and registry rows).
The cleanup verb for a machine that re-paired under a new identity or is gone for good: its stale
trust rows cost a dial every pump tick. Takes a full pubkey hex, an unambiguous prefix, or a node
label. Gated behind OS elevation (trust mutation).
Usage: spt subnet prune <NODE>
Arguments:
<NODE>
The dead identity: pubkey hex, unambiguous prefix, or label
Options:
-h, --help
Print help (see a summary with '-h')
spt subnet revoke
Revoke node(s) fleet-wide and rotate the subnet seed.
The real revocation (vs `prune`'s local cleanup): writes a PROPAGATING roster tombstone now — so
every member drops the node within a roster round — then schedules one seed rotation at the close of
a coalescing window (default 1h); further revokes in the window join the same rotation (one epoch
bump). Benign offliners auto-heal across the rotation (re-seed grace); the revoked node is locked
out and must re-pair. Each target is a pubkey hex, an unambiguous prefix, or a label. Gated behind
OS elevation.
Usage: spt subnet revoke [OPTIONS] <NODES>...
Arguments:
<NODES>...
The identities to revoke: pubkey hex, unambiguous prefix, or label
Options:
--force-rotate-seed
Rotate the seed immediately instead of at the window's close — the compromised-node path
(a benign offliner may then fall behind and must re-pair rather than re-seed)
-h, --help
Print help (see a summary with '-h')
spt subnet detach
Stop serving a held subnet (the daemon keeps running).
The membership (seed) stays on disk, but this node neither advertises into nor connects to the
subnet — pairing responder, rendezvous meet, and registry gossip all skip it. Takes effect within
one pump cadence; `spt subnet attach` reverses it.
Usage: spt subnet detach [OPTIONS] <NAME>
Arguments:
<NAME>
The held subnet to stop serving
Options:
--save
Also persist as the startup default (survives daemon restarts)
-h, --help
Print help (see a summary with '-h')
spt subnet attach
Resume serving a detached subnet.
Advertising + connecting restart within one pump cadence.
Usage: spt subnet attach [OPTIONS] <NAME>
Arguments:
<NAME>
The held subnet to serve again
Options:
--save
Also persist as the startup default (survives daemon restarts)
-h, --help
Print help (see a summary with '-h')
spt subnet notify
Issue a subnet-wide user notification.
Produced into the replicated notification spool and first-fired at the user's most-recently-active
endpoint in that subnet. Body from the trailing arg, or stdin when omitted. Targets the calling
endpoint's HOME subnet unless `--target` names another (M8 decision 25: no resolvable home + no
`--target` = refuse).
Usage: spt subnet notify [OPTIONS] [BODY]
Arguments:
[BODY]
Notification body (read from stdin when omitted)
Options:
--target <TARGET>
Target subnet (defaults to the calling endpoint's home subnet)
--from <FROM>
Issuer endpoint id (auto-detected from session if omitted)
-h, --help
Print help (see a summary with '-h')
spt update
Self-update operations.
`apply` is the explicit ack named by the update-consent notification; it re-verifies the staged
release before touching the live daemon.
Usage: spt update <COMMAND>
Commands:
apply Apply the staged, verified self-update now
fetch Fetch the latest signed release from the GitHub origin and stage it (then `spt update
apply`). Bootstraps a node with no peer to pull from
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help (see a summary with '-h')
spt update apply
Apply the staged, verified self-update now
Usage: spt update apply
Options:
-h, --help Print help
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
--tag <TAG> Fetch a specific release tag (e.g. `v0.3.1`) instead of the latest
-h, --help Print help
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] --adapter <ADAPTER> <COMMAND>
Commands:
seed Harness-hosted startup: record an ephemeral seed keyed by parent pid
listen Consume a seed and hold the perch + relay loop (blocks)
bind Post-spawn bind of a session to its perch
bind-shell Shell-binary bind: the type=Shell flavor of `bind`. Resolves the instance **by
link token alone** (the spawn template carries only `{link_token}` — "owner from
the link") and flips it online. The credential IS the auth: no token, no bind
state Set activity state busy|idle (also arms the echo-gate sentinel)
echo-gate Manage the echo-gate sentinel directly
poll Drain delivered messages (hook channel). With `--link` this is the shell-flavored
relay drain: the link token is the auth, and the drained rows are the shell's
MAC-stamped command/text/file frames
worker-start Create a nested worker perch under a parent
worker-stop Tear down a worker perch
worker-poll Drain a worker perch's messages
boundary Rebind the perch to a new session_id, preserving identity (a context clear/compact
boundary)
session-end Soft teardown (spool/history preserved); `--erase` hard-wipes
presence Report user/agent presence at this endpoint
driven-by Report which node (if any) is remote-driving this endpoint
history-log Append normalized history (body on stdin) to the native history store
digest-entry Push one digest-record (the published contract JSON line, on stdin) for a log-less
adapter — appended to the perch's digest store, tailed by the session-digest
projection (ADR-0008 amendment, REQ-TERM-4)
emit Emit a Shell sensory payload to the owner's **live** session. REST-only by
definition: never spooled, dropped with a diagnostic when the owner isn't live.
The link token is the auth
capability Print the adapter's declared capability (`hostable_types`)
hint Keyword hints: the full user message arrives on **stdin**; emit at most one
matched hint line (declaration order, first unseen wins) for the adapter's context
channel. The per-session seen-set fires each hint once per `--session` (a `/clear`
= a new session = re-armed). Needs `--manifest`
shutdown Graceful live-agent signoff: run the final context save BEFORE teardown, then
soft-stop. The `spt shutdown` lifecycle path
owner-shutdown A shell suspends its linked owner directly, bypassing agent comms — gated by the
manifest `can_shutdown` pre-consent grant, fail-closed. The firing shell cascades
offline with its siblings, by design
help Print this message or the help of the given subcommand(s)
Options:
--adapter <ADAPTER>
adapter_name — the calling harness adapter. Required on every `api` call
--manifest <MANIFEST>
Path to the adapter's runtime manifest (when the command needs it)
-h, --help
Print help (see a summary with '-h')
spt api seed
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`)
--type <ENDPOINT_TYPE> The endpoint type tag (info.json `state`). Defaults to
`live_agent` (the agent host); a non-agent endpoint — e.g. a
`gateway` — binds with its own open-type tag
(REQ-EP-1/REQ-EP-6). A revive keeps the prior type unless
this overrides it [default: live_agent]
--token <TOKEN> Capability token proving association to the target perch
--session-id <SESSION_ID> Session id proving association (matches the perch's
info.json)
-h, --help Print help
spt api bind-shell
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 digest-entry
Push one digest-record (the published contract JSON line, on stdin) for a log-less adapter —
appended to the perch's digest store, tailed by the session-digest projection (ADR-0008 amendment,
REQ-TERM-4)
Usage: spt api --adapter <ADAPTER> digest-entry [OPTIONS] <ID>
Arguments:
<ID>
Options:
--token <TOKEN> Capability token proving association to the target perch
--session-id <SESSION_ID> Session id proving association (matches the perch's info.json)
-h, --help Print help
spt api emit
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 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 --adapter <ADAPTER> hint --session <SESSION>
Options:
--session <SESSION> The harness session id keying the once-per-session seen-set
-h, --help Print help
spt api shutdown
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
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 [COMMAND]
Commands:
list Merged endpoint listing (the bare `spt endpoint` view)
run Bring up an spt-hosted harness endpoint into a broker-held PTY
fork Fork an endpoint into another subnet as a NEW identity
suspend Rest an endpoint cold (the suspend edge)
wake Wake a resting endpoint in place
shutdown Gracefully shut down an agent's own endpoint
stop Soft-stop a perch (spool preserved)
rename Rename an endpoint's logical id across its on-disk state
digest Show a session's live activity buffer (session digest)
access Endpoint access whitelist for unsolicited off-node inbound
description The endpoint's service-description blurb (ex-`resources`)
role Show or set the endpoint's durable **role** — a broad statement of purpose stored in
the mind (`tracked/agents/<id>/live-role.md`), which replicates with the agent and
renders FIRST at start-transition context injection. Bare `role` prints the current
role; `--overwrite <file>` replaces it from a file. This is the **sole writer** of
the role — no automated path (reconcile / echo-commune / signoff) ever mutates it
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help (see a summary with '-h')
spt endpoint list
Merged endpoint listing (the bare `spt endpoint` view).
Default: every member subnet's endpoints grouped by subnet, with this session's own endpoint pinned
at the top. `--local` lists this node's perches instead (id, state, address, ready, alive);
`--subnet` filters to one subnet; `--detail` adds each endpoint's description blurb (the
resource-registry yellow-pages projection).
Usage: spt endpoint list [OPTIONS]
Options:
--local
List this node's local perches instead of the subnet view
--subnet <SUBNET>
Limit the subnet view to one subnet
--detail
Add each endpoint's description blurb to the rows
-h, --help
Print help (see a summary with '-h')
spt endpoint run
Bring up an spt-hosted harness endpoint into a broker-held PTY.
Spawns the adapter's `[session.self]` command into a broker-owned PTY (the harness self-registers
its perch on bind), then starts / attaches / views per the terminal-action flag. The endpoint id
rides argv so the harness binds to exactly it. This is the non-interactive core (the interactive
picker lands in a later wave); the flags cover every terminal action so a `spt-<id>` shortcut can
bake a fully non-interactive launch.
Usage: spt endpoint run [OPTIONS]
Options:
--adapter <ADAPTER>
The harness adapter to host: `<adapter>[:profile]` (must be a registered `kind="harness"`
adapter on this node). Omit (with --id) to launch the interactive picker
--id <ID>
The endpoint id to bring up (charset: alphanumeric, `-`, `_`). Omit (with --adapter) to
launch the interactive picker
--create
Mint a fresh session (the default; explicit so a non-interactive shortcut can bake
create-vs-resume). Conflicts with --resume
--resume <RESUME>
Resume a prior session id instead of minting a fresh one
--start
Start the endpoint and return immediately (no attach)
--attach
Attach a local terminal after bringup (the default action)
--view
Attach read-only after bringup (watch; forward no input)
-h, --help
Print help (see a summary with '-h')
spt endpoint fork
Fork an endpoint into another subnet as a NEW identity.
Home subnets are immutable — fork is the cross-subnet move, never a re-home. Seeds the fork with a
one-time copy of the source's mind (live + project tiers); the two diverge immediately (no ongoing
sync). The source is untouched unless --delete-source. Same-node only today (one node holds one
perch per name, so a local fork needs a new id).
Usage: spt endpoint fork [OPTIONS] --subnet <SUBNET> <SRC> <NEW_ID>
Arguments:
<SRC>
The source endpoint (must exist on this node)
<NEW_ID>
The fork's id (must differ from the source on the same node)
Options:
--subnet <SUBNET>
The fork's home subnet — the target (must be a member)
--delete-source
Delete the source endpoint (perch + tracked mind) after the copy
-h, --help
Print help (see a summary with '-h')
spt endpoint suspend
Rest an endpoint cold (the suspend edge).
The resting state machine's suspend edge. From dormant — or straight from active, in which case the
final context save still fires first. Accepts a qualified `id@node` to suspend an instance on a
paired peer.
Usage: spt endpoint suspend <ID>
Arguments:
<ID>
The endpoint id (qualified `id@node` reaches a paired peer)
Options:
-h, --help
Print help (see a summary with '-h')
spt endpoint wake
Wake a resting endpoint in place.
Re-activates the existing seat (state's already there — no fresh spawn), resurfaces undismissed
notifications, and requests an immediate context freshness pull from trusted peers. Accepts a
qualified `id@node` for an instance on a paired peer.
Usage: spt endpoint wake <ID>
Arguments:
<ID>
The endpoint id (qualified `id@node` reaches a paired peer)
Options:
-h, --help
Print help (see a summary with '-h')
spt endpoint shutdown
Gracefully shut down an agent's own endpoint.
Soft-stops the listener, then the suspend edge — the final context save fires and persistent shells
cascade offline with it.
Usage: spt endpoint shutdown [ID]
Arguments:
[ID]
The endpoint id (defaults to the session's own perch)
Options:
-h, --help
Print help (see a summary with '-h')
spt endpoint stop
Soft-stop a perch (spool preserved).
Removes the ready marker and unregisters the perch; the spool is preserved.
Usage: spt endpoint stop <ID>
Arguments:
<ID>
Perch id to stop
Options:
-h, --help
Print help (see a summary with '-h')
spt endpoint rename
Rename an endpoint's logical id across its on-disk state.
Rippled everywhere the id appears: the endpoint's perch dir, its nested companion/worker perches,
and every record naming it. Refuses while the perch is live (stop it first).
Usage: spt endpoint rename <OLD_ID> <NEW_ID>
Arguments:
<OLD_ID>
The endpoint's current (bare) id
<NEW_ID>
The new (bare) id — charset-validated; `:`/`@` are reserved
Options:
-h, --help
Print help (see a summary with '-h')
spt endpoint digest
Show a session's live activity buffer (session digest).
The at-a-glance "what is this agent doing now" view — a projection of the endpoint's normalized
session logs. Pulls a snapshot, or `--follow`s the delta-stream. Local endpoints only.
Usage: spt endpoint digest [OPTIONS] <ID>
Arguments:
<ID>
The (local) endpoint id to read
Options:
--follow
Stream live changes instead of a one-shot snapshot (Ctrl-C to stop)
--json
Emit structured JSON instead of the human-glanceable render
-h, --help
Print help (see a summary with '-h')
spt endpoint access
Endpoint access whitelist for unsolicited off-node inbound.
Controls which origin nodes may send an endpoint unsolicited off-node inbound. Absent entry = open;
`allow` flips the endpoint to restricted; revoking the last node leaves it locked down; `open`
deletes the restriction.
Usage: spt endpoint access <COMMAND>
Commands:
allow Whitelist a node for an endpoint (creates the restriction if absent)
revoke Remove a node from an endpoint's whitelist. Never widens: revoking the last node leaves
the endpoint locked down (all unsolicited refused)
open Delete an endpoint's restriction entirely — back to default-open
list List restrictions (all endpoints, or one)
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help (see a summary with '-h')
spt endpoint description
The endpoint's service-description blurb (ex-`resources`).
Bare `description` shows your own; `set` authors it. The cross-node projection over every visible
endpoint is `endpoint list --detail`.
Usage: spt endpoint description [COMMAND]
Commands:
set Author this endpoint's blurb (the agent refines its own at runtime; an empty string clears
it back to the node-config seed)
show Show a local endpoint's authored blurb (the bare `description` view)
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help (see a summary with '-h')
spt endpoint role
Show or set the endpoint's durable **role** — a broad statement of purpose stored in the mind
(`tracked/agents/<id>/live-role.md`), which replicates with the agent and renders FIRST at
start-transition context injection. Bare `role` prints the current role; `--overwrite <file>`
replaces it from a file. This is the **sole writer** of the role — no automated path (reconcile /
echo-commune / signoff) ever mutates it
Usage: spt endpoint role [OPTIONS]
Options:
--id <ID> Which local endpoint (auto-detected from the session if omitted)
--overwrite <OVERWRITE> Replace the role with the contents of <file> (the only writer)
-h, --help Print help
spt how-to
Task-oriented instructions for agents: `how-to <topic>`.
The binary's own usage guidance, written for an agent to read and follow. Bare `how-to` lists the
topics.
Usage: spt how-to [TOPIC]
Arguments:
[TOPIC]
The topic to print (omit to list available topics)
Options:
-h, --help
Print help (see a summary with '-h')
spt ready
Become reachable: register the perch and listen (blocks).
Drains the spooled backlog first; each received message prints to stdout. With --once, runs a single
drain+receive cycle and exits.
Usage: spt ready [OPTIONS] <ID>
Arguments:
<ID>
This agent's perch id
Options:
--once
Run a single drain+receive cycle, then exit (one-shot fallback for harnesses that cannot
host a long-running listener)
--subnet <SUBNET>
Home subnet for a NEW endpoint (required on a multi-subnet node — home is assigned at
creation, never guessed)
-h, --help
Print help (see a summary with '-h')
spt ring
Send and block for a reply (body read from stdin).
The reply body is printed to stdout; gives up after --timeout seconds.
Usage: spt ring [OPTIONS] <TARGET>
Arguments:
<TARGET>
Target perch id
Options:
--from <FROM>
Sender id (auto-detected from session if omitted)
--timeout <TIMEOUT>
Seconds to wait for a reply before giving up
[default: 60]
-h, --help
Print help (see a summary with '-h')
spt send
Send a message (body read from stdin); fire-and-forget
Usage: spt send [OPTIONS] [TARGET]
Arguments:
[TARGET] Target perch id. May be omitted when --reply-to is given
Options:
--from <FROM> Sender id carried structurally as the message `from` (auto-detected
from session if omitted)
--reply-to <REPLY_TO> Reply to this sender; sets the target and labels output REPLIED
--deferred Spool only (deferred / hook channel) — no live wake
--user-msg Request the `user-msg` type (the user's authority). Honored only from a
user-backed origin (a Gateway endpoint, or the local user's own CLI);
an agent-family sender is re-stamped to plain `msg` (REQ-MSG-5)
-h, --help Print help
spt shell
Shell instances: mint, list, drive, tear down owned surfaces.
The driven surfaces this agent owns. `spawn` MINTS a new instance identity (`<adapter>-<n>`) — it is
not the online switch; bringing an existing offline instance back is `relink` / `persistent` / wake.
Usage: spt shell <COMMAND>
Commands:
spawn Mint a NEW shell instance of a registered `kind="shell"` adapter: canonical id
`<adapter>-<n>` (smallest free n; teardown frees slots), starting offline (the launch +
bind handshake brings it online)
list List this owner's instances: canonical id, alias, adapter, status
teardown Destroy an instance (perch removed; mint slot + alias freed)
rename Set/replace an instance's alias (owner-unique)
cmd Drive the shell with a typed capability command (the durable command channel): the op +
positional args are vocabulary-checked against the manifest's `[shell.capabilities]`,
spooled on the shell perch, and drained by the manifest's `command_receipt` mode (relay
/ stdin)
send Send a text and/or file payload down the durable 2-way text+file channel (agent→shell;
the shell answers via ordinary `spt send`). File transfers are progress-queryable by
xfer id
relink Bring an existing offline (persistent) instance back online: re-spawns the binary with a
fresh link token; the perch onlines at its bind
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help (see a summary with '-h')
spt shell spawn
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 whoami
Print this session's own perch id.
Resolved from $OWL_SESSION_ID / $SPT_AGENT_ID.
Usage: spt whoami
Options:
-h, --help
Print help (see a summary with '-h')