> ## 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 AUI Agent Builder 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 and select your org/account/agent
aui login --environment production

# Import the agent configuration locally
aui import-agent

# Open the directory in your IDE
cd my-agent
cursor .    # or: code .

# Edit any .aui.json file — you get schema autocomplete in VSCode/Cursor

# Validate your changes
aui validate

# See what changed
aui diff

# Test against the live runtime (see below), then push to the cloud
aui push
```

<Info>
  After importing, your IDE gets automatic JSON schema autocomplete for all `.aui.json` files, and coding-agent skills are generated for Cursor, Claude Code, and opencode — no additional setup required.
</Info>

***

## Create a New Agent from Scratch

Provision a new agent end-to-end and start building. `aui agent --create` creates the agent server-side, then imports it locally and drops you into its folder.

```bash theme={"dark"}
# Login first
aui login --environment production

# Create a new agent (interactive)
aui agent --create

# ...or non-interactively (no pickers)
aui agent --create --name "Returns Assistant" --account-id <id>

# Follow GUIDE.md, edit the .aui.json files, then:
aui validate
aui push
```

The generated `GUIDE.md` walks you through configuring each file in order.

***

## Test Against the Runtime

Talk to your agent against the real Apollo-1 runtime. Your local `.aui.json` files are forwarded by default, so replies reflect your latest edits — no deploy required.

```bash theme={"dark"}
# Terminal-based, scriptable messaging
TASK=$(aui apollo create-thread --json | jq -r .data.task_id)
aui apollo send-message --task-id "$TASK" --text "I want to return an order" --pretty
aui apollo trace --task-id "$TASK"

# Or launch a web playground on localhost
aui serve
```

<Info>
  The `aui apollo` commands default to JSON output (built for scripting and coding agents). Pass `--pretty` for the human-readable view.
</Info>

***

## Validate and Push Changes

Always validate before pushing. Use `--dry-run` to preview.

```bash theme={"dark"}
# Validate all project files
aui validate

# Preview what will be pushed
aui push --dry-run

# Push changes as a new revision, with a save note
aui push --commit-message "Tighten refund eligibility rule"
```

Made a mess locally? Discard all uncommitted changes with `aui revert`.

***

## Publish and Activate a Version

Pushing updates your **draft**. To make changes live, publish and activate a version.

```bash theme={"dark"}
# Inspect versions
aui version list

# Publish the current draft (locks it permanently)
aui version publish

# Activate the published version as live
aui version activate

# Compare two snapshots when reviewing a change
aui version snapshot diff <tag-a> <tag-b> --full
```

***

## Evaluate with Scenarios

Turn a faithful agent into a reliable one by scoring it against evaluation scenarios. Run these from inside the agent project.

```bash theme={"dark"}
# Scaffold the scenarios/ folder
aui scenarios generate

# (a coding agent fills in scenarios/ from the intent files)

# Push the bundle and record scores for this version
aui scenarios push --notes "baseline eval"

# Review scores
aui scenarios score
aui scenarios score --remote
```

***

## Switch Between Environments

Test on staging before deploying to production.

```bash theme={"dark"}
# Work on staging
aui env staging
aui import-agent
# ... make changes ...
aui validate
aui push

# When ready, switch to production
aui env production
aui push
```

***

## CI/CD Integration

Use environment variables to skip interactive login in CI pipelines.

```bash theme={"dark"}
export AUI_AUTH_TOKEN="your-jwt-token"
export AUI_ENVIRONMENT="production"
export AUI_ACCOUNT_ID="your-account-id"
export AUI_ORGANIZATION_ID="your-org-id"

# Validate and push
aui validate
aui push
```

<Tip>
  Add `--json` to any command to get a machine-readable envelope, and use `aui curl` after a command to see exactly which HTTP requests it made — handy when debugging a pipeline.
</Tip>

***

## Driving the CLI with a Coding Agent

The CLI is built to be driven by coding agents (Cursor, Claude Code, the Agent Builder). Nearly every command is non-interactive and supports `--json`, and importing an agent generates skill files so the agent knows the workflow.

* **Author → run → read the trace → revise.** Have the agent edit `.aui.json` files, then `aui apollo send-message ... --json`, read `trace_info`, and iterate until behavior holds.
* **Report learnings.** Coding agents should surface issues and learnings with `aui report`.
* **Keep the session aligned.** `aui sync-session` reconciles the session with the project's `.auirc` (runs automatically before most commands).

***

## 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">
    Project structure, config files, and environment variables.
  </Card>
</CardGroup>