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: http://localhost:5474 (spt
docs url)
Usage: spt [OPTIONS] [COMMAND]
User commands:
adapter Adapter registration: what this node can drive/launch
docs The node-local docs: open them in your browser, or print their URL
fetch Pull a served file to a local path
go Take me to this endpoint — whatever state it is in
grant Consent grant store: gated capabilities held on this node
help Print this message or the help of the given subcommand(s)
install Self-install this binary onto the node (the bootstrap path)
knock Ask an endpoint to let you reach it, and answer the asks you receive
msg Read one message back by its short-ID (spt msg show <id>)
node The per-machine supervisor: run, stop, or status [aliases: daemon]
notif Inspect and acknowledge notifications
rc Attach a local terminal to a broker-held endpoint PTY
serve Register local files and directories for node-prefixed HTTP serving
subnet Subnet membership: status, create, show-code
update Self-update: bare spt update brings the whole node current
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)
seal Wax seals: mint a citable proof of user authority over content
send Send a message (body read from stdin); fire-and-forget
shell Shell instances: mint, list, drive, tear down owned surfaces
whoami Who am I? This session's own endpoint, identity-only and fast
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
hints Print a registered adapter's declared [[hints]] — for each, the keywords that
fire it and the text it surfaces. This is the command a shell-hint teaser names:
the teaser tells an agent that a hint exists, and this shows the text without
instantiating anything. Resolves the option's merged view, so a profile's overlay
is what prints
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
service The adapter's resident service: the background process spt's daemon supervises on
the adapter's behalf when its manifest declares a [service] section. Read-only
— list and status report what the daemon is supervising and never change 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 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 hints
Print a registered adapter's declared [[hints]] — for each, the keywords that fire it and the text
it surfaces. This is the command a shell-hint teaser names: the teaser tells an agent that a hint
exists, and this shows the text without instantiating anything. Resolves the option's merged view,
so a profile's overlay is what prints
Usage: spt adapter hints [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] Adapters to update, comma-separated (all gh_release adapters if omitted). Names are
validated before anything updates; a registered adapter without a gh_release avenue (e.g.
a local-path dev registration) is skipped loudly, not failed
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 adapter service
The adapter's resident service: the background process spt's daemon supervises on the adapter's
behalf when its manifest declares a [service] section. Read-only — list and status report what
the daemon is supervising and never change it.
(Distinct from spt node's "service" wording, which means the OS service manager hosting the spt
daemon itself.)
Usage: spt adapter service [OPTIONS] <COMMAND>
Commands:
list List every registered adapter's declared service and its supervision state: the declared
start trigger, whether it is running, whether an update is holding it, and any relaunch
suppression with the captured startup output behind it
status Report one adapter option's service state (<adapter> or <adapter>:<profile>). Exit 1
if nothing declares or supervises 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 adapter service list
List every registered adapter's declared service and its supervision state: the declared start
trigger, whether it is running, whether an update is holding it, and any relaunch suppression with
the captured startup output behind it.
The daemon is the only source: it holds the child handles. With no daemon running there is no answer
to give, and none is invented.
Usage: spt adapter service 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 (see a summary with '-h')
spt adapter service status
Report one adapter option's service state (<adapter> or <adapter>:<profile>). Exit 1 if nothing
declares or supervises it
Usage: spt adapter service status [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 docs
The node-local docs: open them in your browser, or print their URL.
Every release ships a version-matched docs bundle; the daemon serves it on loopback. Bare spt docs
opens the browser; spt docs url prints the resolved URL for tools and agents.
Usage: spt docs [OPTIONS] [COMMAND]
Commands:
url Print the resolved node-local docs URL (honoring port overrides)
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 docs url
Print the resolved node-local docs URL (honoring port overrides)
Usage: spt docs url [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 fetch
Pull a served file to a local path.
spt fetch <node>/f/<name> [dest]. Exit 0 wrote the file, 3 the owner refused it (an access
decision — do not retry), 1 everything else.
Usage: spt fetch [OPTIONS] <URL> [DEST]
Arguments:
<URL>
A full node-prefixed URL, or the <node>/f/<name> shorthand
[DEST]
Where to write it; defaults to the served name in this directory
Options:
--force
Overwrite an existing destination
--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 go
Take me to this endpoint — whatever state it is in.
The one verb for "put me at the controls of <id>". It reads the endpoint's state and does whatever
that state needs before handing you the terminal: attaches when it is already up, asks before
kicking a controller off it, wakes it when it is resting, resumes its latest session when it is
offline, and starts its first session when it has never run one. The lifecycle verbs under
endpoint (create/start/resume) are the same steps taken one at a time, without the
attach.
Usage: spt go [OPTIONS] <ID>
Arguments:
<ID>
The endpoint id to be taken to
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
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 install
Self-install this binary onto the node (the bootstrap path).
Run it from a downloaded release binary: it places itself at the canonical install dir, registers
that dir on your user PATH, and refuses a binary built for another platform. First-run identity and
daemon start happen on the first normal invocation, as always. Non-interactive and idempotent —
re-running is safe.
Usage: spt install [OPTIONS]
Options:
--dir <DIR>
Install dir override (default: the spt home's bin dir)
--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-path
Skip user-PATH registration
--expect-sha256 <HEX>
Refuse unless THESE bytes hash to this sha256 — the anchor the LAN bootstrap listener
prints. The hash of what you downloaded is printed BEFORE it is compared, so an operator
can read both
--release-json <PATH>
The .release.json provenance sidecar downloaded beside the binary. Its signature and
this platform's digest are re-verified against THIS binary's built-in release keys before
anything is written
-h, --help
Print help (see a summary with '-h')
spt knock
Ask an endpoint to let you reach it, and answer the asks you receive.
Bare spt knock <target> sends the request; it lands in that endpoint's inbox and is never pushed
at its agent — someone has to look. spt knock list shows what is waiting for you, approve and
deny answer it. new-code mints an invite you can hand out, and redeem presents one you were
given.
A subcommand name always wins over the bare target, so an endpoint whose id is send, list,
approve, deny, new-code or redeem is knocked as spt knock send <id>.
Usage: spt knock [OPTIONS] [TARGET] [COMMAND]
Commands:
send Ask target to let you reach it
list Show the knocks waiting for you
approve Approve a waiting knock
deny Refuse a waiting knock
new-code Mint an invite code that grants the named surfaces when redeemed
redeem Present an invite code you were given
help Print this message or the help of the given subcommand(s)
Arguments:
[TARGET]
The endpoint to ask — the bare form of knock send
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
--surfaces <S1,S2|ALL>
Surfaces to request: a comma list, or ALL. Case is ignored; an unrecognised name is
refused and the known ones are listed. A knock asks for MSG by default — only use
--surfaces if you need more than MSG
--for <ENDPOINT>
Knock on behalf of a local endpoint (verified to exist here)
--send-only
Ask to reach them, and deliberately not the reverse. Required unless you choose
--send-receive: a knock must say which way reach runs for YOUR side
--send-receive
Also open YOUR OWN side to them, so reach runs both ways the moment they answer. Written
by your own daemon, only for the endpoint you knocked, and only once
-h, --help
Print help (see a summary with '-h')
Control surfaces:
MSG — direct messages (a grant binds the single sender)
RC_VIEW — read-only terminal viewing (a grant admits the whole machine)
RC_ATTACH — interactive terminal control (a grant admits the whole machine)
DIGEST — cross-node digest pull (a grant admits the whole machine)
WAKE — waking a resting endpoint (a grant admits the whole machine)
SUSPEND — suspending a running endpoint (a grant admits the whole machine)
SHELL_LINK — driving a linked shell (a grant admits the whole machine)
DISCOVER — being found: resolve, advertise, and the resources blurb (a grant admits the whole
machine)
WEB — reading served resources over HTTP (a grant admits the whole machine)
FORK — forking this endpoint, mind and all (a grant admits the whole machine)
spt knock send
Ask target to let you reach it
Usage: spt knock send [OPTIONS] <TARGET>
Arguments:
<TARGET> The endpoint to ask
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
--surfaces <S1,S2|ALL> Surfaces to request: a comma list, or ALL. Case is ignored; an
unrecognised name is refused and the known ones are listed. A knock
asks for MSG by default — only use --surfaces if you need more than
MSG
--for <ENDPOINT> Knock on behalf of a local endpoint (verified to exist here)
--send-only Ask to reach them, and deliberately not the reverse. Required unless
you choose --send-receive: a knock must say which way reach runs for
YOUR side
--send-receive Also open YOUR OWN side to them, so reach runs both ways the moment
they answer. Written by your own daemon, only for the endpoint you
knocked, and only once
-h, --help Print help
Control surfaces:
MSG — direct messages (a grant binds the single sender)
RC_VIEW — read-only terminal viewing (a grant admits the whole machine)
RC_ATTACH — interactive terminal control (a grant admits the whole machine)
DIGEST — cross-node digest pull (a grant admits the whole machine)
WAKE — waking a resting endpoint (a grant admits the whole machine)
SUSPEND — suspending a running endpoint (a grant admits the whole machine)
SHELL_LINK — driving a linked shell (a grant admits the whole machine)
DISCOVER — being found: resolve, advertise, and the resources blurb (a grant admits the whole
machine)
WEB — reading served resources over HTTP (a grant admits the whole machine)
FORK — forking this endpoint, mind and all (a grant admits the whole machine)
spt knock list
Show the knocks waiting for you
Usage: spt knock list [OPTIONS]
Options:
--for <ENDPOINT> Show another local endpoint's inbox (yours by default)
--json
-h, --help Print help
Control surfaces:
MSG — direct messages (a grant binds the single sender)
RC_VIEW — read-only terminal viewing (a grant admits the whole machine)
RC_ATTACH — interactive terminal control (a grant admits the whole machine)
DIGEST — cross-node digest pull (a grant admits the whole machine)
WAKE — waking a resting endpoint (a grant admits the whole machine)
SUSPEND — suspending a running endpoint (a grant admits the whole machine)
SHELL_LINK — driving a linked shell (a grant admits the whole machine)
DISCOVER — being found: resolve, advertise, and the resources blurb (a grant admits the whole
machine)
WEB — reading served resources over HTTP (a grant admits the whole machine)
FORK — forking this endpoint, mind and all (a grant admits the whole machine)
spt knock approve
Approve a waiting knock
Usage: spt knock approve [OPTIONS] <ID>
Arguments:
<ID> The knock id, as shown by spt knock 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
--surfaces <S1,S2> Grant exactly these surfaces (comma list). Omit with --approve-requested
to grant what was asked for. Case is ignored; an unrecognised name is
refused and the known ones are listed
--approve-requested Grant precisely what the knock requested
--admit-node Confirm a grant that admits the knocker's whole machine — needed when a
requested surface carries no proven sender
--monic <MESSAGE> Record a standing note about the knocker in your own mind, imparted when
the approval lands. A note you already hold about them wins — it is kept
and named rather than replaced
-h, --help Print help
Control surfaces:
MSG — direct messages (a grant binds the single sender)
RC_VIEW — read-only terminal viewing (a grant admits the whole machine)
RC_ATTACH — interactive terminal control (a grant admits the whole machine)
DIGEST — cross-node digest pull (a grant admits the whole machine)
WAKE — waking a resting endpoint (a grant admits the whole machine)
SUSPEND — suspending a running endpoint (a grant admits the whole machine)
SHELL_LINK — driving a linked shell (a grant admits the whole machine)
DISCOVER — being found: resolve, advertise, and the resources blurb (a grant admits the whole
machine)
WEB — reading served resources over HTTP (a grant admits the whole machine)
FORK — forking this endpoint, mind and all (a grant admits the whole machine)
spt knock deny
Refuse a waiting knock
Usage: spt knock deny [OPTIONS] <ID>
Arguments:
<ID> The knock id, as shown by spt knock 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 knock new-code
Mint an invite code that grants the named surfaces when redeemed
Usage: spt knock new-code [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
--surfaces <S1,S2|ALL> Surfaces the code grants: a comma list, or ALL. Case is ignored; an
unrecognised name is refused and the known ones are listed
--for-node Mint a NODE-target code (engine room only)
--admit-node Acknowledge that redeeming this code admits the redeemer's whole
MACHINE. Required when the code grants a surface that carries no
proven sender, because such a surface can only bind a node subject
--subnet <NAME[,NAME…]> Which of your subnets to seal the code to — a comma list, or repeat
the flag. OMIT IT to seal for every subnet you belong to, which is
the default. A redeemer must share one of the sealed subnets to read
the code's route at all, so naming fewer narrows who can redeem
--monic <MESSAGE> Record a standing note about whoever redeems this code, imparted into
your own mind when they do
-h, --help Print help
Control surfaces:
MSG — direct messages (a grant binds the single sender)
RC_VIEW — read-only terminal viewing (a grant admits the whole machine)
RC_ATTACH — interactive terminal control (a grant admits the whole machine)
DIGEST — cross-node digest pull (a grant admits the whole machine)
WAKE — waking a resting endpoint (a grant admits the whole machine)
SUSPEND — suspending a running endpoint (a grant admits the whole machine)
SHELL_LINK — driving a linked shell (a grant admits the whole machine)
DISCOVER — being found: resolve, advertise, and the resources blurb (a grant admits the whole
machine)
WEB — reading served resources over HTTP (a grant admits the whole machine)
FORK — forking this endpoint, mind and all (a grant admits the whole machine)
spt knock redeem
Present an invite code you were given
Usage: spt knock redeem [OPTIONS] <CODE>
Arguments:
<CODE> The code
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
--send-only Take the reach the code grants, and deliberately not the reverse. Required
unless you choose --send-receive
--send-receive Also open YOUR OWN side to the code's target, armed against this code before
it is presented and written only if the redemption is proven. A refusal
disarms it; no answer leaves it armed
-h, --help Print help
spt msg
Read one message back by its short-ID (spt msg show <id>)
Usage: spt msg [OPTIONS] <COMMAND>
Commands:
show Render one message by its short-ID, with its attachment links
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
spt msg show
Render one message by its short-ID, with its attachment links
Usage: spt msg show [OPTIONS] <ID>
Arguments:
<ID> The 8-character (or longer, if it lengthened) short-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
spt node
The per-machine supervisor: run, stop, or status.
Bare spt node renders the node status view — daemon state, member subnets, local endpoints (M8
decision 25).
spt daemon is the deprecated alias of this command; prefer spt node. Both spellings parse to the
identical command, subcommand for subcommand. The alias is not scheduled for removal: installed OS
service units and scheduled-task rungs on every deployed machine already carry spt daemon run, and
renaming the verb does not rewrite them, so removal is blocked on an install-artifact migration.
Usage: spt node [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. Also
LIFTS a standing operator stop — this is how a stopped daemon comes back
stop Stop the daemon (service-aware: a managed service is stopped via its manager so it does
not auto-restart-fight; else a graceful IPC stop). Refuses with a warning if it hosts
live sessions (they would be killed) — pass --force to stop anyway. The stop STICKS:
implicit auto-start (the spt api anchor every harness hook shares) declines to bring
the daemon back and prints "daemon stopped by operator — spt node start to resume", until
you explicitly run spt node start (or an update applies and restarts it by design)
status Node status: daemon state, member subnets, local endpoints (the bare spt node view)
access Node-tier access roster: the entities this node's node-scope rules name, the machine's
own mode, and the captured subnet modes — the tier every hosted endpoint falls through
to. Per-endpoint rosters live on spt endpoint access
refresh Restart the daemon's coordinator process in place — no binary change, no stop/start.
Hosted terminals and the network layer keep running untouched; only the coordinator
cycles. The recovery verb for a stuck coordinator (e.g. endpoint bringup wedged) that
previously needed a full daemon stop/start killing every hosted session
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 node 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 node 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 node 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. Also LIFTS a standing
operator stop — this is how a stopped daemon comes back
Usage: spt node 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 node stop
Stop the daemon (service-aware: a managed service is stopped via its manager so it does not
auto-restart-fight; else a graceful IPC stop). Refuses with a warning if it hosts live sessions
(they would be killed) — pass --force to stop anyway. The stop STICKS: implicit auto-start (the `spt
api` anchor every harness hook shares) declines to bring the daemon back and prints "daemon stopped
by operator — spt node start to resume", until you explicitly run spt node start (or an update
applies and restarts it by design)
Usage: spt node stop [OPTIONS]
Options:
--force Stop even when the daemon hosts live sessions (which the stop kills). Without it, a
daemon with live hosted sessions refuses and names them
--json Emit machine-readable JSON instead of the human view. Honored by the read/status
commands (list, whoami, status, description, role, the *-list queries, how-to);
action commands ignore it
-h, --help Print help
spt node status
Node status: daemon state, member subnets, local endpoints (the bare spt node view)
Usage: spt node 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 node access
Node-tier access roster: the entities this node's node-scope rules name, the machine's own mode, and
the captured subnet modes — the tier every hosted endpoint falls through to. Per-endpoint rosters
live on spt endpoint access
Usage: spt node access [OPTIONS] [COMMAND]
Commands:
allow Add an ALLOW rule node-wide, or on one endpoint's chain with --for
deny Refuse a subject node-wide, or for one endpoint with --for
remove Remove a rule by restating it — node-wide, or for one endpoint
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
Control surfaces:
MSG — direct messages (a grant binds the single sender)
RC_VIEW — read-only terminal viewing (a grant admits the whole machine)
RC_ATTACH — interactive terminal control (a grant admits the whole machine)
DIGEST — cross-node digest pull (a grant admits the whole machine)
WAKE — waking a resting endpoint (a grant admits the whole machine)
SUSPEND — suspending a running endpoint (a grant admits the whole machine)
SHELL_LINK — driving a linked shell (a grant admits the whole machine)
DISCOVER — being found: resolve, advertise, and the resources blurb (a grant admits the whole
machine)
WEB — reading served resources over HTTP (a grant admits the whole machine)
FORK — forking this endpoint, mind and all (a grant admits the whole machine)
spt node access allow
Add an ALLOW rule node-wide, or on one endpoint's chain with --for.
NOT a whitelist and NOT a mode change: the chain is strict first-match and bottoms at implicit-open,
so this admits the named subject without excluding anyone else, and it leaves every mode exactly as
it found it.
Usage: spt node access allow [OPTIONS]
Options:
--for <ENDPOINT>
Edit this endpoint's own rules instead of the node-wide tier
--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
--surfaces <S1,S2|ALL>
--endpoint <ID>
--node <NODE>
Subject: an origin node — its pubkey hex, self for this node, or a node name
--any-of <SUBNET>
--origin <user|agent>
-h, --help
Print help (see a summary with '-h')
Control surfaces:
MSG — direct messages (a grant binds the single sender)
RC_VIEW — read-only terminal viewing (a grant admits the whole machine)
RC_ATTACH — interactive terminal control (a grant admits the whole machine)
DIGEST — cross-node digest pull (a grant admits the whole machine)
WAKE — waking a resting endpoint (a grant admits the whole machine)
SUSPEND — suspending a running endpoint (a grant admits the whole machine)
SHELL_LINK — driving a linked shell (a grant admits the whole machine)
DISCOVER — being found: resolve, advertise, and the resources blurb (a grant admits the whole
machine)
WEB — reading served resources over HTTP (a grant admits the whole machine)
FORK — forking this endpoint, mind and all (a grant admits the whole machine)
spt node access deny
Refuse a subject node-wide, or for one endpoint with --for
Usage: spt node access deny [OPTIONS]
Options:
--for <ENDPOINT>
--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
--surfaces <S1,S2|ALL>
--endpoint <ID>
--node <NODE> Subject: an origin node — its pubkey hex, self for this node, or a
node name
--any-of <SUBNET>
--origin <user|agent>
-h, --help Print help
Control surfaces:
MSG — direct messages (a grant binds the single sender)
RC_VIEW — read-only terminal viewing (a grant admits the whole machine)
RC_ATTACH — interactive terminal control (a grant admits the whole machine)
DIGEST — cross-node digest pull (a grant admits the whole machine)
WAKE — waking a resting endpoint (a grant admits the whole machine)
SUSPEND — suspending a running endpoint (a grant admits the whole machine)
SHELL_LINK — driving a linked shell (a grant admits the whole machine)
DISCOVER — being found: resolve, advertise, and the resources blurb (a grant admits the whole
machine)
WEB — reading served resources over HTTP (a grant admits the whole machine)
FORK — forking this endpoint, mind and all (a grant admits the whole machine)
spt node access remove
Remove a rule by restating it — node-wide, or for one endpoint
Usage: spt node access remove [OPTIONS]
Options:
--for <ENDPOINT>
--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
--surfaces <S1,S2|ALL>
--endpoint <ID>
--node <NODE> Subject: an origin node — its pubkey hex, self for this node, or a
node name
--any-of <SUBNET>
--origin <user|agent>
-h, --help Print help
Control surfaces:
MSG — direct messages (a grant binds the single sender)
RC_VIEW — read-only terminal viewing (a grant admits the whole machine)
RC_ATTACH — interactive terminal control (a grant admits the whole machine)
DIGEST — cross-node digest pull (a grant admits the whole machine)
WAKE — waking a resting endpoint (a grant admits the whole machine)
SUSPEND — suspending a running endpoint (a grant admits the whole machine)
SHELL_LINK — driving a linked shell (a grant admits the whole machine)
DISCOVER — being found: resolve, advertise, and the resources blurb (a grant admits the whole
machine)
WEB — reading served resources over HTTP (a grant admits the whole machine)
FORK — forking this endpoint, mind and all (a grant admits the whole machine)
spt node refresh
Restart the daemon's coordinator process in place — no binary change, no stop/start. Hosted
terminals and the network layer keep running untouched; only the coordinator cycles. The recovery
verb for a stuck coordinator (e.g. endpoint bringup wedged) that previously needed a full `daemon
stop/start` killing every hosted session
Usage: spt node refresh [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 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
--code <CODE>
The current six-digit code for the endpoint's subnet, when the endpoint asks for one
before handing over its controls.
The engine room is the one that does. Either the subnet's member code or its admin code is
accepted. Wrong codes are rate-limited and, repeated, raise a notification. Omit it to be
prompted interactively (Esc cancels) — preferred where possible, since a code passed on
the command line is readable by other processes on this machine while it is still valid.
-h, --help
Print help (see a summary with '-h')
spt serve
Register local files and directories for node-prefixed HTTP serving
Usage: spt serve [OPTIONS] <COMMAND>
Commands:
add Serve a file or directory at its current path. Edits are visible; removing the source makes
its URL answer not found
rm Stop serving an entry by name or id. Does not delete the source
list List exposed paths and their URLs. Supports --json
lan Start or stop the LAN bootstrap listener — the opt-in, all-interfaces server that hands the
spt binary to a machine that is not yet a node. It is NOT the docs server: it serves only
/bin/<triple>/spt[.exe], that file's .release.json sidecar, and /install, and the docs
port stays loopback the whole time
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
spt serve add
Serve a file or directory at its current path. Edits are visible; removing the source makes its URL
answer not found
Usage: spt serve add [OPTIONS] <PATH>
Arguments:
<PATH>
Options:
--as <NAME> Choose a served name; collisions receive a stable numbered suffix
--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 serve rm
Stop serving an entry by name or id. Does not delete the source
Usage: spt serve rm [OPTIONS] <NAME_OR_ID>
Arguments:
<NAME_OR_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
spt serve list
List exposed paths and their URLs. Supports --json
Usage: spt serve 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 serve lan
Start or stop the LAN bootstrap listener — the opt-in, all-interfaces server that hands the spt
binary to a machine that is not yet a node. It is NOT the docs server: it serves only
/bin/<triple>/spt[.exe], that file's .release.json sidecar, and /install, and the docs port
stays loopback the whole time.
OFF BY DEFAULT and off again on every daemon restart. While it is up, ANYONE who can reach the
socket may pull the binary — the only gate is this command. It serves the artifacts of the APPLIED
SIGNED SET or it refuses to start by name.
Usage: spt serve lan [OPTIONS]
Options:
--bootstrap
Start the listener
--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
--stop
Stop the listener
--port <PORT>
Bind an explicit port instead of config/env/5470
-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. Mints BOTH subnet keys — the member key (current 6-digit
code, otpauth:// URI, terminal QR) and the admin key, whose provisioning material is shown HERE
AND NOWHERE ELSE, EVER: scan it now or the subnet has no admin authority. Also states the subnet's
control-surface mode — asked with no preselection unless --open/--closed says it outright. 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
--open
Unlisted subjects are ALLOWED on every control surface (today's fleet posture). Skips the
mode question — for scripted creation
--closed
Unlisted subjects are BLOCKED unless an explicit rule allows. Skips the mode question —
for scripted creation
-h, --help
Print help (see a summary with '-h')
Control surfaces:
MSG — direct messages (a grant binds the single sender)
RC_VIEW — read-only terminal viewing (a grant admits the whole machine)
RC_ATTACH — interactive terminal control (a grant admits the whole machine)
DIGEST — cross-node digest pull (a grant admits the whole machine)
WAKE — waking a resting endpoint (a grant admits the whole machine)
SUSPEND — suspending a running endpoint (a grant admits the whole machine)
SHELL_LINK — driving a linked shell (a grant admits the whole machine)
DISCOVER — being found: resolve, advertise, and the resources blurb (a grant admits the whole
machine)
WEB — reading served resources over HTTP (a grant admits the whole machine)
FORK — forking this endpoint, mind and all (a grant admits the whole machine)
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
--verbose
Print a detailed discovery trace (rendezvous attempts, elapsed vs deadline, the last
concrete error) when the search struggles or fails — for diagnosing a join that can't find
a member
-h, --help
Print help (see a summary with '-h')
spt subnet leave
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 ANCHOR subnet unless --target names another (M8 decision 25: no resolvable anchor + 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 anchor 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: bare spt update brings the whole node current.
The bare form fetches + installs the latest core release, then updates every release-shipped adapter
— one command. The invoking session survives it: installing cycles only the daemon's coordinator
process, never the hosted terminals. 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]
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
adapters Update release-shipped adapters (an alias of spt adapter update, which also stays).
With no names, every release-shipped adapter is swept; with names (comma-separated),
exactly those. Names are validated before anything updates, one adapter's failure never
stops the rest, and a summary line reports each outcome
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
-c, --core-only
Update the core binary only — skip the adapters leg of the bare composite
--restart
The full-cycle form: fetch, update adapters, then finish by restarting the daemon onto the
new version (update apply --finish) as the final step — so the whole node, coordinator
and live agents, runs the new version when it returns. The restart bounces hosted sessions
(they come back automatically)
-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:
--finish Finish onto the new version in one step: install it, then restart the daemon so both
the coordinator and every live agent run the new version. Hosted sessions come back
automatically — no manual restart. Without this flag, install alone leaves the
running daemon on the previous version until you restart it yourself
--json Emit machine-readable JSON instead of the human view. Honored by the read/status
commands (list, whoami, status, description, role, the *-list queries, how-to);
action commands ignore it
-h, --help Print help
spt update fetch
Fetch the latest signed release from the GitHub origin and stage it (then spt update apply).
Bootstraps a node with no peer to pull from
Usage: spt update fetch [OPTIONS]
Options:
--channel <CHANNEL> Accept a release on this channel instead of the node's pin (e.g. beta).
Default: the node's pinned channel
--json Emit machine-readable JSON instead of the human view. Honored by the
read/status commands (list, whoami, status, description, role, the *-list
queries, how-to); action commands ignore it
--tag <TAG> Fetch a specific release tag (e.g. v0.3.1) instead of the latest
--apply Fetch then install in one step — apply the staged update even if the
latest was already downloaded. The one-shot "get me to the latest"
-h, --help Print help
spt update adapters
Update release-shipped adapters (an alias of spt adapter update, which also stays). With no names,
every release-shipped adapter is swept; with names (comma-separated), exactly those. Names are
validated before anything updates, one adapter's failure never stops the rest, and a summary line
reports each outcome
Usage: spt update adapters [OPTIONS] [NAMES]
Arguments:
[NAMES] Adapters to update, comma-separated (e.g. claude-spt,other). Omit to sweep every
release-shipped adapter
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
Harness-contract inbound surface (hook entry points).
The entry points a harness's hooks fire to keep spt-core's on-disk state in sync.
Usage: spt api [OPTIONS] <COMMAND>
Commands:
seed Harness-hosted startup: record an ephemeral seed keyed by parent pid
listen Consume a seed and hold the perch + relay loop (blocks)
bind Post-spawn bind of a session to its perch
bind-shell Shell-binary bind: the type=Shell flavor of bind. Resolves the
instance by link token alone (the spawn template carries only
{link_token} — "owner from the link") and flips it online. The
credential IS the auth: no token, no bind
state Set activity state busy|idle (also arms the echo-gate sentinel)
echo-gate Manage the echo-gate sentinel directly
poll Drain delivered messages (hook channel). With --link this is the
shell-flavored relay drain: the link token is the auth, and the drained
rows are the shell's MAC-stamped command/text/file frames
psyche-download Emit the agent's resume context (durable role/live/project tiers + any
not-yet-synthesized commune/signoff drop as pending slices) to stdout,
for the harness adapter's SessionStart hook to inject as additional
context
worker-start Create a nested worker perch under a parent. The worker id is minted by
spt-core ({parent}-w{N}) and echoed as the bare id on stdout — the
caller does NOT pass one. --agent-id/--agent-type are optional
correlation metadata, never the perch identity
worker-stop Tear down a worker perch
worker-poll Drain a worker perch's messages
boundary Rebind the perch to a new session_id, preserving identity (a context
clear/compact boundary)
session-end Soft teardown (spool/history preserved); --erase hard-wipes
presence Report user/agent presence at this endpoint
driven-by Report which node (if any) is remote-driving this endpoint
endpoint-info Emit an endpoint's identity, where it runs, and which node (if any) is
driving it, as JSON. With no id, reports the caller's own endpoint (like
whoami); an explicit id reports that endpoint. Read-only
seal Wax seals: read a durable, citable proof of user authority over specific
content. Read-only; answers on any member node of the seal's binding
subnet
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 ephemeral frames: the shell-side drain
of the owner→shell control channel AND of the owner's pushed busy/idle
state. REST-only, exactly-once — the daemon serves the single latest
frame of each kind and ONLY when the link matches that slot's write-time
stamp (no stale-control replay on relink). The link token is the auth
(mirrors emit). Each pending frame prints to stdout on its own line,
in class order: the drive frame, then the activity frame, then the
attachment frame — so a poll may print none, one, or several. STDOUT
carries frames and nothing else; the per-poll status line
(DRIVE_DELIVERED: / ACTIVITY_DELIVERED: / ATTACH_DELIVERED: /
DRIVE_EMPTY:) and every diagnostic go to STDERR, so a reader that
merges the two streams sees non-frame lines interleaved and must not key
on line count. Parse the type attribute and ignore what you don't know
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
access-refresh Re-read the subnet-wide access fallbacks this node captured when it
joined, after the subnet's mode has changed
empower Gain authority over a subnet's control-surface modes by proving that
subnet's admin code, for the rest of this session
access-node-mode Set this node's own default posture for callers no rule names
access-node-surface-mode Set this node's own posture for ONE control 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). Select the
manifest with a group-level option on spt api, before hint:
--manifest <path> supplies a path, or --adapter <name[:profile]>
resolves a registered adapter. If neither route resolves a manifest, the
command refuses
io-events The delta-cursored IO EVENT poll a harness adapter reads through.
Answers the events this caller has not been shown and nothing else.
--session-id <sid> keeps a per-session cursor the way now-signal
keeps seen-sets — the same flag that authenticates the call, because
the harness session is one identity and two flags spelt one apart would
be two ways to be wrong about it. --after <seq> lets a caller carry
its own cursor instead, the way endpoint digest --after does. One of
the two is required, because a poll with no cursor could only replay the
log
now-signal The ONE situational-awareness funnel: per-category XML under
<SPT-NOW-SIGNAL>, DELTA-ONLY against per-session seen-sets, so a poll
with nothing new prints NOTHING. Built to be injected on every
turn-boundary hook
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> Anchor subnet for a NEW endpoint (required on a multi-subnet node —
the anchor is assigned at creation, never guessed)
--session-id <SESSION_ID> Bind from this session id when the ephemeral seed is gone (a
session going live late, or after a daemon restart). With no live
seed and no session id, listen refuses (NO_SEED)
-h, --help Print help
spt api bind
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> Anchor 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).
Optionally carries the turn's IO payload for the event funnel: busy carries the USER_INPUT
payload, idle the AGENT_OUTPUT end-of-turn payload. With no payload the call behaves exactly as it
always has and emits nothing.
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
--payload-stdin
Read the IO payload from stdin. Explicit because this verb is fired by adapters on
every hook: sniffing a non-tty stdin would block forever on an inherited-but-idle pipe,
wedging the hook
--payload-file <PAYLOAD_FILE>
Read the IO payload from a file
--mid
This payload is a MID-TURN span of agent output, not the turn's close: it is reported
busy (the agent is still working) and is still AGENT_OUTPUT. Refused at idle, and
refused with no payload — both are contradictions rather than events
--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 (see a summary with '-h')
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. The worker id is minted by spt-core ({parent}-w{N})
and echoed as the bare id on stdout — the caller does NOT pass one. --agent-id/--agent-type are
optional correlation metadata, never the perch identity
Usage: spt api worker-start [OPTIONS] <PARENT>
Arguments:
<PARENT>
Options:
--agent-id <AGENT_ID> Adapter's own agent id (correlation metadata only)
--json Emit machine-readable JSON instead of the human view. Honored by
the read/status commands (list, whoami, status, description, role,
the *-list queries, how-to); action commands ignore it
--agent-type <AGENT_TYPE> Adapter's own agent type (correlation metadata only)
--token <TOKEN> Capability token proving association to the target perch
--session-id <SESSION_ID> Session id proving association (matches the perch's info.json)
-h, --help Print help
spt api worker-stop
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 endpoint-info
Emit an endpoint's identity, where it runs, and which node (if any) is driving it, as JSON. With no
id, reports the caller's own endpoint (like whoami); an explicit id reports that endpoint. Read-only
Usage: spt api endpoint-info [OPTIONS] [ID]
Arguments:
[ID] The endpoint id to report on. Omit to self-resolve the caller's perch
Options:
--json Emit machine-readable JSON instead of the human view. Honored by the read/status
commands (list, whoami, status, description, role, the *-list queries, how-to); action
commands ignore it
-h, --help Print help
spt api seal
Wax seals: read a durable, citable proof of user authority over specific content. Read-only; answers
on any member node of the seal's binding subnet
Usage: spt api seal [OPTIONS] <COMMAND>
Commands:
describe Print the seal record's fields (token, content hash, minter, mint timestamp, ceremony
kind) for a token. Read-only
verify Verify content against a seal: the content arrives on stdin, its hash is recomputed
over the exact bytes received, and the verdict is BOUND or NOT-BOUND with the record's
fields. Exit 0 only when BOUND. With no content on stdin this refuses and points at
describe
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
spt api seal describe
Print the seal record's fields (token, content hash, minter, mint timestamp, ceremony kind) for a
token. Read-only
Usage: spt api seal describe [OPTIONS] <TOKEN>
Arguments:
<TOKEN> The seal token to describe
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 seal verify
Verify content against a seal: the content arrives on stdin, its hash is recomputed over the
exact bytes received, and the verdict is BOUND or NOT-BOUND with the record's fields. Exit 0 only
when BOUND. With no content on stdin this refuses and points at describe
Usage: spt api seal verify [OPTIONS] <TOKEN>
Arguments:
<TOKEN> The seal token to verify against
Options:
--json Emit machine-readable JSON instead of the human view. Honored by the read/status
commands (list, whoami, status, description, role, the *-list queries, how-to); action
commands ignore it
-h, --help Print help
spt api history-log
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 ephemeral frames: the shell-side drain of the owner→shell control
channel AND of the owner's pushed busy/idle state. REST-only, exactly-once — the daemon serves the
single latest frame of each kind and ONLY when the link matches that slot's write-time stamp (no
stale-control replay on relink). The link token is the auth (mirrors emit). Each pending frame
prints to stdout on its own line, in class order: the drive frame, then the activity frame, then the
attachment frame — so a poll may print none, one, or several. STDOUT carries frames and nothing
else; the per-poll status line (DRIVE_DELIVERED: / ACTIVITY_DELIVERED: / ATTACH_DELIVERED: /
DRIVE_EMPTY:) and every diagnostic go to STDERR, so a reader that merges the two streams sees
non-frame lines interleaved and must not key on line count. Parse the type attribute and ignore
what you don't know
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 access-refresh
Re-read the subnet-wide access fallbacks this node captured when it joined, after the subnet's mode
has changed.
Updates only the fallbacks the subnet supplies, never the access rules you set on this node, which
stay yours. Only this node's engine room may run it, and only for a subnet it has been empowered
over.
Usage: spt api access-refresh [OPTIONS] <SUBNET> <ID>
Arguments:
<SUBNET>
The subnet whose captured fallbacks to refresh
<ID>
The calling 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
--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 (see a summary with '-h')
spt api empower
Gain authority over a subnet's control-surface modes by proving that subnet's admin code, for the
rest of this session.
Only this node's engine room may run it. The grant ends when the session ends or the controller
detaches — it is never stored.
Usage: spt api empower [OPTIONS] --admin-code <ADMIN_CODE> <SUBNET> <ID>
Arguments:
<SUBNET>
The subnet to gain authority over
<ID>
The calling endpoint id
Options:
--admin-code <ADMIN_CODE>
The subnet's current admin code
--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 (see a summary with '-h')
spt api access-node-mode
Set this node's own default posture for callers no rule names.
Only this node's engine room may run it. It sets the node-wide default; the rules you wrote for
particular endpoints and nodes are untouched.
Usage: spt api access-node-mode [OPTIONS] <MODE> <ID>
Arguments:
<MODE>
open (callers allowed unless a rule denies) or closed (callers blocked unless a rule
allows)
[possible values: open, closed]
<ID>
The calling 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
--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 (see a summary with '-h')
spt api access-node-surface-mode
Set this node's own posture for ONE control surface.
Only this node's engine room may run it. unset removes this node's entry for the surface, which is
not the same as open: a surface that is on by default is on again, and an ordinary one falls back
to this node's default posture.
Usage: spt api access-node-surface-mode [OPTIONS] <SURFACE> <MODE> <ID>
Arguments:
<SURFACE>
The control surface to set a posture for (DISCOVER, MSG, …)
<MODE>
open, closed, or unset (remove this node's entry)
[possible values: open, closed, unset]
<ID>
The calling 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
--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 (see a summary with '-h')
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). Select the manifest
with a group-level option on spt api, before hint: --manifest <path> supplies a path, or
--adapter <name[:profile]> resolves a registered adapter. If neither route resolves a manifest,
the command refuses.
A THIN ALIAS over now-signal's HINTS category (ratified 2026-07-29): it survives so existing
adapters keep working and gains no independent behaviour, because two verbs answering one question
is how an adapter ends up injecting both.
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 (see a summary with '-h')
spt api io-events
The delta-cursored IO EVENT poll a harness adapter reads through. Answers the events this caller has
not been shown and nothing else. --session-id <sid> keeps a per-session cursor the way
now-signal keeps seen-sets — the same flag that authenticates the call, because the harness
session is one identity and two flags spelt one apart would be two ways to be wrong about it.
--after <seq> lets a caller carry its own cursor instead, the way endpoint digest --after does.
One of the two is required, because a poll with no cursor could only replay the log.
A new session's first poll sees NOTHING and seeds silently — history is endpoint digest's job.
Use --json for the adapter-facing envelope, which is emitted even when it is empty.
Authenticated like api poll, and for the same reason: this hands back the session's verbatim
user input and agent output, which is the payload class addressed to the endpoint's occupant. A
--token caller has no session identity and therefore uses --after.
Usage: spt api io-events [OPTIONS] <ID>
Arguments:
<ID>
The endpoint whose events to read
Options:
--after <AFTER>
Cursor: answer only with events newer than this seq. Wins over the session cursor when
both are given, and writes no session cursor
--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
--limit <LIMIT>
Cap how many events one poll answers with. The rest are NOT dropped — they are the next
poll's first rows, and the answer says it capped
--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 (see a summary with '-h')
spt api now-signal
The ONE situational-awareness funnel: per-category XML under <SPT-NOW-SIGNAL>, DELTA-ONLY against
per-session seen-sets, so a poll with nothing new prints NOTHING. Built to be injected on every
turn-boundary hook
Usage: spt api now-signal [OPTIONS] --session <SESSION> <ID>
Arguments:
<ID> The calling 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
--session <SESSION> The harness session id keying every category's seen-set. A
/clear is a new session and is entitled to the picture once
--user-input <USER_INPUT> The user's words this turn (ENDPOINT_MENTIONS, HINTS, MONICS)
[default: ""]
--agent-output <AGENT_OUTPUT> The agent's words this turn (MONICS, HINTS) [default: ""]
--spec-manifest Take the category tuning from the manifest's [io.now_signal]
--spec-file <SPEC_FILE> Take the category tuning from this JSON file. Wins over
--spec-manifest; unreadable or malformed reads as the default
picture, never as a refusal
-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)
create Create a NEW endpoint and bring its first session up
start Start a NEW session on an endpoint that already exists
resume Resume an endpoint's LATEST session
auto-start Replay this endpoint at every daemon start
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 Stop an endpoint outright (spool and history preserved)
rename Rename an endpoint's logical id across its on-disk state
gc Census the perch tree for perch directories that outlived their endpoint
purge Permanently remove an endpoint and every record keyed on it
digest Show a session's live activity buffer (session digest)
access Access rules and posture, roster-first
engine-room Create or reset this node's engine-room record (the ceremony)
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
monic Reactionary strings which reveal helpful context when detected in this endpoint's
session
trust-warning A hidden warning which joins incoming messages from unknown endpoints. Senders'
endpoint IDs with a matching monic omit the trust warning
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
--show-all
Also show suspended (resting) endpoints, which are hidden by default
--workers
Also show worker perches, which are hidden by default (they are process-local machinery
under a parent agent, not standalone endpoints)
-h, --help
Print help (see a summary with '-h')
spt endpoint create
Create a NEW endpoint and bring its first session up.
The only way an endpoint is minted. The adapter and working directory recorded here become the
endpoint's session defaults — every later start lands on them unless told otherwise. The anchor
subnet is assigned here and is permanent (the cross-subnet move is fork). An id that already
exists is REFUSED: bring the existing one up with start, or go straight to it with `spt go
<id>`.
Usage: spt endpoint create [OPTIONS] <NEW_ID>
Arguments:
<NEW_ID>
The new endpoint's id (charset: alphanumeric, -, _)
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>
Home this endpoint to a named subnet. Required on a node that holds more than one subnet
(the anchor is assigned at creation and is permanent); the sole subnet is used
automatically when there is one
--adapter <ADAPTER>
The harness adapter to host: <adapter>[:profile] (must be a registered kind="harness"
adapter on this node). Omit on a node that has exactly one registered harness adapter
--cwd <DIR>
The project folder the harness runs in (defaults to the directory this command is run
from)
-h, --help
Print help (see a summary with '-h')
spt endpoint start
Start a NEW session on an endpoint that already exists.
Lands on the endpoint's most-recent adapter in its most-recent project folder — never on the folder
you happen to be standing in. --adapter / --cwd override this run AND become the new remembered
defaults. An UNKNOWN id is refused rather than minted (that is create's job); the sibling verbs
are resume (its latest session), wake (an endpoint that is only resting, not offline), and
spt go <id> (start-and-attach, whatever state it is in).
Usage: spt endpoint start [OPTIONS] <ID>
Arguments:
<ID>
The endpoint id to start a new session on
Options:
--adapter <ADAPTER>
Run this session under a different harness adapter, and remember it as the endpoint's
adapter from now on
--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
--cwd <DIR>
Run this session in a different project folder, and remember it as the endpoint's folder
from now on
-h, --help
Print help (see a summary with '-h')
spt endpoint resume
Resume an endpoint's LATEST session.
Brings the endpoint back up on the last session it recorded, in the project folder that session ran
in. An endpoint that has never recorded a session has nothing to resume — start it instead. The
siblings are start (a fresh session), wake (it is only resting, not offline), and `spt go
<id>` (resume-and-attach).
Usage: spt endpoint resume [OPTIONS] <ID>
Arguments:
<ID>
The endpoint id whose latest session to resume
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 auto-start
Replay this endpoint at every daemon start.
Records a startup default: the daemon brings the endpoint up (a fresh session, on its remembered
adapter and folder) every time it starts, until you turn it off with --off. One entry per endpoint
id — setting it again replaces the prior one. An endpoint that fails to come up logs the failure and
never blocks the daemon.
Usage: spt endpoint auto-start [OPTIONS] <ID>
Arguments:
<ID>
The endpoint id to auto-start
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
--off
Stop auto-starting this endpoint (remove its startup default)
-h, --help
Print help (see a summary with '-h')
spt endpoint fork
Fork an endpoint into another subnet as a NEW identity.
Anchor 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, monics included); the two diverge
immediately (no ongoing sync). The source is untouched unless --delete-source.
The source may live on ANOTHER node: name it id@node and the fork is made where the source is, by
that node. That needs the source's owner to admit you for BOTH FORK and DISCOVER on it — FORK
alone cannot be exercised, because without DISCOVER you cannot resolve the endpoint you were given
permission to fork. --delete-source is LOCAL ONLY: a fork across nodes never deletes, and asking
for one is refused rather than quietly downgraded to a copy.
Usage: spt endpoint fork [OPTIONS] --subnet <SUBNET> <SRC> <NEW_ID>
Arguments:
<SRC>
The source endpoint (qualified id@node forks one a paired peer holds)
<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 anchor 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. The siblings are start (a NEW session on
an endpoint that is offline) and resume (its latest session back).
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.
The final context save fires and persistent shells cascade offline first; the session is then ended
and the endpoint reports suspended. The preferred way to stop an endpoint — stop is the escalation
for a session that has stopped responding.
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
Stop an endpoint outright (spool and history preserved).
Ends the session without waiting for it to respond — the way out of a session that has hung. No
final context save is taken, so prefer shutdown when the session is still answering. The
endpoint's spool and history are kept, and it can be started again afterwards.
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 gc
Census the perch tree for perch directories that outlived their endpoint.
REPORTS BY DEFAULT AND DELETES NOTHING. A perch directory is residue only when it carries NO
endpoint record — no info.json — because the perch dir plus its record IS the endpoint record on
this node (the registry is an address table, and every offline endpoint is legitimately absent from
it). Age and last-touched are never consulted: a dormant endpoint, a suspended session and a
long-idle live agent all look "old".
Even then only part of the residue is deletable. A recordless dir holding a SPOOL keeps the only
surviving copy of whatever was queued for it, and an EMPTY dir is also what a bringup owns
mid-create — both are refused permanently and REPORTED by path with the manual remedy. A refused
directory also shields everything beneath it: refusing means the contents are not modified either.
--reap removes exactly the rest.
Usage: spt endpoint gc [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
--reap
Also REMOVE the RESIDUE-REAPABLE directories the census names (recordless, spool-less,
non-empty, no write in flight, no held child, no refused ancestor). Everything else is
still only reported. The census itself prints identically with and without this flag
-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. The snapshot reads an endpoint on
another machine too; only --follow is limited to this one.
Usage: spt endpoint digest [OPTIONS] <ID>
Arguments:
<ID>
The endpoint id to read. Accepts a qualified [subnet:]id@node address to read an
endpoint on another machine — that node projects and answers, so you see exactly what
someone standing on it would. Works with --last and --after; an address that resolves
to this machine is answered locally
Options:
--follow
Stream live changes instead of a one-shot snapshot (Ctrl-C to stop).
THIS MACHINE ONLY — there is no live stream across machines. To track an endpoint on
another node, poll the snapshot with --after <seq>.
--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
Access rules and posture, roster-first.
Bare access lists each ruled endpoint's access entities — the subnets, nodes, and endpoints its
rules name, grouped by type, each with its rule count (and, for a subnet or this machine, its mode).
Name an endpoint to scope the roster to it. The granular rule list is viewable only per named ruled
entity, through the drill-down flags. Rules are node-sovereign: viewing another node's rules means
running this on that node. allow/revoke/open edit as before.
Usage: spt endpoint access [OPTIONS] [ENDPOINT] [COMMAND]
Commands:
allow Add an ALLOW rule for a subject on this endpoint's chain
deny Refuse a subject for an endpoint. Same subject/surface flags as allow
remove Remove a rule by restating it — the same flags that created it
revoke Drop a node's ALLOW rules from an endpoint's chain. Never widens: it deletes those rules
and touches nothing else, so removing the last one leaves the endpoint on the mode allow
set — closed, refusing every unsolicited sender it has no rule for. open is the widening
verb
open Delete an endpoint's restriction entirely — back to default-open
help Print this message or the help of the given subcommand(s)
Arguments:
[ENDPOINT]
Scope the roster to one target endpoint
Options:
--endpoint-rules <ID>
Drill down: the rules naming this sender endpoint
--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
--node-rules <NODE>
Drill down: the rules naming this origin node (pubkey hex)
--subnet-rules <SUBNET>
Drill down: the rules naming this subnet
-h, --help
Print help (see a summary with '-h')
Control surfaces:
MSG — direct messages (a grant binds the single sender)
RC_VIEW — read-only terminal viewing (a grant admits the whole machine)
RC_ATTACH — interactive terminal control (a grant admits the whole machine)
DIGEST — cross-node digest pull (a grant admits the whole machine)
WAKE — waking a resting endpoint (a grant admits the whole machine)
SUSPEND — suspending a running endpoint (a grant admits the whole machine)
SHELL_LINK — driving a linked shell (a grant admits the whole machine)
DISCOVER — being found: resolve, advertise, and the resources blurb (a grant admits the whole
machine)
WEB — reading served resources over HTTP (a grant admits the whole machine)
FORK — forking this endpoint, mind and all (a grant admits the whole machine)
spt endpoint access allow
Add an ALLOW rule for a subject on this endpoint's chain.
NOT a whitelist: the chain is strict first-match and bottoms at implicit-open, so a subject nobody
has written a rule about is decided by the endpoint's mode, then the node's, then a captured subnet
mode — and if none of those governs, it is ALLOWED. Adding an allow rule admits the named subject;
it does not exclude anyone else.
THE MODE EFFECT DIFFERS BY SPELLING, so it is stated per spelling below rather than in one sentence
that can only be half true: the positional spelling also flips the endpoint to restricted if no mode
was set (the v1 verb's meaning, and it says endpoint is now restricted when it does), while the
flag spelling writes the rule and leaves the modes alone.
Two spellings. The short one takes a node pubkey positionally and admits it on every surface —
unless --surfaces narrows it, which this spelling honors like any other. The precise one names the
subject with a flag: --surfaces MSG,SUSPEND --node <hex> (or --endpoint <id> for one sender, or
--any-of <subnet> for any member of a subnet), optionally restricted to human or agent callers
with --origin. Both spellings answer to the same acknowledgment: an agent granting a whole machine
confirms with --admit-node either way.
Usage: spt endpoint access allow [OPTIONS] <ENDPOINT> [NODE]
Arguments:
<ENDPOINT>
The endpoint whose rule chain this rule joins
[NODE]
The origin node's pubkey hex — the short spelling, admitting that node on every surface
unless --surfaces names fewer. Omit it only when naming the subject with a flag instead;
a rule about nobody is refused at parse
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
--surfaces <S1,S2|ALL>
Surfaces this rule covers: a comma list, or ALL
--endpoint <ID>
Subject: one sender endpoint id
--node <NODE>
Subject: an origin node — its pubkey hex, self for this node, or a node name
--any-of <SUBNET>
Subject: any member of this subnet
--origin <user|agent>
Restrict the rule to one caller class: user (the humans on that machine) or agent.
Omit to match both
--admit-node
Confirm a grant that admits an entire machine, not just the subject named. Required for a
node-subject grant
-h, --help
Print help (see a summary with '-h')
Control surfaces:
MSG — direct messages (a grant binds the single sender)
RC_VIEW — read-only terminal viewing (a grant admits the whole machine)
RC_ATTACH — interactive terminal control (a grant admits the whole machine)
DIGEST — cross-node digest pull (a grant admits the whole machine)
WAKE — waking a resting endpoint (a grant admits the whole machine)
SUSPEND — suspending a running endpoint (a grant admits the whole machine)
SHELL_LINK — driving a linked shell (a grant admits the whole machine)
DISCOVER — being found: resolve, advertise, and the resources blurb (a grant admits the whole
machine)
WEB — reading served resources over HTTP (a grant admits the whole machine)
FORK — forking this endpoint, mind and all (a grant admits the whole machine)
spt endpoint access deny
Refuse a subject for an endpoint. Same subject/surface flags as allow
Usage: spt endpoint access deny [OPTIONS] <ENDPOINT>
Arguments:
<ENDPOINT> The endpoint whose rule chain this rule joins
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
--surfaces <S1,S2|ALL> Surfaces this rule covers: a comma list, or ALL
--endpoint <ID> Subject: one sender endpoint id
--node <NODE> Subject: an origin node — its pubkey hex, self for this node, or a
node name
--any-of <SUBNET> Subject: any member of this subnet
--origin <user|agent> Restrict the rule to one caller class: user or agent
--admit-node
-h, --help Print help
Control surfaces:
MSG — direct messages (a grant binds the single sender)
RC_VIEW — read-only terminal viewing (a grant admits the whole machine)
RC_ATTACH — interactive terminal control (a grant admits the whole machine)
DIGEST — cross-node digest pull (a grant admits the whole machine)
WAKE — waking a resting endpoint (a grant admits the whole machine)
SUSPEND — suspending a running endpoint (a grant admits the whole machine)
SHELL_LINK — driving a linked shell (a grant admits the whole machine)
DISCOVER — being found: resolve, advertise, and the resources blurb (a grant admits the whole
machine)
WEB — reading served resources over HTTP (a grant admits the whole machine)
FORK — forking this endpoint, mind and all (a grant admits the whole machine)
spt endpoint access remove
Remove a rule by restating it — the same flags that created it.
Removal names the rule rather than an id, so it is idempotent and script-safe, and the access
drill-down prints the exact command for every rule it lists.
Usage: spt endpoint access remove [OPTIONS] <ENDPOINT>
Arguments:
<ENDPOINT>
The endpoint whose rule 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
--surfaces <S1,S2|ALL>
Surfaces the rule covers: a comma list, or ALL
--endpoint <ID>
Subject: one sender endpoint id
--node <NODE>
Subject: an origin node — its pubkey hex, self for this node, or a node name
--any-of <SUBNET>
Subject: any member of this subnet
--origin <user|agent>
The caller class the rule was restricted to, if any
--admit-node
Confirm removing a refusal that covers an entire machine
-h, --help
Print help (see a summary with '-h')
Control surfaces:
MSG — direct messages (a grant binds the single sender)
RC_VIEW — read-only terminal viewing (a grant admits the whole machine)
RC_ATTACH — interactive terminal control (a grant admits the whole machine)
DIGEST — cross-node digest pull (a grant admits the whole machine)
WAKE — waking a resting endpoint (a grant admits the whole machine)
SUSPEND — suspending a running endpoint (a grant admits the whole machine)
SHELL_LINK — driving a linked shell (a grant admits the whole machine)
DISCOVER — being found: resolve, advertise, and the resources blurb (a grant admits the whole
machine)
WEB — reading served resources over HTTP (a grant admits the whole machine)
FORK — forking this endpoint, mind and all (a grant admits the whole machine)
spt endpoint access revoke
Drop a node's ALLOW rules from an endpoint's chain. Never widens: it deletes those rules and touches
nothing else, so removing the last one leaves the endpoint on the mode allow set — closed,
refusing every unsolicited sender it has no rule for. open is the widening verb
Usage: spt endpoint access revoke [OPTIONS] <ENDPOINT> <NODE>
Arguments:
<ENDPOINT>
<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
-h, --help Print help
spt endpoint access open
Delete an endpoint's restriction entirely — back to default-open
Usage: spt endpoint access open [OPTIONS] <ENDPOINT>
Arguments:
<ENDPOINT>
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 endpoint engine-room
Create or reset this node's engine-room record (the ceremony).
Binds the engine room's anchor subnet and its harness adapter — the only path that can set either.
Creating a first record needs no elevation (run the ceremony early: the unelevated window closes at
the first run); resetting an existing record must run in an elevated shell. Never runnable from an
agent session — run it from your own terminal. The subnet must already be joined here and the
adapter registered, so the record it binds can actually come up.
Usage: spt endpoint engine-room [OPTIONS] --adapter <ADAPTER> <SUBNET>
Arguments:
<SUBNET>
The engine room's anchor subnet (already joined on this node)
Options:
--adapter <ADAPTER>
The harness adapter to bind (already registered on this node)
--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 description set
Author this endpoint's blurb (the agent refines its own at runtime; an empty string clears it back
to the node-config seed)
Usage: spt endpoint description set [OPTIONS] <TEXT>
Arguments:
<TEXT> The blurb text ("" clears)
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
-h, --help Print help
spt endpoint description show
Show a local endpoint's authored blurb (the bare description view)
Usage: spt endpoint description show [OPTIONS] [ID]
Arguments:
[ID] The local endpoint id (auto-detected 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 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 endpoint monic
Reactionary strings which reveal helpful context when detected in this endpoint's session
A monic is a set of triggers plus a body. When something in the session matches a trigger, the body
is revealed. Triggers can watch the sender of a message, its content, or a custom payload — so
classifying a peer is one thing a monic can do, not what a monic is. Monics live in the agent's own
mind and travel with it. Bare monic lists them.
Usage: spt endpoint monic [OPTIONS] [COMMAND]
Commands:
list List the monics this endpoint holds (the bare monic view)
add Write a monic this endpoint does not hold yet
update Replace a monic this endpoint holds
remove Withdraw a monic this endpoint holds
clone Copy monics from another endpoint's mind into this 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')
Trigger kinds:
sender — the proven sender id (evaluated today)
content — the message body (evaluated today)
json — a custom payload (evaluated today)
user-input — what you type (evaluated today)
agent-output — what the agent writes (evaluated today)
spt endpoint monic list
List the monics this endpoint holds (the bare monic view).
A record that is present but unreadable is listed under its own id and marked unreadable: the
delivery edge reads it as never having matched anything, so this view is where it stays findable and
fixable.
Usage: spt endpoint monic 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>
Whose monics to list (auto-detected from the session if omitted)
-h, --help
Print help (see a summary with '-h')
spt endpoint monic add
Write a monic this endpoint does not hold yet.
The body is read from stdin. Refuses when the id is already taken — replacing an existing monic is
update, so a typo'd id or a re-run script cannot quietly change one.
Pass --batch to write several at once from one stdin payload instead.
Usage: spt endpoint monic add [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
--target <TARGET>
The id of the monic to write
--triggers <TRIGGERS>
The trigger set: a JSON array of matchers, e.g. [{"kind":"sender","pattern":"mallory"}].
A pattern is a case-insensitive substring unless you add "regex":true
--batch
Read several whole monics from stdin as a JSON array instead of one body. Each element
carries its own id, triggers and text
--owner <OWNER>
Whose mind to write in (auto-detected from the session if omitted)
-h, --help
Print help (see a summary with '-h')
Trigger kinds:
sender — the proven sender id (evaluated today)
content — the message body (evaluated today)
json — a custom payload (evaluated today)
user-input — what you type (evaluated today)
agent-output — what the agent writes (evaluated today)
spt endpoint monic update
Replace a monic this endpoint holds.
The body is read from stdin. Refuses when there is none under that id — writing a first one is
add. A monic is stated whole, so an update replaces the record rather than amending it.
Pass --batch to replace several at once from one stdin payload.
Usage: spt endpoint monic update [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
--target <TARGET>
The id of the monic to replace
--triggers <TRIGGERS>
The new trigger set: a JSON array of matchers, e.g.
[{"kind":"sender","pattern":"mallory"}]. A pattern is a case-insensitive substring
unless you add "regex":true
--batch
Read several whole monics from stdin as a JSON array instead of one body. Each element
carries its own id, triggers and text
--owner <OWNER>
Whose mind to write in (auto-detected from the session if omitted)
-h, --help
Print help (see a summary with '-h')
Trigger kinds:
sender — the proven sender id (evaluated today)
content — the message body (evaluated today)
json — a custom payload (evaluated today)
user-input — what you type (evaluated today)
agent-output — what the agent writes (evaluated today)
spt endpoint monic remove
Withdraw a monic this endpoint holds.
Removing one that was never there is not an error.
Usage: spt endpoint monic remove [OPTIONS] --target <TARGET>
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>
The id of the monic to withdraw
--owner <OWNER>
Whose mind to write in (auto-detected from the session if omitted)
-h, --help
Print help (see a summary with '-h')
spt endpoint monic clone
Copy monics from another endpoint's mind into this one.
Name a monic id to copy one, or --all for every one the source holds. A record the destination
already holds is KEPT and reported, never silently replaced — pass --overwrite to replace it
deliberately. Copies are marked as inherited, so the destination can tell its own monics from the
ones it was given.
Usage: spt endpoint monic clone [OPTIONS] --from <FROM> [TARGET]
Arguments:
[TARGET]
The one monic id to copy (omit with --all)
Options:
--all
Copy every monic the source holds
--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
--from <FROM>
The endpoint to copy FROM
--to <TO>
The endpoint to copy INTO (auto-detected from the session if omitted)
--overwrite
Replace destination records instead of keeping them
-h, --help
Print help (see a summary with '-h')
spt endpoint trust-warning
A hidden warning which joins incoming messages from unknown endpoints. Senders' endpoint IDs with a
matching monic omit the trust warning.
When a peer gets through an access rule and this endpoint holds no monic whose sender trigger
matches them, spt delivers a system-authored warning alongside their message. This verb shows that
text and — with elevation — replaces the ADVISORY part of it with your own. Bare trust-warning
shows it.
Usage: spt endpoint trust-warning [OPTIONS] [COMMAND]
Commands:
show Show the warning this endpoint would be given, as it would read
set Replace the advisory with your own text (needs an elevated process)
reset Withdraw the custom advisory, restoring the default (needs elevation)
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 trust-warning show
Show the warning this endpoint would be given, as it would read.
Never gated: what an agent is told about strangers is exactly the thing worth being able to audit,
whoever is asking.
Usage: spt endpoint trust-warning show [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>
Whose warning to show (auto-detected from the session if omitted)
-h, --help
Print help (see a summary with '-h')
spt endpoint trust-warning set
Replace the advisory with your own text (needs an elevated process).
Your text takes the place of the advice paragraph only. The line naming who reached the endpoint,
the line saying no note is held about them, and the line saying how to classify them are always
written by spt, so an override changes what the agent is cautioned about and can never hide who is
knocking.
Usage: spt endpoint trust-warning set [OPTIONS] <TEXT>
Arguments:
<TEXT>
The advisory to give instead of the default
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>
Whose warning to change (auto-detected from the session if omitted)
-h, --help
Print help (see a summary with '-h')
spt endpoint trust-warning reset
Withdraw the custom advisory, restoring the default (needs elevation)
Usage: spt endpoint trust-warning reset [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> Whose warning to restore (auto-detected from the session if omitted)
-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>
Anchor subnet for a NEW endpoint (required on a multi-subnet node — the anchor 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.
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>
How long to wait for a reply before giving up. A bare number is MINUTES (an agent answers
on agent time); an explicit s or m suffix sets the unit, so 90s and 2m both work
[default: 30]
-h, --help
Print help (see a summary with '-h')
spt seal
Wax seals: mint a citable proof of user authority over content.
The mint runs the TOTP human-presence ceremony at the minter's attached controller; the read verbs
(describe/verify) live under spt api seal.
Usage: spt seal [OPTIONS] <COMMAND>
Commands:
mint Mint a decision seal: the text to seal arrives on stdin, the TOTP ceremony
runs at the minter's attached controller, and the minted token prints to
stdout. Exit 0 only when the ceremony admitted
enroll-authenticator Enroll this node's platform authenticator (Windows Hello) into a subnet's
security material, gated by the TOTP ceremony: the enrolled pubkey is what
lets any member node verify FIDO2-ceremony seals from this node. Per node x
subnet; records are immutable in v1, so an already-enrolled pair refuses by
name. Exit 0 only when enrolled
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 seal mint
Mint a decision seal: the text to seal arrives on stdin, the TOTP ceremony runs at the minter's
attached controller, and the minted token prints to stdout. Exit 0 only when the ceremony admitted
Usage: spt seal mint [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
--minter <MINTER> The minter endpoint (auto-detected from the session if omitted)
--subnet <SUBNET> The binding subnet (defaults to the minter's anchor subnet)
-h, --help Print help
spt seal enroll-authenticator
Enroll this node's platform authenticator (Windows Hello) into a subnet's security material, gated
by the TOTP ceremony: the enrolled pubkey is what lets any member node verify FIDO2-ceremony seals
from this node. Per node x subnet; records are immutable in v1, so an already-enrolled pair refuses
by name. Exit 0 only when enrolled
Usage: spt seal enroll-authenticator [OPTIONS]
Options:
--endpoint <ENDPOINT> The endpoint whose live session hosts the ceremony overlay
(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
--subnet <SUBNET> The binding subnet (defaults to the endpoint's anchor subnet)
-h, --help Print help
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
--seal Seal this message: the TOTP mint ceremony runs over the exact bytes to
be delivered, and the message carries the seal token as an envelope
attribute. Nothing is sent unless the ceremony admits
--subnet <SUBNET> Binding subnet for --seal (defaults to the sender's anchor subnet, or
the first subnet shared with the destination)
--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
--attachment <PATH> Attach a file: its bytes are SNAPSHOT at send time and served, and the
message carries the link. Nothing is pushed to the receiver. Repeatable
--ttl <DUR> Lifetime for this send's attachments (default 30d). A unit is required:
s, m, h or d
--reply-to <ID> Short-ID of the message this replies to; carried in the envelope so an
adapter may render a thread. An unknown parent is carried, not refused
-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. A RUNNING instance refuses — --force
stops it first, then relinks
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. A RUNNING instance refuses — --force stops it first, then
relinks
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>
--force Relink an instance whose binary is STILL RUNNING: stop it first (the ordinary
link-break close — pre-close instruction, termination window, authenticated
kill), then re-spawn and link. Without it, a running instance refuses (relink
is the online switch). Refused on ephemeral instances, whose close IS a
teardown, and refused if the binary cannot be proven stopped — never launches
a second one
-h, --help Print help
spt whoami
Who am I? This session's own endpoint, identity-only and fast.
Resolves the calling session to its endpoint ($OWL_SESSION_ID / $SPT_AGENT_ID / process ancestry)
and prints that one endpoint's SELF line — id, liveness, description. Never enumerates the roster,
never derives projects, never touches git or the network, so it answers in bounded time from hooks
and scripts under deadlines. For the full roster view use spt endpoint list.
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')