Skip to main content

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.
Test multi-turn threads, not single messages. Most defects live on turn two and later — a read-back that never executes, a gate that promises and then refuses. Make scripted conversations 5–7 turns. Separate threads are independent: run them as parallel processes (around 20 concurrent threads is a sane cap); turns on one thread are strictly sequential.

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
See 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):
At a terminal, 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:
To bring another version’s changes into yours, merge them in — a three-way merge over the revision both came from:
Changed your mind before that push? 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:
With disputed regions, decide them in the files, run 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:
Add --publish to build to make the pushed revision live in the same turn.

Ground the Agent in Knowledge

Knowledge hubs are the corpora that hub: sources search at runtime. Every step below is load-bearing — the last two are the ones people skip:
To test retrieval before pushing, send the working tree inline with 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:
Commands also tell you when something falls behind — a newer CLI, skills older than the runtime they run on, or a newer runtime for the checkout — and name the command to run. Moving a checkout to a newer runtime is your call: 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.
Exit codes are stable: 0 success, 1 runtime/API failure, 2 validation failure, 3 auth/config failure — gate pipeline steps on them.
Pass --yes to commands that confirm (version live, publish, archive). Without a terminal they proceed today with a warning; set APOLLO_REQUIRE_CONFIRM=1 to make them refuse unless --yes is given. apollo --verbose <cmd> streams one redacted line per API request to stderr — handy when debugging a pipeline — and apollo doctor diagnoses the whole setup with the fix attached to every finding.

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/, then apollo --json chat … --local . --trace, read the trace, and iterate until behavior holds. apollo chat --script turns 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 (data on success, error.code/message/suggestion on failure).
  • Keep the checkout fresh. apollo pull refreshes the program, schemas, skill packs, and AGENTS.md the runtime serves; apollo skills update refreshes all but the program. The checkout’s AGENTS.md tells 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.md also teaches the coding agent to file engine, CLI, and platform faults with apollo report.

Next Steps

Command Reference

Full reference for all CLI commands.

Configuration

Checkout structure, config files, and environment variables.