@aui.io/apollo) is the operator console for Apollo agents. One install gives you two surfaces: a scriptable command-line interface (apollo <command>) and a full-screen terminal UI (bare apollo) for the author/test loop. It enables a local-first development workflow: import an agent as a typed YAML program, edit it in your IDE with schema support, validate, test against the live runtime, and push changes back as new revisions.
The CLI is designed to be driven by coding agents as much as by humans. Every command is fully non-interactive with a
--json output mode, and importing an agent installs authoring skill packs for Cursor and Claude Code — so tools like Cursor, Claude Code, and the Agent Builder can author, run, and iterate on an agent end-to-end.Quick Start
Mental Model
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.
Key Features
Local-First Development
Local-First Development
Import an agent as a typed YAML program under
bundle/src/. Edit it in
VSCode, Cursor, or any editor — the checkout ships JSON Schemas for every
file. Version control is git: diffs against policies/global.yaml are real
diffs, and rollback is git revert.Validation and Diffing
Validation and Diffing
apollo validate checks the local program deterministically before any
push. apollo diff shows what changed line by line — your edits, your
checkout against any revision, or two revisions — and apollo push --dry-run
previews exactly what would ship. apollo show prints a file as any
revision has it, apollo restore puts files back, and apollo merge-from
brings another version’s changes in.Runtime Testing
Runtime Testing
Talk to your agent against the real Apollo-1 runtime with
apollo chat —
including your local, unpushed edits via --local . — and see what it did
with every reply: the intent, the capabilities it ran, and whether its
checks passed. Speak as one of the spec’s test callers with --caller,
script whole conversations with expectations using --script, and read the
decision trace with --trace. Inspect full conversations with
apollo thread messages and apollo thread trace, or open them in the
Playground with apollo open.Version Management
Version Management
Each push adds a revision to a version (
v3.1, v3.2, …), and exactly one
revision is live. apollo version live <tag> makes an exact revision live —
an older one included, which is the rollback — and pushing never moves it.
apollo version lock protects a version from further pushes, and
log, label, notes, and archive manage the rest of the lifecycle.
(The CLI’s own help calls a version a branch and a revision a commit:
apollo branch is the same command.)Knowledge, Mock DB & Secrets
Knowledge, Mock DB & Secrets
Create knowledge hubs and upload documents with
apollo kb, spin up a
per-agent test database with apollo mockdb, and store credentials
referenced from connections.yaml with apollo vault.Evaluation
Evaluation
Replay the scripted suite through the simulator with
apollo regress, and
go looking for what no script covers with apollo evaluate — improvising
simulated callers planned from your guidelines and graded by a judge. Both
report coverage per capability card in bundle/build/spec.yaml.Staying Current
Staying Current
The CLI tells you when a newer release is out, and when a checkout’s skills
or runtime fall behind — with the command that fixes it.
apollo release-notes says what changed and what to do next, and
apollo skills update refreshes a checkout’s skills, AGENTS.md, and
schemas without touching the program. When something breaks that isn’t your
program, apollo report files it with its evidence.Beta Runtime
Beta Runtime
Build a new agent on Beta, the newest runtime, with
apollo agent create --beta, or try an existing version there with
apollo version try-beta: it gets a new version on Beta, rebuilt and
evaluated, and your own version doesn’t change. See
Beta runtime.Interactive TUI
Interactive TUI
Bare
apollo on a TTY launches the full-screen terminal UI: an Author mode
(validate, diff, push, pull, versions, resources) and a Talk mode
(converse with the running agent), with an action palette (Ctrl+K) that
shows the CLI equivalent of every operation.The TUI in One Minute
Bareapollo on a TTY launches the TUI (apollo tui and --tui force it; any subcommand, --json, --no-input, or a non-TTY always runs the CLI). It has two primary modes — Author (the program cockpit) and Talk (converse with the running agent):
In Author, type a single letter and press
Enter to run a quick action (v validate · d diff · p push · l pull · r versions · m resources · o open in IDE). Any other text is a copilot turn: the TUI hands it to Claude Code when it’s on your PATH, and you review what it changed with d. In Talk, the composer sends everything to the agent verbatim — Ctrl+T shows the trace and Ctrl+N starts a new thread.
The TUI runs on Bun. Without Bun installed,
apollo prints install guidance and the CLI remains fully usable. Ctrl+1 / Ctrl+2 need a terminal with the kitty keyboard protocol; Tab works everywhere, and apollo tui --keys shows what your terminal sends for each key.Get Started
Installation
Install the CLI and authenticate with your account.
Hello world
Build your first agent end to end, from empty folder to live version.
Command Reference
Full reference for every CLI command.
Configuration
Checkout structure, config files, and environment variables.
Workflows
Common development workflows and best practices.
Beta runtime
Build and try agents on the newest runtime.