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.

# 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

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.

---

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.

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

# 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

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

---

Validate and Push Changes

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

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

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

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

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

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

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.

---

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

Command Reference

Full reference for all CLI commands.

Configuration

Project structure, config files, and environment variables.