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 [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
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
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
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
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
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
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
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
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
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
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
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
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
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
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)
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
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
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
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]
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 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
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
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
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
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
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
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
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
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
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
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
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
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
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
-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 [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
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
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
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
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
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
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
Apply the staged, verified self-update now
Usage: spt update apply [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 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
-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] <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
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
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
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
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)
-h, --help Print help
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
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
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
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
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
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
Create a nested worker perch under a parent
Usage: spt api worker-start [OPTIONS] <PARENT> <ID>
Arguments:
<PARENT>
<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-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
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
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
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
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
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 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
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
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
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
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
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
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
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
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
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
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
-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
--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
-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:
--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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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')