Apollo CLI — @aui.io/apollo

Author, test, and operate Apollo agents from your terminal.

The Apollo CLI is the operator console for agents built on Apollo-1, AUI's neuro-symbolic foundation model. One install gives you two surfaces:

• a scriptable command-line interface — apollo <command>, with a --json mode for scripts and coding agents;
• a full-screen terminal UI (bare apollo) for the author → validate → test → push loop.

An agent's program is a typed YAML codebase you keep in a local checkout, edit in your IDE with schema support, validate, test against the live runtime, and push back as new versions. The same agents are available in the Playground.

📘 Full documentation: docs.aui.io/cli

Requirements

No npm login is required to install. The TUI is built on OpenTUI and runs on Bun: when launched from Node, apollo transparently re-executes the TUI under bun from your PATH; without Bun it prints install guidance and the CLI remains fully usable.

Install

npm install -g @aui.io/apollo
apollo --version
apollo doctor          # checks Node/Bun, the install, your terminal and connectivity

Upgrade later with:

apollo upgrade            # install the latest version from npm
apollo upgrade --check    # show the available version only

Quick start

# 1. Sign in — opens the browser flow in the Playground
apollo login

# 2. Create a new agent, or import one you already have
apollo agent create "Returns Assistant"      # or: apollo agent import <agent-id>
cd <the printed checkout directory>          # defaults to ~/apollo/<profile>/<env>/<name>-<id>

# 3. Edit the program under bundle/src/
#    program.yaml · vocabulary.yaml · situations.yaml · sources.yaml ·
#    derivations.yaml · connections.yaml · capabilities/ · policies/

# 4. Validate — deterministic, with every finding located in a file
apollo validate

# 5. Talk to it against the live runtime WITHOUT deploying, and read the trace
apollo chat "I want to return an order" --local . --trace

# 6. Push the change, then make that SAVE the one customers get, when it is ready
apollo push -m "Describe the change"
apollo branch list
apollo branch live <tag>          # `v3.7` ships exactly that save; `v3` ships its newest

apollo status always tells you where you stand — which profile, organization, project, agent and version are active, and which runtime the checkout is pinned to.

How the CLI thinks

Context is positional: the nearest .apollorc walking up from your current directory selects the agent you are working on, so cd into a checkout and every command applies to that agent.

Commands

status      [--check]                          active context (+ service connectivity)
doctor      [--offline]                        diagnose the setup; exit 2 on problems
upgrade     [version] [--check] [--force]      upgrade from npm
login       [--sso | --email <e> [--otp <c>] | --token <jwt>]
logout
profile     current | list | use <name>
org         list | use <id>
project     list | use <id> | create <name>
agent       list | create <name> [--dir <path>] [--template <id>]
            | import [agent-id] [--tag <tag>] [--dir <path>] [--skills <targets>] [--force]
            | use <target> | path | unlink
runtime     list | show | use [version]
validate    [directory]                        validate the local program (exit 2 on errors)
diff        [--remote]                         compare local files with the last baseline
pull        [--tag] [--dir] [--force] [--skills cursor,claude,opencode] [--no-skills] [--no-schemas]
push        -m <message> [--dry-run]           validate and push local changes as a new version
version     list | get <tag> | use <tag> | create [--from <tag> | --template <id>] [--label] [--notes]
            | publish <tag> | archive <tag>
chat        [text…] [--thread <id>] [--local <dir>] [--var k=v] [--trace]
thread      create | list | get <id> | messages <id> | trace <id>
regress     [--scenarios <ids>] [--explain] [--follow] [--status] [--cancel] [--pull]
evaluate    [directory] [guidelines] [--simulations <n>] [--min-turns] [--max-turns] [--seed] [--follow]
advise      <question> [--fresh] [--model] [--max-usd]
build       <instruction> [-m] [--version-tag] [--publish] [--model] [--max-usd]
mockdb      provision [--wire] | status | describe | export | keys | wire | clone --from <id> | reset [--scope data|all] --force | delete --force
            | collections create | update | list | truncate | delete · seed (--rows | --file) [--mode] · rows list | patch | delete
            | endpoint create | list | get | update | delete · execute --slug <s> [--session] [--body] · session get | reset · rotate mgmt | runtime
            | identities get | set · guide
vault       set <NAME> | list | get <NAME> | rm <NAME> --force
kb          list | status <name> | create <name> | add <hub> <files…> | add-url <hub> <urls…>
            | check | export [name] | delete <name> --force | connections | resync <hub>
report      <title> [--kind] [--confidence] [--summary] [--tried …] [--command] [--dry-run] [--no-session]
shell-init                                     print the shell hook (see below)

Run apollo <command> --help for the live flag list on your installed version — the command surface is verified against the CLI itself, so --help is always the authority.

Global flags (before the subcommand)

--json (stable envelope for scripts) · --quiet · --verbose (extra diagnostics, including one live line per API request) · --no-input · --yes · --profile <name> · --project <id> · --org <id> · --runtime-version <version> · --timeout <ms>

JSON mode always emits {"success":true,"data":…} or {"success":false,"error":{"code","message","suggestion"}}. Exit codes: 0 success · 1 runtime/API failure · 2 validation failure · 3 auth/config failure.

Authentication

apollo login                               # browser sign-in via the Playground (default)
apollo login --email [email protected]       # email one-time code, then prompts for it
apollo login --token "$ACCESS_TOKEN"       # store a pre-issued access token
apollo whoami                              # who this session acts as, checked with identity
apollo logout

Credentials are stored per profile in ~/.apollo/credentials.json (mode 0600). Use profiles to keep several accounts side by side (apollo profile use work, or --profile work on a single command).

CI and automation: set APOLLO_TOKEN in the environment and run with --json --no-input; nothing prompts, and every result is a machine-readable envelope. An APOLLO_TOKEN run never touches the saved login: an expired token fails with AUTH_ERROR instead of refreshing into whoever is stored on disk.

Working with coding agents

The CLI is designed to be driven by coding agents as much as by humans. apollo agent import / apollo pull install the authoring skill packs and an AGENTS.md into the checkout (--skills cursor,claude,opencode selects the targets; --no-skills skips them), so tools such as Cursor, Claude Code and OpenCode can author, validate, test and push an agent end to end. apollo advise "<question>" asks the server-side authoring advisor about your checkout, and apollo build "<instruction>" runs one build turn over the pushed agent.

The TUI in one minute

Bare apollo on a TTY launches the terminal UI (apollo tui / --tui force it; any subcommand, --json, --no-input or a non-TTY always runs the CLI; APOLLO_TUI=0 keeps a bare TTY on the CLI). Two primary modes — Author (validate, diff, push, pull, versions, resources, scenarios) and Talk (converse with the running agent).

In Author, single letters run quick actions (v validate · d diff · p push · l pull · r versions · m resources · s scenarios · o open in IDE), and free text is a copilot instruction to the author backend. In Talk, the composer sends everything to the agent verbatim.

Testing an agent

Data your agent reads

• Mock database — apollo mockdb … provisions a per-agent, seedable mock database with declared endpoints, so you can build and test against realistic data before a real backend exists. apollo mockdb guide writes the complete how-to into your checkout.
• Knowledge hubs — apollo kb … creates hubs, uploads documents or scrapes URLs into them, and checks the program's hub: references before you push. For a hub a connector (Notion, Confluence, Google Drive, …) syncs, kb connections shows how its syncs went and kb resync <hub> runs one now.
• Secrets — apollo vault set <NAME> stores connection credentials by name; programs reference them (token_env, ${NAME}) in bundle/src/connections.yaml and never carry a value.

Diagnostics

apollo doctor             # diagnose the setup end to end; exit 2 on problems
apollo status --check     # context + per-service reachability/auth
apollo --verbose <cmd>    # stream each API call live to stderr

apollo doctor checks 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. Share its output when reporting issues.

apollo report "<the fault>" files a fault that is not your program's — the engine contradicting its reference, the CLI breaking its contract, a platform call that keeps failing — with your login. It attaches the checkout, the engine build, the CLI version and, under a coding agent, the session's commands, scrubbed of secrets (never what you typed); --dry-run shows exactly what would be sent. The CLI also files its own crashes and server errors in the background. APOLLO_REPORTS=0 turns all of it off.

--verbose streams one redacted line per API request (auth/token/key/secret values never appear) to stderr — a request that got no answer says why (a refused connection, a timeout, an untrusted certificate); the TUI shows the same stream live in its activity drawer.

Behind a corporate proxy

Set the proxy the way you would for curl. Every request the CLI and the TUI make, and the update check, then goes through it:

export HTTPS_PROXY=http://proxy.example.com:8080       # user:password@ before the host if it needs a login
export NO_PROXY=localhost,127.0.0.1                     # hosts that skip it; .example.com covers subdomains
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem    # only if the proxy inspects HTTPS
apollo doctor                                           # shows the proxy in use and what each service answers

The lowercase forms (https_proxy, http_proxy, no_proxy) work too and win when both are set. Only HTTP(S) proxies are supported — a bare host:port reads as http://host:port, and any other scheme (socks5://, …) is refused by name rather than silently gone around.

Files and environment variables

~/.apollo/
  config.json          # profile, default projects
  credentials.json     # tokens (mode 0600 — the only secret-bearing file)
  checkouts.json       # known-checkouts registry
  baselines/…          # sync hashes for diff/push

<checkout>/.apollorc   # org / project / agent / version_tag binding
<checkout>/bundle/src/ # the editable program source

The full table, including per-service URL overrides, is in the configuration reference.

Shell integration

The postinstall step offers a small shell hook (or add it yourself with eval "$(apollo shell-init)"): it lets apollo agent use / import / create drop your shell directly into the checkout directory.

Documentation and support

• CLI overview · Installation · Commands · Configuration · Workflows
• Apollo-1 documentation — the program model, the Messaging API, the Agent Builder API and the SDK
• The Playground — the same agents in the browser
• Questions or issues: run apollo doctor, then contact AUI with its output

Terms of use

Use of this package, and of the Apollo APIs it calls, is governed by the AUI API and Developer Package Terms of Service. By installing or using @aui.io/apollo you agree to those terms.

© AUI. All rights reserved.