Skip to main content
The Apollo CLI (@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

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.
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.
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.
Ask the grounded authoring advisor a question with apollo advise, run a complete build turn with apollo build (gated: green pushes a new revision, red refuses), and grade the agent with apollo regress and apollo evaluate, run server-side over your checkout.
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.)
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.
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.
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.
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.
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

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