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

# Apollo CLI

> Author, test, and operate Apollo agents from your terminal — a scriptable CLI and a full-screen TUI in one install.

```bash theme={"dark"}
npm install -g @aui.io/apollo
```

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

<Info>
  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.
</Info>

## Quick Start

```bash theme={"dark"}
# 1. Authenticate (opens the browser)
apollo login

# 2. Create a new agent — or import an existing one with: apollo agent import
apollo agent create "Returns Assistant"
cd <the printed checkout directory>

# 3. Edit the program under bundle/src/ (program.yaml, capabilities/, policies/, …)

# 4. Validate your changes
apollo validate

# 5. Test against the live runtime without deploying
apollo chat "I want to return an order" --local . --trace

# 6. Push changes to the cloud as a new version
apollo push -m "Describe the change"
```

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

| 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` |

## Key Features

<AccordionGroup>
  <Accordion title="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`.
  </Accordion>

  <Accordion title="Validation and Diffing">
    `apollo validate` checks the local program deterministically before any
    push. `apollo diff` compares your working tree with the last baseline (or
    the selected remote version with `--remote`), and `apollo push --dry-run`
    previews exactly what would ship.
  </Accordion>

  <Accordion title="Runtime Testing">
    Talk to your agent against the real Apollo-1 runtime with `apollo chat` —
    including your local, unpushed edits via `--local .` — and read the
    decision trace with `--trace`. Inspect full conversations with
    `apollo thread messages` and `apollo thread trace`.
  </Accordion>

  <Accordion title="Server-Side Authoring">
    Ask the grounded authoring advisor a question with `apollo advise`, run a
    complete build turn with `apollo build` (gated: green pushes a new version,
    red refuses), and grade the agent with `apollo regress` and
    `apollo evaluate`, run server-side over your checkout.
  </Accordion>

  <Accordion title="Version Management">
    Manage the full lifecycle — draft, publish, archive — with `apollo version`.
    Publishing is also the rollback operation: re-publishing an older version
    makes it live again.
  </Accordion>

  <Accordion title="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`.
  </Accordion>

  <Accordion title="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
    measure against the case bank in `bundle/build/cases.yaml`.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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):

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

<Note>
  The TUI runs on [Bun](https://bun.sh). Without Bun installed, `apollo` prints install guidance and the CLI remains fully usable.
</Note>

## Get Started

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/cli/installation">
    Install the CLI and authenticate with your account.
  </Card>

  <Card title="Hello world" icon="rocket" href="/hello-world">
    Build your first agent end to end, from empty folder to published version.
  </Card>

  <Card title="Command Reference" icon="terminal" href="/cli/commands">
    Full reference for every CLI command.
  </Card>

  <Card title="Configuration" icon="gear" href="/cli/configuration">
    Checkout structure, config files, and environment variables.
  </Card>

  <Card title="Workflows" icon="route" href="/cli/workflows">
    Common development workflows and best practices.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.