Import and Edit an Existing Agent
The most common workflow: pull an agent from the cloud, edit it locally, validate, test, and push back.Importing installs authoring skill packs for Cursor and Claude Code (add
opencode via --skills), pulls the authoring JSON Schemas into schemas/, and drops the runtime’s AGENTS.md guide (with a CLAUDE.md copy) into the checkout — open the agent folder as your coding-tool project root and no additional setup is required.Create a New Agent from Scratch
apollo agent create provisions the agent server-side, creates a local checkout, and makes it active.
Test Against the Runtime
Talk to your agent against the real Apollo-1 runtime. Pass--local . to send your working tree inline — replies reflect your latest edits, no push required. Every reply says what the agent did — the intent, the capabilities it ran, and whether its checks passed — so a single turn is often all you need to read.
Script a conversation with expectations
Put the turns in a file and say what each one must do.apollo chat --script runs them on one thread and exits 2 when an expectation isn’t met — a quick, repeatable check you can run against the working tree before any push:
turns.yaml
apollo chat for every expectation key. For a quick conversation without expectations, pipe one message per line: cat script.txt | apollo chat -.
Validate, Regress, and Push
The authoring arc is pull → edit → validate → regress → push:validate checks structure; only a run proves conduct — that gates refuse, read-backs execute, and writes land. Every regression is graded by a deterministic judge; add --explain to have the LLM judge explain every bad answer. A bundle with no bundle/build/scenarios.yaml has never been graded.
Make a Version Live
Pushing mints a revision but never changes what callers get. To ship, make a revision live (the CLI’s own help and output call a version a branch and a revision a commit —apollo branch is the same command as apollo version):
live asks before it moves anyone. Without one — CI, a coding agent — it goes ahead with a warning, so pass --yes deliberately, or set APOLLO_REQUIRE_CONFIRM=1 to make it refuse without one. To stop further pushes landing on a version you rely on, apollo version lock v3 — callers are unaffected. apollo version publish <tag> is the older one-step that locks a version and makes its newest revision live.
Work Across Versions
Every revision is a snapshot you can read, compare with, and take files from — without touching the checkout’s binding:apollo merge-from --abort undoes the merge — until your next push or pull.
When a push is refused because your version moved. If someone — a teammate, the Playground, or a build turn — pushed to your version after your checkout started, the push is refused (VERSION_MOVED), naming the newer revision and who pushed it. Bring it in and push again, or push yours as a new version:
apollo merge-from v3.8 --resolved, then push.
Evaluate the Agent
Two lanes run the agent for real, both server-side, both frozen at start so you can keep editing:regress answers “does what worked still work” and runs on the tree in front of you; evaluate goes looking for what no script covers, and a pass counts for your version once you’ve pushed it. Both report coverage per capability card in bundle/build/spec.yaml.
Server-Side Authoring
Two commands move authoring itself to the server, grounded in your checkout:--publish to build to make the pushed revision live in the same turn.
Ground the Agent in Knowledge
Knowledge hubs are the corpora thathub: sources search at runtime. Every step below is load-bearing — the last two are the ones people skip:
apollo chat --local . from inside the checkout. For a hub a connector (Notion, Confluence, Google Drive, …) keeps in sync, apollo kb connections shows how its syncs went and apollo kb resync <hub> runs one now.
After You Upgrade
The CLI and the runtime both ship often. When either changes:apollo runtime use <version>, a checkpoint apollo push, then apollo build "Upgrade this agent runtime version". See Staying up to date.
Report a Fault
When something fails that isn’t your program — the engine contradicts its reference, the CLI breaks its contract, or a platform call keeps failing — file it with its evidence:--dry-run prints exactly what would be sent; drop it to file. A fault in your own program is never a report — fix it. See apollo report for what the CLI attaches.
CI/CD Integration
Authenticate with a token, force non-interactive mode, and parse the JSON envelope.0 success, 1 runtime/API failure, 2 validation failure, 3 auth/config failure — gate pipeline steps on them.
Driving the CLI with a Coding Agent
The CLI is built to be driven by coding agents (Cursor, Claude Code, the Agent Builder). Every command is non-interactive with--json, and importing an agent installs skill packs that teach the workflow.
- Author → run → read the trace → revise. Have the agent edit
bundle/src/, thenapollo --json chat … --local . --trace, read the trace, and iterate until behavior holds.apollo chat --scriptturns a behavior you’ve agreed on into a check it can rerun. - Put global flags before the command —
apollo --json --no-input <command> …— and parse the envelope (dataon success,error.code/message/suggestionon failure). - Keep the checkout fresh.
apollo pullrefreshes the program, schemas, skill packs, andAGENTS.mdthe runtime serves;apollo skills updaterefreshes all but the program. The checkout’sAGENTS.mdtells the coding agent which update requests to run itself and which to bring to you. - Report what isn’t the program’s. The checkout’s
AGENTS.mdalso teaches the coding agent to file engine, CLI, and platform faults withapollo report.
Next Steps
Command Reference
Full reference for all CLI commands.
Configuration
Checkout structure, config files, and environment variables.