Agents from the CLI
Configure environments and secrets, start agent sessions on a harness, follow them, answer the decisions they stop on, and watch several at once.
From a shell, a person or a coding agent can run Standards agents end to end: prepare the environment a session runs on and the secrets its machine receives, start a session on a harness, follow its turn to the end, answer the decision it stops on, and open the links its machine publishes. Every output is plain text or JSON, so a model reads it as well as a person.
standards guide agents prints the same loop as a guide written for an agent, matching the installed version. See How to use the CLI.
Environments
standards environments list
standards environments get <env>
standards environments harnesses
standards environments create --name ci --harness claude-code,codex --repo acme/api --size default --max-size large --image code
standards environments create --name docs --harness standards --image documents
standards environments update <env> --size large
standards environments build <env>
standards environments archive <env> --yes<env> is an environment id or its name. A name no environment holds is refused with No environment named "<name>"; a name two environments share is refused with both ids and their owners, and you pass the id instead.
| Flag | create and update |
|---|---|
--name <name> | Its name. Required on create. |
--harness <id,…> | The harnesses it accepts: claude-code, codex, cursor. standards accepts the built-in agent only. |
--repo <owner/name> | A repository its machines clone. Repeat it once per repository. |
--size <size>, --max-size <size> | The size its machines start at, and the largest a run may ask for: small, default or large. |
--image <image> | Its base image: code or documents. |
--visibility <visibility> | private (default) or workspace. A workspace environment shares its machine, so it also needs --confirm-shared. |
harnesses lists each harness with the models it offers. build rebuilds the environment's image. archive refuses to run without --yes.
Secrets
A secret is an environment variable a session's machine receives. The CLI reads its value from stdin only: never from an argument, never from a prompt.
printf %s "$ANTHROPIC_API_KEY" | standards secrets set ANTHROPIC_API_KEY --environments all
printf %s "$OPENAI_API_KEY" | standards secrets set OPENAI_API_KEY --environments ci,staging
printf %s "$TOKEN" | standards secrets set GITHUB_TOKEN --private
printf %s "$TOKEN" | standards secrets set NPM_TOKEN --env ci --repository acme/web
printf %s "info" | standards secrets set LOG_LEVEL --plain --environments allstandards secrets list
standards secrets list --env ci
standards secrets delete NPM_TOKEN --env ci --repository acme/web --yes| Scope | Flags | Reaches |
|---|---|---|
| Workspace (default) | --environments <env,…|all> | A new workspace secret is listed on the environments --environments names, all meaning every environment that exists now. Without it, it is listed nowhere, and the command prints on stderr Used by no environment yet: re-run with --environments <env,…|all> (all = every current environment). An existing key keeps the environments that list it. Agents and routines list workspace variables in the app. |
| Personal | --private | The sessions that act for you, on every environment. |
| Environment | --env <env> [--repository <owner/name>] | The sessions on that environment, or only that repository's processes with --repository. Only the environment's owner writes them. |
A value is stored as sensitive unless --plain says otherwise. secrets list never prints a value, sensitive or not. set refuses a terminal on stdin, before any request: pipe the value. --repository is only accepted with --env. delete refuses to run without --yes; with --env, it deletes the environment-wide value, or the one --repository names. A key nobody holds is refused with No secret named "<KEY>". Logins (a password and its TOTP) are set in the app. The layers and how a run reads them are on Environments.
Sessions
standards sessions start "Fix the failing test in api/" --harness claude-code --env ci
standards sessions start "Fix issue 101" --harness codex --detach
standards sessions send <id> "Now open a pull request"
standards sessions follow <id>start creates a session and sends its first message; send sends the next one. Both then follow the turn they started, and only that turn, until it ends. follow follows the turn that is running, or the next one to start; on a session with no turn running it returns at once with the last outcome.
| Flag | On start |
|---|---|
--harness <id> | The harness that pilots the machine. |
--env <env> | The environment it runs on. |
--size <size>, --model <id>, --name <name> | The machine size, the model and the session's name. |
--detach | Prints { id, url } and returns once the message is sent, without following. send takes it too. |
If the message cannot be sent once the session exists, start prints { id, url } on stderr with the standards sessions send <id> "<task>" command to run, and exits 1. Run that command: starting again would create a second session.
Following a turn
A followed turn writes the reply as it comes, → tool <name> for each tool call, and ↺ retrying step when a step restarts: the text before it is dropped. With an explicit --format json, it writes one JSON object per line instead: {"type":"text","text":"…"}, {"type":"reset"}, then {"type":"end","outcome":"…"}. A dropped stream reconnects by itself, so following is never a reason to send again.
| Exit code | Meaning | Next |
|---|---|---|
0 | The turn completed. | Read the reply, or send the next message. |
1 | The turn failed, or was cancelled. | sessions get <id>, then send to retry. |
1 | The session stream did not open after 10 attempts: the API was unreachable for about 40 seconds, and the turn may still be running. | sessions follow <id>, never send. |
3 | The agent stopped on a decision, printed with its numbered options. | Answer it, then sessions follow <id>. |
If the decision is not open yet when the turn ends, the command prints decision not opened yet: run "standards decisions list" and still exits 3.
Reading sessions
standards sessions list --running
standards sessions get <id>
standards sessions messages <id> --last 5
standards sessions cancel <id>
standards sessions archive <id>list takes --running (sessions running or waiting on a decision), --q <text> and --limit <n>. get prints one object, { session, phase, lastReply, waiting, machine, links, decisions }: lastReply is the last assistant text, waiting is true while a message you sent is not yet read, and before the first turn machine is null and links is empty. messages requires --last <n>.
Decisions
standards decisions list
standards decisions list --all
standards decisions show <id>
standards decisions answer <id> <answer…>With the CLI's personal key (standards login), a session you start is yours and its decisions are addressed to you, while standards decisions still reads and answers the key's own decisions: list stays empty and the session's decision is answered in the app for now.
list shows the open decisions, every state with --all: the id, the type, the title, the sender, and each question with its context, when it has one, and its options numbered from 1. show adds the decision's links, the setup commands it asks for and its URL in the app. How a decision is answered depends on its kind:
| Kind | Answer |
|---|---|
| Approval | answer <id> yes, or answer <id> no --reason "too risky". |
| Question | One answer per question, in order: an option's number (2), its label (case does not matter), 1,3 for a question that takes several, or free text. --skip skips them all. |
| Review | answer <id> yes, or answer <id> changes --feedback "tighten the tests". |
| Agent setup | answer <id> continue, or skip. |
| Bundle setup | answer <id> configure. |
| Any other | Answered in the app: the command is refused with the decision's URL, before any request. |
A question answered with fewer or more answers than it has questions is refused before any request. Whether a free text fits a question is the server's call, and its refusal is printed as is; so is the refusal of a decision that is no longer open.
A secret is never an answer
An agent setup decision that asks for a variable is answered by setting it, not by typing it into the answer. decisions show <id> prints, for each missing variable, the exact printf %s "$VALUE" | standards secrets set <KEY> … command to run. Run it, then answer <id> continue.
Machines and links
standards machines list --env ci
standards machines get <id>
standards machines runs <id>
standards machines destroy <id> --yes
standards links open <linkId>
standards links relaunch <linkId>
standards links extend <linkId> --for 2hmachines list reads every page; get prints the machine, its lease, its pilot and its links; runs lists the runs it served; destroy refuses to run without --yes. A session's links are also in sessions get <id>.
links open prints one URL and nothing else. relaunch reruns the link's command, waking the machine first. extend makes the link expire a duration from now: 30m, 2h or 1d, at most one day; a longer one is refused before any request.
An opened link is a credential
The URL links open prints carries a single-use token valid for 60 seconds: anyone holding it opens the link as you. Open it right away; never paste it into a message, a file, a log or a decision.
Monitoring
standards status
standards --format json status
standards watch
standards watch --interval 30s --until decisionstatus reads once what is in flight: the sessions running or waiting on a decision, the open decisions, and the running machines with their links. It prints a table, or one object { sessions, decisions, machines } with an explicit --format json.
watch polls and writes one line per change, nothing when nothing changed. Its first poll prints the current state as snapshot lines, then each transition:
| Line | When |
|---|---|
session <id> running→idle | A session's turn ended. |
session <id> → parked | A session stopped on a decision. |
session <id> failed | A session's turn failed. |
decision <id> opened "<title>" | A decision opened. |
decision <id> answered | A decision was answered. |
link <slug> published <url> | A machine published a link. |
machine <id> stopped | A machine stopped. |
--interval defaults to 10s and is at least 2s. Sessions and decisions are read on every poll; machines only when a session changed phase, and otherwise at most once a minute. With an explicit --format json, each line is a JSON object. --until decision exits 3 as soon as a decision is open, one already open at the first poll included, its line last; without it, watch runs until interrupted. A failed poll writes poll failed: <message> and retries; five in a row exit 1. To wait for one session, use sessions follow.
The loop end to end
printf %s "$ANTHROPIC_API_KEY" | standards secrets set ANTHROPIC_API_KEY --environments all
standards environments create --name api --harness claude-code --repo acme/api
standards sessions start "Upgrade the ORM and fix what breaks" --harness claude-code --env api
# exit 3: a decision waits
standards decisions show <decisionId>
standards decisions answer <decisionId> 1
standards sessions follow <sessionId>
# exit 0: done
standards sessions get <sessionId>Several sessions at once start detached, and watch tells you which one needs you:
for task in "Fix issue 101" "Fix issue 102" "Fix issue 103"; do
standards sessions start "$task" --harness claude-code --env api --detach
done
standards watch --until decision
standards decisions listNext steps
- Environments: images, harnesses, variables and their layers.
- Machines and links: what a machine is and who may open its links.
- Decisions: every kind of decision and where it is answered.
- How to use the CLI: profiles, global flags and exit codes.
- Book a demo