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

# Workflows

> Common development workflows and best practices for the Apollo CLI.

## Import and Edit an Existing Agent

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

```bash theme={"dark"}
# 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"
```

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

***

## Create a New Agent from Scratch

`apollo agent create` provisions the agent server-side, creates a local checkout, and makes it active.

```bash theme={"dark"}
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.

```bash theme={"dark"}
# 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"
```

<Tip>
  **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.
</Tip>

***

## Validate, Certify, and Push

The authoring arc is **pull → edit → validate → certify → push**:

```bash theme={"dark"}
apollo pull                  # program + schemas + skills + AGENTS.md
# edit bundle/src/…
apollo validate              # structural verdict (exit 2 on findings)
apollo certify               # run the bundle's own scenario suite offline
apollo push --dry-run        # preview what will ship
apollo push -m "Tighten refund eligibility rule"
```

`validate` checks structure; only `certify` proves conduct — that gates refuse, read-backs execute, and writes land. A bundle with no `bundle/src/scenarios.yaml` has never been graded.

***

## Publish a Version

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

```bash theme={"dark"}
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

Run the live evaluation suite server-side — simulated callers plus a judge — over your checkout. The run is frozen at start, so you can keep editing while it runs.

```bash theme={"dark"}
apollo evaluate --follow                       # wait for the verdict
apollo evaluate -m "Post-refactor baseline"    # note shown on the scoreboard
apollo evaluate --scenarios REF-01,REF-02      # scope the run (never promotes)
apollo evaluate --status                       # read the scoreboard later
```

***

## Server-Side Authoring

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

```bash theme={"dark"}
# 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:

```bash theme={"dark"}
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.

```bash theme={"dark"}
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.

<Tip>
  `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.
</Tip>

***

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

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Command Reference" icon="terminal" href="/cli/commands">
    Full reference for all CLI commands.
  </Card>

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