Skip to main content

Checkout Structure

A checkout is a local directory holding one agent. After apollo agent import or apollo agent create, it looks like this:
Open the agent folder as your coding-tool project root so the skill packs are discovered. The skill packs, schemas, and AGENTS.md come from the runtime the checkout’s version runs on: apollo pull refreshes them with the program, and apollo skills update refreshes them alone (skip them on pull with --no-skills / --no-schemas).

The .apollorc Binding

.apollorc
Context is positional: the nearest .apollorc walking up from your current directory selects the agent. Commands run inside a checkout use its binding for organization, project, agent, version, and runtime.
Don’t edit .apollorc manually — apollo agent use / import, apollo project use, apollo version use, apollo pull --tag, and apollo runtime use maintain it, and apollo push updates the tag on every push.

User Configuration (~/.apollo/)

The CLI also keeps a few small caches here, such as recent runtime availability and the TUI’s copilot sessions.
Never read, print, copy, or commit ~/.apollo/credentials.json or ~/.apollo/mockdb/ — they hold your access and refresh tokens and your mock DB keys. All other commands need no additional secrets.

Environment Variables

Environment variables override file-based configuration — useful for CI/CD pipelines.

Output & Exit Codes

With the global --json flag, every command emits exactly one envelope on stdout (the one exception, apollo chat --events, first streams one JSON line per frame, then the envelope):
When a gate says no — validate finds errors, a --follow run ends red, push refuses an invalid program — error.detail carries the same object a success would put in data. Either envelope can also carry update, skills_update, and runtime_update fields when something is out of date; they’re additive, so a consumer that never looks for them sees the envelope it always did. --verbose streams one redacted line per API request to stderr (auth/token/key/secret values never appear); the TUI shows the same stream live in its activity drawer.

Next Steps

Command Reference

Full reference for all CLI commands.

Workflows

Common development workflows and patterns.