Command reference

stratactl is the command-line client of the management API, for people and CI. Its commands come from one registry (sp-commands) that the assistant's shell shares (architecture.md §8); in that shell the CLI is called sp.

1. Conventions

• Target and credentials. A context names a server and a token; the token's tenant is the context's tenant: stratactl login --server https://strataplane.example.com asks for an API token (spk_…, created in the UI or with token create) and stores it in ~/.config/stratactl/ (0600). context list|use and the global --context NAME (or STRATACTL_CONTEXT) pick between several contexts; STRATACTL_SERVER and STRATACTL_TOKEN override the context, for CI. login --ca-cert FILE (or STRATACTL_CA_CERT) trusts a private CA besides the system's and keeps it with the context. Platform commands use a context with a platform token (self-hosted: any token of a platform admin).
• Output. Tables for people; -o json prints the API response unchanged, for scripts and jq. The one exception: a command whose table shows several responses prints them as one object keyed by response (host show: host, files; changeset show: change_set, reviews; changeset submit --no-wait: change_set, operation). Rendered configs mask secrets as <secret:name@vN>.
• Selectors use the short form (spec-format.md §2): --selector 'stage in (prod),!decommissioned'.
• Long operations wait and show progress; --no-wait prints the operation id instead.
• Secret values are read from stdin or --from-file, never from an argument, so they stay out of shell history and process lists.
• Retries: a 429 is repeated after its Retry-After, up to four times; reads and keyed writes are also repeated on 503 and transport errors.
• Exit codes: 0 success, 1 error, 2 usage error, 3 the command ran but found problems: validation errors, a failed check, a halted rollout, a conflict (409, 412, 422 from the server, rebase conflicts). CI fails on anything but 0.

2. Effects

Every command declares one effect. The assistant's shell offers every command except those with effect remote-write (assistant.md §4).

Effect	Meaning
local-read	Reads the working copy or local files.
local-stage	Changes the working copy only, or for context use the CLI's configuration.
remote-read	Reads through the API.
remote-stage	Writes a change set: creates, updates, validates or submits it.
remote-run	Drives a browser on a runner: acts on the target site; changes nothing in Strataplane but kept runs and the audit.
remote-write	Any other write: reviews, merges, rollouts, pins, secrets, agents, administration.

login (remote-read), context list and commands --json (local-read) and context use (local-stage) are CLI-only and not offered in the assistant's shell. commands --json [--assistant] prints the registry; the browser assistant's copy (web/src/lib/assistant/commands/registry.json) is checked against it.

3. Working copy

spec pull writes the spec tree of a revision into a directory, with .strataplane/base.json (base revision, change set) and a copy of the base tree in .strataplane/base/, so the overlay is computed offline. Edits to the files are the overlay of the change set; files that differ from the base only in formatting are not changes. Pulling the same revision again over a clean working copy keeps its change set, unless that was merged or closed.

Command	Effect	Purpose
spec pull [DIR] [--revision N]	remote-read	Write the spec tree (default: latest revision).
status	local-read	Changed files against the base; the change set and its state.
diff [PATH…] [--stat]	local-read	Diff of the overlay; --stat groups repeated replacements.
log [PATH] [--limit N]	remote-read	Revisions that changed a file, or the whole spec, with author, change set and message.
restore --revision N PATH…	local-stage	Write the files' content at rN, including deleted files, into the working copy.
rebase	local-stage	Move the working copy to the latest revision, merging the overlay three-way; conflicts are left marked in the files.

4. Preview

Previews run against the base plus the working copy's overlay (POST /api/v1/preview/*), so they work before a change set exists; --base previews the base alone. validate PATH… shows only the diagnostics of those files or directories, which must exist in the working copy, and those without a file (composition, rendering); the exit code counts every error.

Command	Effect	Purpose
validate [PATH…]	remote-read	L0–L2 diagnostics with file and path (spec-format.md §7).
render HOST [--kind K] [--version V] [--base]	remote-read	Render for the host's agent of kind K; --version renders a hypothetical agent.
explain HOST KEY[.PATH] [--kind K] [--base]	remote-read	Provenance of an instance or option (spec-format.md §4).
impact [--by KEYS]	remote-read	The impact set, grouped (e.g. --by owner,stage,version), and the approval requirements that would apply.

5. Change sets

Command	Effect	Purpose
changeset submit -m MSG	remote-stage	Create or update the change set from the overlay, validate it (L0–L3) and submit it for review. Prints the change set link. --no-wait starts the validation and returns; submit again to submit.
changeset validate [CS]	remote-stage	Validate the current digest without submitting.
changeset revert REV -m MSG	remote-stage	Create a draft that undoes revision REV.
changeset list [--state S] [--mine] [--needs-review]	remote-read	Change sets.
changeset show [CS]	remote-read	State, approved flag, validation, impact, requirements, reviews.
changeset review CS approve|reject|comment [-m MSG] [--as TEAM…]	remote-write	Review the current digest; --as limits the teams the approval counts for.
changeset merge CS [--rollout]	remote-write	Merge; --rollout starts a rollout for each affected agent kind without an active one.
changeset close CS	remote-write	Close without merging.

CS is a number (418 or CS-418) or a uuid; without it, the working copy's change set.

6. Fleet

Command	Effect	Purpose
hosts [--selector S] [--kind K] [--sort F]	remote-read	Hosts with their labels; also the way to test a selector. --sort takes the fields of listHosts (openapi.yaml), -F descending.
host show HOST	remote-read	Labels by source, agents, matching layers.
host label HOST KEY=VALUE… [KEY-…]	remote-write	Set or remove manual labels.
host forget HOST	remote-write	Forget the host and revoke its agents' credentials.
agents [--selector S] [--kind K] [--health H] [--sync S] [--version V] [--sort F]	remote-read	Agent instances; --sort as for hosts, with the fields of listAgents.
agents summary --by KEYS	remote-read	Counts grouped by health, sync, version, revisions or label keys.
agent show HOST [--kind K]	remote-read	Health, sync and reason, desired/served/applied, flags, identity.
agent config HOST [--kind K] [--desired|--served|--applied]	remote-read	A rendered config of the agent.
agent logs HOST [--kind K] [--level L]	remote-read	Heartbeat logs, or component and unit state for Elastic Agent.
agent events HOST [--kind K]	remote-read	Status transitions.
agent approve HOST [--kind K] [KEY=VALUE…]	remote-write	Approve a pending enrollment, optionally setting manual labels.
agent quarantine HOST [--kind K] --reason R / agent release HOST [--kind K]	remote-write	Stop or resume config and secret delivery.
agent action HOST --kind elastic-agent settings KEY=VALUE…	remote-write	Queue a SETTINGS action (e.g. log_level=debug).
agent revoke-credential HOST [--kind K] / agent forget HOST [--kind K]	remote-write	Force re-enrollment, or forget the instance.
agent enroll telegraf|helper --token T [--hostname H] [--agent-url URL] [--cert F --key F] [--out FILE]	remote-write	Enroll this machine and write the env file (0640; agents/telegraf.md §2). The token can come from STRATAPLANE_ENROLLMENT_TOKEN instead, which keeps it out of the shell history. For helper, strataplane-agent run reads STRATAPLANE_HELPER_TOKEN and STRATAPLANE_INSTANCE_ID from it instead of enrolling.
agent enroll vector --token T [--hostname H] [--agent-url URL] [--cert F --key F] [--ca-file PATH] [--root DIR] [--out FILE]	remote-write	Enroll this machine and install Vector's bootstrap under --root (default /): /etc/vector/strataplane.toml (0640, group vector), the VECTOR_CONFIG line of /etc/default/vector, the systemd drop-in, and with --cert/--key the identity files under /etc/vector/strataplane/ (agents/vector.md §2). --ca-file names a CA for the agent listener in the bootstrap; --out writes only the bootstrap, there.
placements	remote-read	Placements with their picks and shortfall (spec-format.md §3.9).

7. Releases, rollouts and pins

Command	Effect	Purpose
releases	remote-read	The release pointer per agent kind.
rollout list [--state S] / rollout show RO	remote-read	Rollouts; stages with agents and guardrail values.
rollout start KIND [--to REV] [--policy P]	remote-write	Start a rollout (default: to the latest revision).
rollout pause|resume|advance|abort RO [--reason R]	remote-write	Rollout actions (rollout_state).
rollout wait RO	remote-read	Wait until the rollout completes (exit 0), halts or is aborted (exit 3).
pin list	remote-read	Pins, including scheduled ones.
pin create --revision N (--selector S --kind K… | --agent HOST --kind K) --reason R [--from T] [--until T]	remote-write	Pin agents to a revision.
pin delete ID	remote-write	Remove a pin; its agents follow the release again.

8. Secrets

Command	Effect	Purpose
secret list [--owner TEAM] [--unset]	remote-read	Secrets with owner, current version and use; never values.
secret show NAME	remote-read	Versions and the agents that reference it.
secret set NAME [--from-file F] [-m COMMENT]	remote-write	Write a new version, read from stdin or a file.
secret disable NAME VERSION	remote-write	Disable a version; agents fall back to the previous one.
secret deliveries NAME	remote-read	Delivery audit.

9. Journeys and tools

Command	Effect	Purpose
journey list [--status S] / journey show NAME	remote-read	Journeys, runners and latest results (journeys.md).
journey run NAME [--runner R]	remote-run	Run the journey now on its runners, or one; prints the result per runner with the run ids (journeys.md §3.1).
journey runs NAME [--all] / journey run-show RUN [--evidence DIR]	remote-read	Kept failed runs, --all also passed ones (journeys.md §6); --evidence downloads screenshot and snapshot.
journey explore start [URL] [--journey FILE] [--allow HOST]… [--viewport WxH] [--runner R] [--screenshot FILE]	remote-run	Open a session on an exploration runner at URL, or at the file's startUrl with its allowHosts and viewport; prints the session and the page snapshot (journeys.md §8.2).
journey explore do SCRIPT [--file F] [--screenshot FILE] [--session ID]	remote-run	Run a script fragment (or the file's content) against the session's page; prints the outcome, output and snapshot, --screenshot saves the page as PNG (in the assistant's shell, whose files are text, the chat panel shows every screenshot instead, and --look on start, do and snapshot attaches it for the model).
journey explore snapshot [--screenshot FILE] [--session ID] / journey explore stop [--session ID]	remote-run	The page without acting; end the session. Without --session, commands use the caller's only open session.
journey explore list / journey explore runners	remote-read	The caller's open sessions; the exploration runners the caller may use, with their open sessions.
journey explore pair	remote-write	A pairing code and the strataplane-agent explore command that lends this computer as the caller's exploration runner (journeys.md §8.2).
journey try FILE [--out DIR] [--runner R]	remote-run	Run a Journey file once on an exploration runner; --out receives result.json, a snapshot per step (NN-<step>.snapshot.json and its text form .snapshot.txt) and the screenshot of the last step; in the assistant's shell (default /samples/runs/<name>/) only the text snapshots and result.json.
journey import-chrome NAME FILE [--owner TEAM] [--selector S] [--interval I]	local-stage	Convert a Chrome Recorder export into a Journey file with that owner (default: a placeholder), runner selector and interval (journeys.md §8.1).
telegraf-parse --version V --parser P --config F SAMPLE…	local-read	Run a Telegraf parser on samples in local wasm (agents/telegraf.md §8).
vector-vrl --version V --program F EVENTS…	local-read	Run a VRL program (a remap source) on events in local wasm; --time fixes now(), --timezone the default timezone; exit 3 when an event fails or the program does not compile (agents/vector.md §8).
mib FILE… [--object NAME]… [--telegraf] [--instance KEY]	local-read	Objects of SNMP MIB files with their numeric OIDs, kind (scalar, table, column, …), syntax, access and units; names resolve across the files and the SNMPv2-SMI roots. --telegraf prints inputs.snmp options for the objects (scalars with the .0 instance, tables with their readable columns), so pollers need no MIB files. The assistant's shell runs the same code as wasm in the browser.
import telegraf DIR [--owner TEAM] [--selector S] [--precedence N] [--prefix DIR]	local-stage	Turn a Telegraf config directory into layers under --prefix (default layers/imported) with that owner (default admins), selector (default: every host) and precedence (default 400) (agents/telegraf.md §9).
import vector PATH [--owner TEAM] [--selector S] [--precedence N] [--prefix DIR]	local-stage	Turn a Vector config file or config directory (TOML, YAML or JSON) into layers, with the defaults of import telegraf (agents/vector.md §9).
catalog search QUERY [--kind K] [--version V] / catalog show KIND SECTION.PLUGIN [--version V]	remote-read	Plugins and options, schema, sample and docs.

10. Administration

Resource commands map one to one to the API and need the roles of architecture.md §7. All have effect remote-write, except list and show (remote-read).

Command	Resource
user list / user add USERNAME / user disable|enable USER	Tenant members
team list|show|create|update|delete, team member add|remove TEAM USER	Teams
role-binding list|create|delete	Role bindings (--user, --team, --role, --tenant | --owner TEAM | --selector S)
service-account list|create|delete	Service accounts
token list|create|revoke	API tokens; create prints the token once
enrollment-token list|create|revoke	Enrollment tokens; create prints the token and install snippets once
trust-anchor list|create|delete	Trust anchors
zone list|create|delete	Network zones
audit events [--object KIND/ID] [--actor ID] [--since T] / audit sink list|create|update|delete	Audit chain and export
assistant providers get|set FILE	LLM providers (set replaces the list)
tenant show	Limits and usage
platform tenant list|show|update|delete, platform catalog import FILE, platform audit	Platform admins

11. Other binaries

Binary	Commands
strataplane	init, serve [--no-migrate], db migrate|status|backup|restore, catalog import, secrets export-key|rotate-key (operations.md)
strataplane-agent	run (the runner service), journey run FILE (journeys.md §7), explore --pair CODE (a paired exploration runner, journeys.md §8.2)

12. CI

A pipeline that generates spec files, for example node layers from an inventory export, runs with a service account token:

stratactl spec pull work && cd work
./generate-node-layers > layers/nodes/generated.toml
stratactl changeset submit -m "Node layers from inventory" -o json > cs.json   # exit 3 on validation errors
# once approved (or at once if no ApprovalPolicy matches):
stratactl changeset merge "$(jq -r .number cs.json)" --rollout -o json > merge.json
stratactl rollout wait "$(jq -r '.rollouts[0].number' merge.json)"

Service accounts can submit and merge, but never approve (architecture.md §7).