> ## Documentation Index > Fetch the complete documentation index at: https://docs.aui.io/llms.txt > Use this file to discover all available pages before exploring further. # Command Reference > Complete reference for every Apollo CLI command. 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 --help` for the live flag list on your installed version. ## Quick Reference | Command | Description | | - | - | | [`apollo login`](#apollo-login) | Authenticate with Apollo | | [`apollo logout`](#apollo-logout) | Remove the active session | | [`apollo status`](#apollo-status) | Show the active context | | [`apollo doctor`](#apollo-doctor) | Diagnose the setup end to end | | [`apollo upgrade`](#apollo-upgrade) | Upgrade the CLI from npm | | [`apollo profile`](#apollo-profile) | Show or select the active credential profile | | [`apollo org`](#apollo-org) | Select an organization | | [`apollo project`](#apollo-project) | Manage projects | | [`apollo agent`](#apollo-agent) | Manage agents and checkouts | | [`apollo runtime`](#apollo-runtime) | Select the runtime (engine build) a checkout runs against | | **Authoring** | | | [`apollo validate`](#apollo-validate) | Validate the local agent program | | [`apollo diff`](#apollo-diff) | Compare local files with the last baseline | | [`apollo pull`](#apollo-pull) | Pull the selected agent version, schemas, and skills | | [`apollo push`](#apollo-push) | Validate and push local changes as a new version | | [`apollo version`](#apollo-version) | Manage agent versions | | **Server-side authoring & evaluation** | | | [`apollo advise`](#apollo-advise) | Ask the authoring advisor a grounded question | | [`apollo build`](#apollo-build) | Run one gated build turn server-side | | [`apollo regress`](#apollo-regress) | Replay the scripted suite through the simulator | | [`apollo evaluate`](#apollo-evaluate) | Explore the agent with improvising simulated callers | | **Testing & inspection** | | | [`apollo chat`](#apollo-chat) | Chat with an agent (alias: `apollo send`) | | [`apollo thread`](#apollo-thread) | Inspect threads, messages, and traces | | **Resources** | | | [`apollo kb`](#apollo-kb) | The agent's knowledge hubs | | [`apollo vault`](#apollo-vault) | Manage vault secrets used by `connections.yaml` | | [`apollo mockdb`](#apollo-mockdb) | Manage the per-agent mock database | | **Shell** | | | [`apollo shell-init`](#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 ` | Override the active profile for this command | | `--project ` | Override the active project | | `--org ` | Override the active organization | | `--runtime-version ` | Override the checkout's pinned runtime (env: `APOLLO_RUNTIME_VERSION`) | | `--timeout ` | 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. ```bash theme={"dark"} apollo login # browser flow apollo login --email user@example.com # email OTP (re-run with --otp ) apollo login --token "$ACCESS_TOKEN" # store a pre-issued JWT ``` | Option | Description | | - | - | | `--sso` | Use the browser login flow | | `--email ` | Send an email OTP | | `--otp ` | OTP code (with `--email`) | | `--token ` | Store an existing access token | | `--url ` | Override the Playground login URL | Invalidate the remote session (best-effort) and remove the local credential. ```bash theme={"dark"} apollo logout ``` Show the active Apollo context: profile, checkout, authentication, organization, project, agent, version, runtime, and token expiry. ```bash theme={"dark"} apollo status apollo status --check # also check service connectivity and authorization ``` 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. ```bash theme={"dark"} apollo doctor apollo doctor --offline # skip connectivity checks ``` Upgrade Apollo from npm (`@aui.io/apollo`). ```bash theme={"dark"} 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 | Show or select the active credential profile. Profiles keep separate credentials for different users or contexts. ```bash theme={"dark"} apollo profile current apollo profile list apollo profile use work ``` `--profile ` 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. ```bash theme={"dark"} apollo --json org list [--name ] 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. Manage projects — the containers agents live in. `use` inside a checkout updates that checkout's `.apollorc`; outside any checkout it sets the account default. ```bash theme={"dark"} apollo --json project list [--name ] apollo project use [project-id] apollo project create "Display name" ``` *** ## Agents & Checkouts Manage agents and their local checkouts. A **checkout** is a directory holding one agent, pinned by its own `.apollorc`. With [shell integration](/cli/installation#post-login-setup), `use`, `import`, and `create` also `cd` into the checkout. ```bash theme={"dark"} apollo --json agent list [--name ] # 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 ` | Checkout directory (defaults to a managed directory under `~/apollo/`) | | `--template ` | Template agent to go live on immediately (default: empty draft) | **`agent import`** options: | Option | Description | | - | - | | `--name ` | Filter the interactive picker by name | | `--tag ` | Version tag (defaults to the live version) | | `--dir ` | Checkout directory (defaults to a managed directory under `~/apollo/`) | | `--skills ` | 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. Select the runtime (engine build) this checkout runs against. ```bash theme={"dark"} 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 Validate the local agent program — the verdict plus the orphan and era censuses. Exits `2` on findings. ```bash theme={"dark"} 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 | Compare local files with the last baseline (the last successful import, pull, or push). ```bash theme={"dark"} apollo diff apollo diff --remote # compare with the selected remote version instead ``` 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. ```bash theme={"dark"} apollo pull apollo pull --tag v2.3 apollo pull --force # discard local bundle changes and match remote ``` | Option | Description | | - | - | | `--tag ` | Version tag | | `--dir ` | Destination directory | | `--force` | Discard local bundle changes and match remote | | `--skills ` | 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 | 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. ```bash theme={"dark"} apollo push --dry-run # validate and show the diff without pushing apollo push -m "Tighten refund eligibility" ``` | Option | Description | | - | - | | `-m, --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 `. Manage agent versions. ```bash theme={"dark"} 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 ` (clone an existing version) · `--template ` (create from a template) · `--label *** ## Server-Side Authoring & Evaluation Ask the server-side authoring advisor — ships this checkout's tree and waits for grounded advice. ```bash theme={"dark"} 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 ` | Advisor model override | | `--max-usd ` | Per-question spend cap (server default applies otherwise) | 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. ```bash theme={"dark"} apollo build "Add a fee waiver for premium members" -m "Fee waiver" ``` | Option | Description | | - | - | | `--version-tag ` | The base version to build from (defaults to the pin) | | `-m, --message ` | The push message | | `--model ` | Build model override | | `--max-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 | 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. ```bash theme={"dark"} 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 ` | 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 ` | A note on the run — shows up on the report | | `--version-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///` | | `--annotate ` · `--verdict ` | Append your reading to a settled run | | `--id ` | The run the flags above mean (defaults to the last started) | 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. ```bash theme={"dark"} 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 ` | How many simulated conversations the plan may spend | | `--min-turns ` · `--max-turns ` | Bounds on conversation length | | `--seed ` | Base seed for the world draws — same seed, same callers | | `--world ` | `slot=value` pins applied to every simulation, e.g. `persona=irate` | | `--return ` | 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 ` | 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///` | | `--annotate ` · `--verdict ` | Append your reading to a settled run | | `--id ` | The run the flags above mean (defaults to the last started) | *** ## Testing & Inspection 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`. ```bash theme={"dark"} 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 ` | Append to an existing thread | | `--local ` | Send a local program bundle inline | | `--var ` | 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: ```bash theme={"dark"} 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). Inspect Apollo threads. Messages are sent as the signed-in user; `thread list` likewise lists the signed-in user's threads. ```bash theme={"dark"} apollo thread create apollo --json thread list [--size 25] [--after ] apollo --json thread get apollo --json thread messages apollo --json thread trace apollo --json thread trace --interaction ``` `trace` returns the runtime's official turn-trace view, whose vocabulary is the program's capabilities, policies, facts, sources, and records. *** ## 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: `), and the match is **by name**. Every `kb` command needs an agent checkout. ```bash theme={"dark"} 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 ` | Create an empty hub in the agent's scope (`--description `) | | `list` | List hubs owned by the agent | | `add ` | Upload documents into an existing hub; indexing runs async | | `add-url ` | Scrape web pages into an existing hub; indexing runs async | | `status ` | 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 --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. 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. ```bash theme={"dark"} 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 ` | Create or rotate a secret (`--value `, or prefer piped stdin) | | `list` | List secrets visible from the current scope (masked) | | `get ` | Show one secret's metadata and masked preview | | `rm --force` | Delete a secret (`409` while connections still reference it) | Manage the per-agent mock database — a test database the agent's connections can run against. ```bash theme={"dark"} 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 Print the shell wrapper (zsh/bash) enabling auto-cd after `agent use` / `agent import` / `agent create`. Add to your shell profile: ```bash theme={"dark"} eval "$(apollo shell-init)" ``` ## Next Steps Checkout structure, config files, and environment variables. Common development workflows and patterns. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.