@aui.io/apollo

Apollo operator console — CLI + interactive TUI for authoring and operating Apollo agents.

One npm install gives you both surfaces: a scriptable Commander CLI (apollo <command>) and a full-screen terminal UI (bare apollo) for the author/test loop. This is the only published Apollo console package — the apollo-core, apollo-cli, and apollo-tui workspaces are bundled inside it.

Install

npm install -g @aui.io/apollo
apollo --version

| Requirement | Needed for | |---|---| | Node.js ≥ 20 | everything | | Bun (optional) | the interactive TUI only |

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.

Upgrade later with:

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

CLI or TUI?

• Bare apollo on a TTY launches the TUI (the main path). apollo tui / --tui force it.
• Any subcommand, --json, --no-input, or a non-TTY always runs the CLI.
• Escape hatches: APOLLO_TUI=0 keeps a bare TTY on the CLI welcome; apollo cli <cmd…> always routes to Commander.

Quick start

apollo login                          # browser flow
apollo agent import <agent-id>        # or: apollo agent create <name>
cd <the printed checkout directory>   # defaults to ~/apollo/<profile>/<env>/<name>-<id>

# edit bundle/src/… (program.yaml, vocabulary.yaml, capabilities/, policies/, …)

apollo validate                       # deterministic program validation
apollo push -m "describe the change"  # upload as a new version revision
apollo chat "hello" --trace           # talk to it, with the decision trace

Context is positional: the nearest .apollorc walking up from your current directory selects the agent you are working on. apollo status always tells you where you stand.

Mental model

| Layer | What it is | Commands | |---|---|---| | Profile | Named credential slot (e.g. default, work) | profile * | | Checkout | Local directory holding one agent (.apollorc + bundle/src/) | agent use / import / create | | Organization | Identity / billing org (on the access token) | org * | | Project | Container for agents | project * | | Agent | The program you edit and test | agent * | | Version | Tagged remote snapshot of the program | version *, pull / push |

Command overview

status     [--check]                         # active context (+ service connectivity)
doctor     [--offline]                       # diagnose setup; exit 2 on problems
upgrade    [version] [--check] [--force]
login | logout
profile    current | list | use <name>
org        list | use <id>
project    list | use <id> | create <name>
agent      list | use <target> | path | create <name> [--dir] | import <id> | unlink
schema     pull [--dir]
validate   [directory]
diff       [--remote]
pull       [--tag] [--dir] [--force]
push       -m|--message <text> [--dry-run]
version    list | get <tag> | use <tag> | create [--from|--template|--label|--notes]
           | publish <tag> | archive <tag>
scenarios  generate | pull | push | scores
chat       [text…] [--thread] [--user] [--local] [--var] [--trace]
thread     create | list | get | messages | trace
mockdb     provision | status | describe | export | keys | wire | delete --force
           | collections … | seed | endpoint … | execute | session … | rotate …
vault      set <NAME> | list | get <NAME> | rm <NAME> --force
kb         list | status <name> | check | create <name> | add <hub> <files…>
           | add-url <hub> <urls…> | export <hub> | export --all | delete <name> --force

Run apollo <command> --help for the live flag list on your installed version.

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

The TUI in one minute

Two primary modes — Author (program cockpit: validate, diff, push, pull, versions, resources, scenarios) and Talk (converse with the running agent).

| Input | Action | |---|---| | Ctrl+1 / Ctrl+2 (or Tab) | Author / Talk | | Ctrl+K | Action palette — every operation, with CLI equivalents | | Ctrl+G | Context switcher — profile / agent / project / org | | Ctrl+J | Activity drawer — operations, retry, output, live API-request tail | | Esc | Close overlay / cancel |

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.

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

--verbose streams one redacted line per API request (auth/token/key/secret values never appear) to stderr; the TUI shows the same stream live in its activity drawer.

Files and environment variables

~/.apollo/
  config.json          # profile, environment, 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

APOLLO_PROFILE, APOLLO_TOKEN (CI auth), APOLLO_ORG_ID, APOLLO_PROJECT_ID, APOLLO_TIMEOUT_MS, and per-service APOLLO_*_URL overrides are honored everywhere; see the User Guide for the full table.

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

Full docs live in the repository:

• User Guide — install, mental model, every command, TUI, troubleshooting
• Configuration — every file and variable the console reads or writes
• Architecture — services, auth, request handling
• Keybindings — TUI input reference