Command Reference

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

Command	Description
`apollo login`	Authenticate with Apollo
`apollo logout`	Remove the active session
`apollo status`	Show the active context
`apollo doctor`	Diagnose the setup end to end
`apollo upgrade`	Upgrade the CLI from npm
`apollo profile`	Show or select the active credential profile
`apollo org`	Select an organization
`apollo project`	Manage projects
`apollo agent`	Manage agents and checkouts
`apollo runtime`	Select the runtime (engine build) a checkout runs against
Authoring
`apollo validate`	Validate the local agent program
`apollo diff`	Compare local files with the last baseline
`apollo pull`	Pull the selected agent version, schemas, and skills
`apollo push`	Validate and push local changes as a new version
`apollo version`	Manage agent versions
Server-side authoring & evaluation
`apollo advise`	Ask the authoring advisor a grounded question
`apollo build`	Run one gated build turn server-side
`apollo regress`	Replay the scripted suite through the simulator
`apollo evaluate`	Explore the agent with improvising simulated callers
Testing & inspection
`apollo chat`	Chat with an agent (alias: `apollo send`)
`apollo thread`	Inspect threads, messages, and traces
Resources
`apollo kb`	The agent’s knowledge hubs
`apollo vault`	Manage vault secrets used by `connections.yaml`
`apollo mockdb`	Manage the per-agent mock database
Shell
`apollo shell-init`	Print the shell wrapper enabling auto-cd

Global Flags

Place global flags before the subcommand; command-specific flags go after it (apollo --json push -m "…").

Flag	Description
`--json`	Emit a stable JSON envelope
`--quiet`	Suppress progress and warnings
`--verbose`	Diagnostic details, including one redacted line per API request
`--no-input`	Disable interactive input
`--yes`	Confirm prompts
`--profile <name>`	Override the active profile for this command
`--project <id>`	Override the active project
`--org <id>`	Override the active organization
`--runtime-version <v>`	Override the checkout’s pinned runtime (env: `APOLLO_RUNTIME_VERSION`)
`--timeout <ms>`	Request timeout in milliseconds (env: `APOLLO_TIMEOUT_MS`)

Exit codes: 0 success · 1 runtime/API failure · 2 validation failure · 3 authentication/configuration failure.

Session & Context

Authenticate with Apollo. With no options, opens the browser sign-in flow.

apollo login                             # browser flow
apollo login --email user@example.com    # email OTP (re-run with --otp <code>)
apollo login --token "$ACCESS_TOKEN"     # store a pre-issued JWT

Option	Description
`--sso`	Use the browser login flow
`--email <email>`	Send an email OTP
`--otp <code>`	OTP code (with `--email`)
`--token <jwt>`	Store an existing access token
`--url <url>`	Override the Playground login URL

apollo logout

Invalidate the remote session (best-effort) and remove the local credential.

apollo logout

apollo status

Show the active Apollo context: profile, checkout, authentication, organization, project, agent, version, runtime, and token expiry.

apollo status
apollo status --check    # also check service connectivity and authorization

apollo doctor

Diagnose the setup end to end: runtimes (Node/Bun), install origin, shell integration, APOLLO_* overrides, 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.

apollo doctor
apollo doctor --offline    # skip connectivity checks

apollo upgrade

Upgrade Apollo from npm (@aui.io/apollo).

apollo upgrade            # install @latest
apollo upgrade --check    # show the available version without installing
apollo upgrade 0.2.1      # install a specific version or tag

Option	Description
`--check`	Show the available version without installing
`--force`	Reinstall even when already on that version

apollo profile

Show or select the active credential profile. Profiles keep separate credentials for different users or contexts.

apollo profile current
apollo profile list
apollo profile use work

--profile <name> before any command is a one-command override; it does not change the saved default. Change the default with apollo profile use.

apollo org

List organizations and re-scope the access token to one. use without an id opens an interactive picker.

apollo --json org list [--name <filter>]
apollo org use [org-id]

You rarely need this directly — apollo agent use switches the organization-scoped token automatically when the selected agent requires another org.

apollo project

Manage projects — the containers agents live in. use inside a checkout updates that checkout’s .apollorc; outside any checkout it sets the account default.

apollo --json project list [--name <filter>]
apollo project use [project-id]
apollo project create "Display name"

Agents & Checkouts

apollo agent

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.

apollo --json agent list [--name <filter>]     # filter is server-side
apollo agent use [agent-id|name]               # enter a KNOWN checkout
apollo agent path                              # print the last-used checkout path
apollo agent create "Agent name"               # provision + create a checkout
apollo agent import [agent-id]                 # pull a cloud agent into a checkout
apollo agent unlink                            # remove the local binding only

agent create options:

Option	Description
`--dir <path>`	Checkout directory (defaults to a managed directory under `~/apollo/`)
`--template <id>`	Template agent to go live on immediately (default: empty draft)

agent import options:

Option	Description
`--name <filter>`	Filter the interactive picker by name
`--tag <tag>`	Version tag (defaults to the live version)
`--dir <directory>`	Checkout directory (defaults to a managed directory under `~/apollo/`)
`--skills <targets>`	Comma-separated `cursor,claude,opencode` (default: `cursor,claude`)
`--force`	Overwrite an existing local program

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. 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.

apollo runtime

Select the runtime (engine build) this checkout runs against.

apollo runtime list           # runtime versions this account can select
apollo runtime show           # the runtime this checkout is pinned to
apollo runtime use [version]  # pin a version ('latest' takes the newest)

Authoring

apollo validate

Validate the local agent program — the verdict plus the orphan and era censuses. Exits 2 on findings.

apollo validate [directory]    # defaults to the bound checkout
apollo validate --fix          # apply the build-bundle audit's mechanical repairs

Option	Description
`--fix`	Apply the build-bundle audit’s mechanical repairs (files moved home, retired keys respelled, case prose lifted onto its need), then report what remains

apollo diff

Compare local files with the last baseline (the last successful import, pull, or push).

apollo diff
apollo diff --remote    # compare with the selected remote version instead

apollo pull

Pull the selected agent version plus the schemas, skills, and AGENTS.md its runtime serves. Pull refuses to overwrite local changes unless forced; a successful pull makes bundle/src match the remote snapshot exactly, including deleting local files no longer in the remote bundle.

apollo pull
apollo pull --tag v2.3
apollo pull --force      # discard local bundle changes and match remote

Option	Description
`--tag <tag>`	Version tag
`--dir <directory>`	Destination directory
`--force`	Discard local bundle changes and match remote
`--skills <targets>`	Comma-separated `cursor,claude,opencode` (default: `cursor,claude`)
`--no-skills`	Skip the skill packs and the checkout’s `AGENTS.md`
`--no-schemas`	Skip the authoring JSON Schemas

apollo push

Validate and push local changes — a changed program mints a version; a changed bundle/build ships a build bundle. Push validates first, creates a draft from a published version when necessary, commits the bundle, updates .apollorc to the returned tag, and refreshes the diff baseline.

apollo push --dry-run                       # validate and show the diff without pushing
apollo push -m "Tighten refund eligibility"

Option	Description
`-m, --message <message>`	Commit message
`--dry-run`	Validate and show the diff without pushing

Pushing is not publishing — a pushed version goes live only after apollo version publish <tag>.

apollo version

Manage agent versions.

apollo --json version list
apollo version get v2.3
apollo version use v2.3                              # bind a tag in this checkout
apollo version create --from v2.3 --label "Variant"  # clone an existing version
apollo version create --label "Empty draft"
apollo version publish v3.0
apollo version archive v2.3

version create options: --from <tag> (clone an existing version) · --template <id> (create from a template) · --label <label> · --notes <notes>.use binds a version tag in the checkout — the push base and pull default. publish is also the rollback/switch operation: publishing an older version makes it live again. Don’t archive the live version.

Server-Side Authoring & Evaluation

apollo advise

Ask the server-side authoring advisor — ships this checkout’s tree and waits for grounded advice.

apollo advise "Why doesn't the refund gate fire on turn two?"

Option	Description
`--fresh`	Start a new advisor thread instead of continuing the saved one
`--model <model>`	Advisor model override
`--max-usd <usd>`	Per-question spend cap (server default applies otherwise)

apollo build

Run one build turn over this checkout’s pushed agent, server-side. The turn is gated: green pushes a new version and pulls it into the checkout; red refuses.

apollo build "Add a fee waiver for premium members" -m "Fee waiver"

Option	Description
`--version-tag <tag>`	The base version to build from (defaults to the pin)
`-m, --message <text>`	The push message
`--model <model>`	Build model override
`--max-usd <usd>`	Per-turn spend cap (server default applies otherwise)
`--evaluate`	Run the evaluation suite on the result before pushing
`--publish`	Flip the agent’s active pointer to the pushed version

apollo regress

Run the scripted suite (bundle/build/scenarios.yaml) live through the simulator — every turn said as written, one real conversation per scenario, 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.With the judge off, a scenario passes when its script ran clean end to end; --judge also grades each conversation against the cases it covers.

apollo regress --follow                      # wait for the verdict; exits 2 on red
apollo regress --judge                       # also grade each conversation against its cases
apollo regress --scenarios REF-01,REF-02     # run part of the suite
apollo regress --pull --failures-only        # fetch the failures for reading

Option	Description
`--scenarios <codes>`	Comma-separated scenario codes (default: the whole suite)
`--judge`	Grade each conversation against the cases it covers (`build/cases.yaml`)
`--follow`	Wait for the verdict instead of returning the receipt; exits `2` on red
`-m, --message <text>`	A note on the run — shows up on the report
`--version-tag <tag>`	The tag stamped on the minted trial threads (defaults to the pin)
`--status` · `--cancel`	Read a run’s report, or cancel a live run, instead of starting one
`--pull` · `--failures-only`	Fetch the run’s conversations, traces and verdicts into `tmp/<lane>/<id>/`
`--annotate <text>` · `--verdict <pass\|fail\|mixed>`	Append your reading to a settled run
`--id <run-id>`	The run the flags above mean (defaults to the last started)

apollo evaluate

Evaluate the agent with improvising simulated callers, planned from guidelines you write in plain words together with the bundle’s own records (cases.yaml, needs.yaml, world.yaml), graded by a judge, ending on a macro verdict — summary, findings, per-case coverage, and candidate regression scenarios. Where regress replays fixed turns, evaluate explores.Push first: the run binds to a pushed version.

apollo evaluate "the refund refusal path after this change" --simulations 4 --follow
apollo evaluate "callers who argue with a refusal" --world persona=irate --seed 7
apollo evaluate --status                     # read the last run's report

Option	Description
`[guidelines]`	What to evaluate, in plain words (positional; a lone argument that isn’t a directory is taken as the guidelines)
`--simulations <n>`	How many simulated conversations the plan may spend
`--min-turns <n>` · `--max-turns <n>`	Bounds on conversation length
`--seed <n>`	Base seed for the world draws — same seed, same callers
`--world <pins>`	`slot=value` pins applied to every simulation, e.g. `persona=irate`
`--return <shape>`	The report structure you want back, in your words
`--follow`	Wait for the verdict instead of returning the receipt; exits `2` on red
`-m, --message <text>`	A note on the run — shows up on the report
`--status` · `--cancel`	Read a run’s report, or cancel a live run, instead of starting one
`--pull` · `--failures-only`	Fetch the run’s conversations, traces and verdicts into `tmp/<lane>/<id>/`
`--annotate <text>` · `--verdict <pass\|fail\|mixed>`	Append your reading to a settled run
`--id <run-id>`	The run the flags above mean (defaults to the last started)

Testing & Inspection

apollo chat

Chat with an agent, or start an interactive session. Alias: apollo send. Calling apollo chat with no text opens a REPL in an interactive terminal; scripts should pass text explicitly with --no-input.

apollo chat "Where is my order?" --var caller.id=CUST-1
apollo chat "Cancel order #W001" --var caller.id=CUST-1 --trace
apollo chat "Cancel order #W001" --local . --trace     # test local, unpushed files

Option	Description
`--thread <id>`	Append to an existing thread
`--local <directory>`	Send a local program bundle inline
`--var <key=value>`	Agent variable (repeatable; JSON values are decoded)
`--trace`	Include the reply trace

A send without --thread creates and persists a thread — capture data.thread_id from --json output and pass --thread on later turns for multi-turn conversations:

t=$(apollo --json send "Hi — I need to cancel an order" --local . | jq -r '.data.thread_id')
apollo --json send "It's order #W001" --thread "$t" --local . | jq -r '.data.message.text'

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).

apollo thread

Inspect Apollo threads. Messages are sent as the signed-in user; thread list likewise lists the signed-in user’s threads.

apollo thread create
apollo --json thread list [--size 25] [--after <cursor>]
apollo --json thread get <thread-id>
apollo --json thread messages <thread-id>
apollo --json thread trace <thread-id>
apollo --json thread trace <thread-id> --interaction <interaction-id>

trace returns the runtime’s official turn-trace view, whose vocabulary is the program’s capabilities, policies, facts, sources, and records.

Resources

apollo kb

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.

apollo kb create POLICY_DOCS --description "Cancellation and refund policy"
apollo kb add POLICY_DOCS ./policy/*.md    # upload documents (indexing is async)
apollo kb add-url POLICY_DOCS https://example.com/refunds
apollo kb status POLICY_DOCS               # wait for completed
apollo kb check                            # local hub: refs vs the agent's remote hubs
apollo kb list
apollo kb delete POLICY_DOCS --force       # irreversible

Command	Description
`create <name>`	Create an empty hub in the agent’s scope (`--description <text>`)
`list`	List hubs owned by the agent
`add <hub> <files…>`	Upload documents into an existing hub; indexing runs async
`add-url <hub> <urls…>`	Scrape web pages into an existing hub; indexing runs async
`status <name>`	Show a hub’s latest indexing jobs
`check`	Cross-check the program’s `hub:` references against the agent’s remote hubs — run after editing sources, before push
`delete <name> --force`	Permanently delete a hub and all its resources

A hub is inert until a pushed 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 apollo version publish. A reference to a nonexistent hub retrieves nothing, with no validation error.

apollo vault

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.

printf '%s' "$API_KEY" | apollo vault set STRIPE_KEY --description "Stripe live key"
apollo vault list                # visible secrets, masked
apollo vault get STRIPE_KEY     # metadata and masked preview
apollo vault rm STRIPE_KEY --force

Command	Description
`set <name>`	Create or rotate a secret (`--value <value>`, or prefer piped stdin)
`list`	List secrets visible from the current scope (masked)
`get <name>`	Show one secret’s metadata and masked preview
`rm <name> --force`	Delete a secret (`409` while connections still reference it)

apollo mockdb

Manage the per-agent mock database — a test database the agent’s connections can run against.

apollo mockdb provision    # create the mock DB and store keys locally
apollo mockdb wire         # write bundle/src/connections.yaml for mock-db
apollo mockdb describe     # schema, endpoints, and row counts
apollo mockdb seed

Command	Description
`provision`	Create the agent’s mock DB and store runtime/management keys locally
`status`	Show mock DB ownership and local key prefixes
`describe`	Show schema, endpoints, and row counts
`export`	Export schema, base data, and endpoints
`keys`	Show locally stored key prefixes (no secrets)
`wire`	Write `bundle/src/connections.yaml` for mock-db using the stored runtime key (ships with push)
`collections`	Manage mock DB collections
`seed`	Seed data
`endpoint`	Manage named endpoints
`execute`	Execute against the mock DB
`session`	Inspect or reset session overlays
`rotate`	Rotate mock DB keys
`delete`	Permanently delete the mock DB and clear local keys

Shell

apollo shell-init

Print the shell wrapper (zsh/bash) enabling auto-cd after agent use / agent import / agent create. Add to your shell profile:

eval "$(apollo shell-init)"

CLI

Command Reference

Quick Reference

Global Flags

Session & Context

Agents & Checkouts

Authoring

Server-Side Authoring & Evaluation

Testing & Inspection

Resources

Shell

Next Steps

Configuration

Workflows

​Quick Reference

​Global Flags

​Session & Context

​Agents & Checkouts

​Authoring

​Server-Side Authoring & Evaluation

​Testing & Inspection

​Resources

​Shell

​Next Steps

Configuration

Workflows

Quick Reference

Global Flags

Session & Context

Agents & Checkouts

Authoring

Server-Side Authoring & Evaluation

Testing & Inspection

Resources

Shell

Next Steps