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

# AUI Agent Builder CLI

> Build, manage, and deploy AI agent configurations from your terminal with a local-first workflow.

<div style={{ display: "flex", gap: "8px", marginBottom: "16px" }}>
  <span
    style={{
background: "#F59E0B",
color: "#fff",
padding: "2px 10px",
borderRadius: "12px",
fontSize: "13px",
fontWeight: 500,
}}
  >
    Beta
  </span>

  <span
    style={{
background: "rgba(129,105,255,0.15)",
color: "#8169FF",
padding: "2px 10px",
borderRadius: "12px",
fontSize: "13px",
fontWeight: 500,
}}
  >
    v0.4.45
  </span>

  <span
    style={{
background: "rgba(34,197,94,0.15)",
color: "#22C55E",
padding: "2px 10px",
borderRadius: "12px",
fontSize: "13px",
fontWeight: 500,
}}
  >
    GA Q2 2026
  </span>
</div>

```bash theme={"dark"}
npm install -g aui-agent-builder
```

AUI Agent Builder is a CLI tool for building, managing, and deploying AI agent configurations on the AUI platform. It enables a **local-first development workflow**: import agents as typed JSON files, edit them in your IDE with schema autocomplete, validate locally, test them against the live Apollo-1 runtime, and push changes back to the cloud.

**Current version:** 0.4.45

<Info>
  The CLI is designed to be driven by **coding agents** as much as by humans. Nearly every command is fully non-interactive with a `--json` output mode, so tools like Cursor, Claude Code, and the Agent Builder can author, run, and iterate on an agent end-to-end.
</Info>

## Quick Start

```bash theme={"dark"}
# 1. Authenticate (walks you through org → account → agent)
aui login --environment production

# 2. Create a new agent (provisioned end-to-end, then imported locally)
aui agent --create

# 3. Edit .aui.json files in your IDE (VSCode/Cursor get schema autocomplete)

# 4. Validate your changes
aui validate

# 5. Test against the live runtime without deploying
aui serve

# 6. Push changes to the cloud
aui push
```

To work on an agent that already exists, swap step 2 for `aui import-agent`.

## Key Features

<AccordionGroup>
  <Accordion title="Local-First Development">
    Import agent configs as `.aui.json` files. Edit them in VSCode or Cursor
    with full JSON schema autocomplete. Version control is git — diffs against
    `rules.aui.json` are real diffs, and rollback is `git revert`.
  </Accordion>

  <Accordion title="Schema Validation">
    Validate agent configurations locally with `aui validate` before pushing.
    Catches JSON syntax errors, missing required fields, and cross-reference
    issues. Schemas are pulled from the backend with `aui pull-schema`.
  </Accordion>

  <Accordion title="Smart Push with Diffing">
    `aui push` detects changes via git diff and uploads only what changed, as a
    new revision on your draft version. Preview first with `aui push --dry-run`.
  </Accordion>

  <Accordion title="Runtime Messaging & Testing">
    Talk to your agent against the real Apollo-1 runtime with the `aui apollo`
    commands (create a thread, send a message, rerun an interaction, fetch the
    trace) — or launch a web playground on localhost with `aui serve`. Your
    local edits are forwarded so replies reflect your latest changes.
  </Accordion>

  <Accordion title="Version Management">
    Manage the full version lifecycle — draft, publish, activate, archive — with
    `aui version`, and compare configurations across time with
    `aui version snapshot`.
  </Accordion>

  <Accordion title="Integrations, Mock DB & Secrets">
    Wire up MCP and Composio integrations with `aui integration`, spin up a
    per-agent test database with `aui mockdb`, and store credentials securely
    with `aui vault`.
  </Accordion>

  <Accordion title="Evaluation Scenarios">
    Generate, push, and score evaluation scenarios with `aui scenarios` to turn
    a faithful agent into a reliable one.
  </Accordion>

  <Accordion title="Multi-Environment Support">
    Switch between `staging`, `custom`, `production`, and `eu-production`
    environments with `aui env`. Test safely before deploying.
  </Accordion>
</AccordionGroup>

## How It Works

<Steps>
  <Step title="Login">
    Authenticate with browser login, email + OTP, an access token, or an API key
    using `aui login`. The CLI then walks you through selecting your
    organization, account, and agent.
  </Step>

  <Step title="Create or Import">
    Provision a new agent end-to-end with `aui agent --create` (it auto-imports
    into a `./<agent-name>` folder), or pull an existing agent locally with
    `aui import-agent`.
  </Step>

  <Step title="Develop">
    Edit `.aui.json` files in your IDE. Schema autocomplete works out of the box
    in VSCode and Cursor. Follow the generated `GUIDE.md` for step-by-step help.
  </Step>

  <Step title="Validate & Test">
    Run `aui validate` to check syntax, required fields, and cross-reference
    integrity, then test behavior with `aui apollo send-message` or `aui serve`.
  </Step>

  <Step title="Push & Ship">
    Deploy changes with `aui push` (use `--dry-run` to preview), then `aui
            version publish` and `aui version activate` to make a version live.
  </Step>
</Steps>

## Get Started

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/cli/installation">
    Install the CLI and authenticate with your AUI account.
  </Card>

  <Card title="Command Reference" icon="terminal" href="/cli/commands">
    Full reference for every CLI command.
  </Card>

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

  <Card title="Workflows" icon="route" href="/cli/workflows">
    Common development workflows and best practices.
  </Card>
</CardGroup>