Workflows

Import and Edit an Existing Agent

The most common workflow: pull an agent from the cloud, edit it locally, validate, test, and push back.

# Login (opens the browser)
apollo login

# Import the agent into a local checkout — with shell integration, this cds into it
apollo agent import

# Open the checkout in your IDE
cursor .    # or: code .

# Edit the program under bundle/src/

# Validate your changes
apollo validate

# See what changed
apollo diff

# Test against the live runtime (see below), then push to the cloud
apollo push -m "Explain the intent of this change"

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

apollo agent create "Returns Assistant"

# Start from a template instead of an empty draft
apollo agent create "Returns Assistant" --template <id>

# Edit bundle/src/, then:
apollo validate
apollo push -m "First version"

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.

# One-shot probe with the decision trace
apollo chat "I want to return an order" --local . --var caller.id=CUST-1 --trace

# Multi-turn conversation: capture the thread id, then keep appending to it
t=$(apollo --json send "Hi — I need to cancel an order" --local . --var caller.id=CUST-1 \
  | jq -r '.data.thread_id')
for msg in \
  "It's order #W001" \
  "Will I be charged a fee?" \
  "OK, go ahead"; do
  apollo --json send "$msg" --thread "$t" --local . --var caller.id=CUST-1 \
    | jq -r '.data.message.text'
done

# Inspect the conversation afterwards
apollo --json thread messages "$t"
apollo --json thread trace "$t"

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.

Validate, Regress, and Push

The authoring arc is pull → edit → validate → regress → push:

apollo pull                  # program + schemas + skills + AGENTS.md
# edit bundle/src/…
apollo validate              # structural verdict (exit 2 on findings)
apollo regress --follow      # replay the scripted suite through the simulator
apollo push --dry-run        # preview what will ship
apollo push -m "Tighten refund eligibility rule"

validate checks structure; only a run proves conduct — that gates refuse, read-backs execute, and writes land. Add --judge to grade each conversation against the cases it covers. A bundle with no bundle/build/scenarios.yaml has never been graded.

Publish a Version

Pushing mints a version; to make it live, publish it.

apollo version list
apollo version publish v3.0

# Rollback is publishing an older version — it becomes live again
apollo version publish v2.3

# Compare before publishing
apollo diff --remote

Evaluate the Agent

Two lanes run the agent for real, both server-side, both frozen at start so you can keep editing:

# Replay the scripted suite — fixed turns, one conversation per scenario. No push needed.
apollo regress --judge --follow

# Explore with improvising callers planned from guidelines you write. Push first.
apollo push -m "…"
apollo evaluate "the refund refusal path after this change" --follow

# Read a settled run, or pull its conversations and traces down to read
apollo evaluate --status
apollo regress --pull --failures-only

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 binds to a pushed version. Both measure against the case bank in bundle/build/cases.yaml.

Server-Side Authoring

Two commands move authoring itself to the server, grounded in your checkout:

# Ask a grounded question — ships the tree, waits for advice
apollo advise "Why doesn't the fee waiver fire for premium members?"

# Run one gated build turn: green pushes a new version and pulls it back, red refuses
apollo build "Waive cancellation fees for premium members" -m "Fee waiver" --evaluate

Add --publish to build to flip the agent’s active pointer to the pushed version 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:

apollo kb create POLICY_DOCS --description "Cancellation and refund policy"
apollo kb add POLICY_DOCS ./policy/*.md    # or add-url for pages to scrape
apollo kb status POLICY_DOCS               # wait for completed — indexing is async
#  → declare it in bundle/src/sources.yaml:
#      - id: handbook
#        kind: knowledge
#        hub: POLICY_DOCS
apollo kb check                            # hub: refs vs the agent's remote hubs
apollo validate
apollo push -m "Answer policy questions from POLICY_DOCS"
apollo version publish <tag>               # pushing is not publishing

To test retrieval before pushing, send the working tree inline with apollo chat --local . from inside the checkout.

CI/CD Integration

Authenticate with a token, force non-interactive mode, and parse the JSON envelope.

export APOLLO_TOKEN="$CI_APOLLO_TOKEN"

apollo --json --no-input validate
apollo --json --no-input push -m "$COMMIT_MESSAGE"

Exit codes are stable: 0 success, 1 runtime/API failure, 2 validation failure, 3 auth/config failure — gate pipeline steps on them.

apollo --verbose <cmd> streams one redacted line per API request to stderr — handy when debugging a pipeline. 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.
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.

CLI

Workflows

Import and Edit an Existing Agent

Create a New Agent from Scratch

Test Against the Runtime

Validate, Regress, and Push

Publish a Version

Evaluate the Agent

Server-Side Authoring

Ground the Agent in Knowledge

CI/CD Integration

Driving the CLI with a Coding Agent

Next Steps

Command Reference

Configuration

​Import and Edit an Existing Agent

​Create a New Agent from Scratch

​Test Against the Runtime

​Validate, Regress, and Push

​Publish a Version

​Evaluate the Agent

​Server-Side Authoring

​Ground the Agent in Knowledge

​CI/CD Integration

​Driving the CLI with a Coding Agent

​Next Steps

Command Reference

Configuration

Import and Edit an Existing Agent

Create a New Agent from Scratch

Test Against the Runtime

Validate, Regress, and Push

Publish a Version

Evaluate the Agent

Server-Side Authoring

Ground the Agent in Knowledge

CI/CD Integration

Driving the CLI with a Coding Agent

Next Steps