CLI

The CLI is the product's working surface. It discovers facts, records passports, selects a composition, and asks a harness provider to apply a plan. The website shows the catalog and the account. It does not write native harness state.

Every command that a person copies from this help center should be run with --json. The CLI then prints exactly one envelope on stdout and nothing else.

How to read an envelope

With ok: true, the result is in data. warnings may still be worth showing. With ok: false, error.code is a stable code from the closed registry; next_actions names a sensible next command, not a permission.

Do not guess the next step from the process exit class alone. Retry only when the envelope says retryable: true. After an unconfirmed timeout, read status before applying again.

Mutability and confirmation

These two fields answer different questions.

mutability	Meaning
read	observes; creates nothing
plan	records a checkable plan or snapshot; does not change the target
apply	changes state
destructive	discards identity or managed bytes; always a separate decision

confirmation	Meaning
none	no extra token; this is not "safe to run unasked"
explicit_flag	pass the flag the descriptor names, usually --confirm
plan_digest	pass --expected-plan-digest of an unchanged plan

A read command on a fresh install returns typed emptiness. It does not silently run device init.

Machine help is the parser

Everyday discovery:

ai-stp task intents --json

Expert full registry of this install:

ai-stp help --agent --json

Documentation groups commands so a person can find the right page. If this page and the CLI disagree, follow the CLI.

The full list, one row per command, is the command map.

Command groups

Group	Page	When you open it
Observe	Observe	first run, health, machine help
Configuration	Configuration	values this install should honour
Telemetry	Install telemetry	the optional anonymous install ping
Device	Device	identity of this installation
Passports	Passports	developer and device facts
Sign-in	Sign-in	account session and link web
Consent	Consent	unverified publishers and major lines
Project	Project	discover, index, symbols, project passport
Toolchain	Toolchain	managed tools and harness survey
Harness program	Harness program	the harness binary, not the setup
Agent Skill	Agent Skill CLI	the CLI's own skill, not kind skill
Registry	Registry	catalog search, fetch, local ports
Component	Component commands	discover → passport → publish
Select	Select	eligibility, proposal, reports
Install	Install	install intent; expert recover/resume remain
Target	Target	daily status, diff, backups, named rollback
Setup	Setup commands	compose, import, update, publish
Provider	Provider	the binary that writes native state
Sync	Sync	private account stream
Grants	Access grants	major-line access
Reports	Reports	closed report cases
Owner	Owner objects	server-side objects you own
Publication	Publication	attest, plan, confirm
Eval	Eval	local reference evaluation

A working loop

task intents --json
→ task start --intent <shipped> --idempotency-key <key> --json
→ follow continuations (execute argv only when actor is cli)
→ report payload verification

Expert leaves (install plan / approve / apply) stay available for recovery. Everyday install, change, and switch drain those steps in-process under the matching intent.

The agent may skip a step only when the previous envelope already made it unnecessary. It may not skip a mechanical check.

What the CLI never does

• call a model API or ask for a model key;
• write the harness target itself — only the public provider does;
• put secrets, .env bodies, or tokens into a passport;
• treat author_verified as proof that a component version is safe.

Typical refusals

What you see	What it means	What to do
a mutating command without --json	mixed human text on stdout	add --json and read one envelope
stale plan	the plan bytes changed	build a new plan, show it, confirm again
confirmation missing	explicit_flag or plan_digest was required	read the descriptor; do not invent a flag name
command absent from machine help	this install does not have it	stop; do not substitute a similar command

The first-run path in prose is Quickstart for people. The session ritual for an agent is Quickstart for agents.