Skip to main content
Every command accepts a global --json flag that emits a stable envelope to stdout for scripting, piping, and coding agents: {"success": true, "data": …} on success, {"success": false, "error": {"code", "message", "suggestion"}} on failure. Run apollo <command> --help for the live flag list on your installed version.

Quick Reference

Global Flags

Place global flags before the subcommand; command-specific flags go after it (apollo --json push -m "…"). Exit codes: 0 success · 1 runtime/API failure · 2 validation failure (including a red --follow run and an unmet chat --script expectation) · 3 authentication/configuration failure, or a usage error · 130 stopped with Ctrl+C · 141 the reader went away (apollo … | head). When something is out of date, either envelope can also carry an update, skills_update, or runtime_update field — see Staying up to date.

Session & Context

Authenticate with Apollo. With no options, opens the browser sign-in flow.
Invalidate the remote session (best-effort) and remove the local credential.
Ask the server whose session this is — the answer comes from the server, not from reading the token. Prints the email and user id, the profile, the organization and project commands act in, where the token came from (APOLLO_TOKEN in the environment, or a saved login), and when it expires.
It refreshes a saved login the way every command does, so a session that answers here is one the next command can use. Not logged in exits 3. apollo status is the offline view of the same context.
Show the active Apollo context: profile, checkout, authentication, organization, project, agent, version, runtime, and token expiry.
--check also reports when the checkout’s runtime pin is behind or no longer served — the conditions that make commands refuse (see apollo runtime).
Diagnose the setup end to end: runtimes (Node/Bun), install origin, shell integration, APOLLO_* overrides, the proxy in use, terminal capabilities, credential permissions, token expiry, the current checkout, and service reachability. Read-only, with the fix attached to every finding; exits 2 on problems. Share its output when reporting issues.
Upgrade Apollo from npm (@aui.io/apollo).
After an upgrade, it names the apollo release-notes --since <old version> command that lists what changed.
What changed in the CLI and in the runtime this checkout runs on, and what to do after a version change.
The CLI’s notes ship inside the build, so they answer offline. The runtime’s notes cover the runtime the checkout runs on and every newer one — outside a checkout, or on Beta, the newest — and a BREAKING line means your program needs a change. Both end with what to do after a CLI or runtime change. With --json, the result carries cli, engine, and guidance.
Needs Apollo CLI 0.1.111 or later.
Show or select the active credential profile. Profiles keep separate credentials for different users or contexts.
--profile <name> before any command is a one-command override; it does not change the saved default. Change the default with apollo profile use.
List organizations and re-scope the access token to one. use without an id opens an interactive picker (--name <filter> narrows it).
You rarely need this directly — apollo agent use switches the organization-scoped token automatically when the selected agent requires another org. With APOLLO_TOKEN set there is no saved session to re-scope, so org use refuses: use a token for the organization you want.
Manage projects — the containers agents live in. use inside a checkout updates that checkout’s .apollorc; outside any checkout it sets the account default.

Agents & Checkouts

Manage agents and their local checkouts. A checkout is a directory holding one agent, pinned by its own .apollorc. With shell integration, use, import, and create also cd into the checkout.
agent create options:A new agent starts on the runtime you chose — --runtime-version, APOLLO_RUNTIME_VERSION, or the pin of the checkout you’re standing in (never a Beta one) — else on the newest published runtime; a chosen runtime that isn’t offered is refused before anything is created. The agent goes in the active project, which must belong to the organization you’re signed in to: if it doesn’t, agent create creates nothing and says so. Switch to the project’s organization with apollo org use, or pick one of your own projects (apollo project list, then --project <id>).agent import options:Import writes .apollorc, materializes the program files, registers the checkout, makes the agent active, installs the authoring skill packs, and records a local diff baseline. It pins the runtime the imported version was last pushed for — --runtime-version overrides it — so the checkout reproduces the agent as it is. agent use only enters checkouts already known to the registry — import remote-only agents first.
There is intentionally no delete command. agent unlink removes only the local binding.
Select the runtime (engine build) this checkout runs against. The pin lives in .apollorc, so every command in the checkout agrees on it.
use with no argument opens a picker. Moving the pin also refreshes the schemas, skills, and AGENTS.md the new runtime serves; the program is untouched. The next push records the new pin on the version — when the program hasn’t changed, apollo push --restamp commits it anyway. --runtime-version <v> before any command tries another runtime for that one command without moving the pin.When a command refuses on the pin. chat, validate, advise, build, push, regress, evaluate, and skills update check the pin first:Both errors name the exact command to run.
The skill packs, AGENTS.md (with its CLAUDE.md copy), and schemas/ a checkout gets from the runtime its version runs on.
skills update never touches the program (bundle/src), so it works on a checkout with local changes, where pull would refuse. It rewrites the skill folders that already hold Apollo’s packs (.cursor/, .claude/, .opencode/), or Cursor’s and Claude Code’s when none do. --check answers current, stale, unknown, or none and exits 0 either way — scripts read data.state. Commands tell you when a checkout’s skills fall behind its runtime — see Staying up to date.
Needs Apollo CLI 0.1.110 or later.

Authoring

Commands that take a <ref> accept a revision (v3.7), a version (v3 — its newest revision), a version’s name, or live — the revision callers get.
Validate the local agent program — the engine’s verdict plus the orphan and era censuses, which are advisory and never change the verdict. Exits 2 on findings.
Show what changed, line by line: your edits against the revision the checkout started from, the checkout against a revision, or two revisions.
Program files are listed by path, and changes under bundle/build/ are prefixed build/. A revision you compare with is fetched into bundle/tmp/versions/<tag>/. With --json, the result carries patches (path → patch).
Show one revision — its version and files — or, with a path, that file’s text as the revision has it. Nothing in the checkout changes.
Paths are the ones apollo diff prints.
Put program files back the way the checkout’s base revision has them — or another revision, with --source.
A file you deleted comes back. A file the source doesn’t have is never deleted: named, it is refused; under --all it is kept and listed. The text being overwritten is copied to bundle/tmp/restored/<time>/ first. restore doesn’t touch bundle/build/ — apollo pull --force re-syncs that.
Bring another version’s changes into bundle/src — a three-way merge over the revision both came from. Where both sides changed the same lines, your text is kept: no conflict markers are written. Each disputed region is listed under Decisions needed with the base, your text, and theirs, and their copy of the file lands in bundle/tmp/versions/<tag>/. Decide each region by editing the file, then apollo validate and apollo push.
merge-from is also the way out when someone pushed to your version after your checkout started: bring their revision in (a clean merge moves the base for you; with disputes, decide them and run --resolved), then push again. --only never moves the base. --abort keeps one undo and works until the checkout is next pushed or pulled; after that, take single files back with apollo restore <file> --source <ref>.
Pull the selected version plus the schemas, skills, and AGENTS.md its runtime serves — the program (and the agent’s build bundle into bundle/build/), the authoring JSON Schemas, the skill packs, and AGENTS.md with its CLAUDE.md copy. Pull refuses to overwrite local changes unless forced; a successful pull makes bundle/src (and bundle/build) match the remote snapshot exactly, including deleting local files no longer in the remote bundle.
Validate and push local changes — a changed program mints a revision; a changed bundle/build ships a build bundle. Push validates first, commits the bundle onto the version the checkout is bound to, updates .apollorc to the returned tag, and refreshes the diff baseline.
When the version can’t take the push:
  • It’s locked or archived. The push starts a new draft version, ”… (continued)”, cut from the revision your checkout is based on, and says so. The checkout works on that version from then on.
  • Someone pushed to it after your checkout started. The push is refused (VERSION_MOVED, exit 3), naming the newer revision and who pushed it. Bring their changes in with apollo merge-from <revision> and push again, or push yours as a new version with --new-version. There is no force.
  • Your edits are based on another version. After apollo version use without a pull, the push is refused: bind the original version again, or push your edits as a new version with --new-version.
  • It would move the version to an older runtime. Each revision records the runtime it was pushed for, so a push from a checkout pinned to an older runtime family is refused (RUNTIME_DOWNGRADE). Move the pin with apollo runtime use, or pass --allow-runtime-downgrade on purpose.
If a push’s answer never comes back — a timeout, or a gateway error — the revision may still have landed, so the CLI never pushes twice. It checks the version instead: when the newest revision is yours, with exactly the files you sent, the push is reported as done; otherwise it stops with PUSH_OUTCOME_UNKNOWN (exit 1). Check apollo version log before you push again.
Pushing never changes what callers get — make a revision live with apollo version live <tag>.
Manage the agent’s versions and choose what goes live. A version is a line of revisions: v3 is the version, and each push adds a revision — v3.1, v3.2, and so on. Live is one exact revision, and pushing never moves it.
The CLI’s own help and output call a version a branch and a revision a commit. apollo version and apollo branch are the same command.
Confirmations. live, publish, and archive say whose callers move from which revision to which and, at a terminal, ask Continue? [y/N]. --dry-run prints the move and changes nothing; --yes confirms without asking. Without a terminal — CI, coding agents, --json, or --no-input — they don’t ask: they proceed with a warning. Set APOLLO_REQUIRE_CONFIRM=1 to make them refuse there unless --yes is given.use changes only the binding in .apollorc, never bundle/src — follow it with apollo pull, or use apollo pull --tag <version> to do both. To talk to a revision without binding it, use apollo chat --at <ref>.version try-beta copies the checkout’s version into a new version labelled Beta, runs it on the Beta runtime, moves the checkout onto it, and rebuilds and evaluates it there. Your own version doesn’t change. Options: --dry-run (writes nothing) · --label <name> (name the new version) · --no-build (skip the rebuild) · --model <model> · --max-usd <usd>.

Server-Side Authoring & Evaluation

Ask the server-side authoring advisor — ships this checkout’s tree and waits for grounded advice.
Run one build turn over this checkout’s pushed agent, server-side. The turn is gated: green pushes a new revision and pulls it into the checkout; red refuses.
Run the scripted suite (bundle/build/scenarios.yaml, a version: 2 suite of cases) live through the simulator — every turn said as written, a real conversation per case, nobody improvising. The run is frozen at start, so you can keep editing while it runs. No push needed, and it reports rather than gates.Every run is graded the same way: a deterministic judge answers each case’s questions from the transcript and the engine’s own record of each turn, so a regression gives the same answer twice. --explain adds the LLM judge, which scores the case’s judgments and explains every bad answer — the verdict is the same either way.
Evaluate the agent with improvising simulated callers, planned from guidelines you write in plain words together with the capability cards in bundle/build/spec.yaml, graded by a judge, ending on a computed verdict — summary, findings, coverage per card, and candidate scenarios for the scripted suite. Where regress replays fixed turns, evaluate explores.Push first. The run executes the tree in front of you, frozen at start, but a pass counts for your version only when that tree matches what you pushed.
Guidelines are required unless you pass --plan-from, which reuses the earlier run’s guidelines and plan; it can’t be combined with --simulations, --min-turns, --max-turns, --seed, or --return.

Testing & Inspection

Chat with an agent: each reply comes with what the agent did and whether its checks passed. Alias: apollo send. Calling apollo chat with no text opens an interactive session in a terminal — /new starts a new thread, /thread shows its id, /trace toggles how the agent got each reply, /caller [id|none] changes the test caller, /exit leaves. Scripts should pass text explicitly with --no-input.
What you get. Each reply comes with one line per step on stderr — the intent it took, the capabilities it ran, what it looked up — and its checks verdict, then the reply and the thread id on stdout:
When a policy refuses, a capability is blocked, a change waits for the caller’s go-ahead, a check replaces the reply, or the engine fails, the summary says so on its own line. What the turn did outside the conversation gets a line too — a tap’s send, a write that didn’t land, the outcomes that fired, a hand-off to a person. At a terminal, the steps stream in as the agent works.Multi-turn. A send without --thread creates and persists a thread — capture data.thread_id from --json output and pass --thread on later turns:
A thread stays on the revision it started on: --thread runs that revision, and an --at naming a different one is refused. Turns on one thread are strictly sequential (a racing turn is refused with API_423), but separate threads share nothing — run them concurrently (around 20 parallel threads is a sane cap).Scripted conversations. --script runs a YAML or JSON file of turns on one thread and checks each turn’s expect against its reply and trace:
turns.yaml
Every key is optional, and a file holds at most 200 turns (so does - on stdin). A turn can name its own caller: (or caller: none); --caller sets it for every turn that names none, and every caller is checked before the first message goes out. Each expectation prints ✓ or ✗ under its turn, the run ends with a tally (Expectations: 7 of 8 met.), and it exits 2 when any is not met. With --json the envelope still reports success: true — read the exit code, or data.expectations.passed.
Inspect Apollo threads. Messages are sent as the signed-in user, and thread list lists the signed-in user’s threads unless you ask for everyone’s.
Inside a checkout, thread list shows your threads with that agent, newest first; outside one, or with --all-agents, your threads with every agent. A page ends with a More: line naming the command for the next page.Every filter narrows one agent’s threads, so it needs a checkout and can’t be combined with --all-agents. trace returns the runtime’s official turn-trace view, whose vocabulary is the program’s capabilities, policies, facts, sources, and records; at a terminal it then prints what each turn did, the way chat does.
Open the Playground on this checkout’s agent and revision, or on a thread.
The link always prints; when no browser can be started, the command says so and still succeeds.

Resources

The agent’s knowledge hubs — the corpora that hub: sources search at runtime. A source in bundle/src/sources.yaml names its hub (hub: <name>), and the match is by name. Every kb command needs an agent checkout.
A hub is inert until a live bundle declares it: the agent consults a hub only because a kind: knowledge source in the running program names it. After uploading, declare the hub in bundle/src/sources.yaml, then apollo push and make that revision live with apollo version live. A reference to a nonexistent hub retrieves nothing, with no validation error.
Manage vault secrets. A connection refers to one by name — as its token_env, or as ${NAME} in bundle/src/connections.yaml — so the value itself never enters the bundle.
Manage the per-agent mock database — a test database the agent’s connections can run against. Management calls carry your Apollo login, and the agent must be in your current organization. Runtime calls use the per-agent runtime key: apollo mockdb execute takes it from $MOCKDB_TOKEN, else the local key cache, and the deployed agent reads it from the vault secret its connection names (token_env). Every subcommand but guide takes --agent <id> (default: the checkout’s agent) and --account <id> (rarely needed; also APOLLO_ACCOUNT_ID).
To change data later, reach for reset, collections truncate, seed --mode upsert|replace, or rows patch — never delete then provision, which mints new keys and breaks everything that uses the old runtime key.

Support & Shell

File a fault that isn’t your program’s — the engine contradicting its reference, the CLI breaking its contract, a platform call that keeps failing, or docs that teach something the engine refuses — with its evidence, so the people who own it can act without asking you.
Describe the fault with --summary, --step (repeatable, in order), --expected and --actual, --impact and --severity (blocker, major, minor), --frequency (always, intermittent, once), --evidence (repeatable), --file (repeatable), --thread and --run (repeatable), --since, --tried (repeatable), --cause, and --workaround; name the failure with --command, --error-code, --error-message, and --request-id. --confidence confirmed needs a reproduction; anything less is suspected (the default).The CLI attaches when it happened, the checkout (agent, version, runtime pin, engine build, the names of the program files changed since the last pull, the last run ids), and its own version and machine. When Claude Code runs it, it also attaches that session’s shell commands (a failed one with the tail of its output) and the paths of the files it edited, scrubbed of secrets — never your prompts, never file contents; --session <id> picks the session and --no-session leaves it out. --dry-run prints the exact report and needs neither a login nor the network.Filing needs your login. The command answers with the identifier the report was filed under — quote it when you contact AUI — and the same report within a day adds an occurrence to that report instead of filing a new one.
Background reports. The CLI also files its own hard faults — a crash, or a 5xx from a service — after the error is printed, without changing the command’s output or exit code. Each carries the same context as a manual report, plus the failing command line (secret-shaped values masked) and that command’s recent API calls: method, URL, status, and timing, never headers or bodies. APOLLO_REPORTS=0 turns off both kinds; nothing else does. Needs Apollo CLI 0.1.112 or later.
Print the shell wrapper (zsh/bash) enabling auto-cd after agent use / agent import / agent create. Add to your shell profile:

Next Steps

Configuration

Checkout structure, config files, and environment variables.

Workflows

Common development workflows and patterns.