> ## 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.
# Command Reference
> Complete reference for every AUI Agent Builder CLI command.
## Quick Reference
| Command | Alias | Description |
| ------------------------------------------------------- | -------------- | ------------------------------------ |
| [`aui login`](#aui-login) | | Authenticate with the AUI platform |
| [`aui logout`](#aui-logout) | | Clear session and credentials |
| [`aui env`](#aui-env) | | Show or switch environment |
| [`aui status`](#aui-status) | | Display session and project info |
| [`aui agents`](#aui-agents) | `aui agent` | Manage agents |
| [`aui list-agents`](#aui-list-agents) | `aui ls` | Quick table of all agents |
| [`aui account`](#aui-account) | `aui accounts` | Manage accounts |
| [`aui import-agent`](#aui-import-agent) | `aui import` | Download agent config locally |
| [`aui push`](#aui-push) | | Upload local changes to backend |
| [`aui pull`](#aui-pull) | | Pull latest agent files from backend |
| [`aui diff`](#aui-diff) | | Compare agent configurations |
| [`aui validate`](#validate) | | Validate .aui.json files |
| [`aui pull-schema`](#aui-pull-schema) | | Fetch latest domain schemas |
| [`aui chat`](#aui-chat) | | Interactive terminal chat |
| [`aui serve`](#aui-serve) | | Web-based chat playground |
| **Runtime Messaging** | | |
| [`aui apollo create-thread`](#aui-apollo-create-thread) | | Start a conversation thread |
| [`aui apollo send-message`](#aui-apollo-send-message) | | Send a message and get reply |
| [`aui apollo rerun`](#aui-apollo-rerun) | | Regenerate a previous interaction |
| [`aui apollo trace`](#aui-apollo-trace) | | Fetch interaction traces |
| **Version Management** | | |
| [`aui version`](#aui-version) | | Manage agent versions |
| **Integrations** | | |
| [`aui integration`](#aui-integration) | | Manage MCP and Composio integrations |
| [`aui rag`](#aui-rag) | | Manage knowledge bases |
***
## Authentication & Session
Authenticate with the AUI platform.
```bash theme={null}
aui login
aui login --email user@example.com
aui login --token
aui login --api-key --account-id
```
| Option | Description |
| --------------------- | ------------------------------------------------------ |
| `--email ` | Authenticate with email + OTP |
| `--token ` | Authenticate with an access token |
| `--environment ` | Target environment (`staging`, `custom`, `production`) |
| `--account-id ` | Pre-select account |
| `--api-key ` | Use API key authentication |
| `--url ` | Override API base URL |
Clear the local session and stored credentials.
```bash theme={null}
aui logout
```
Show or switch the active environment.
```bash theme={null}
aui env # Show current environment
aui env staging # Switch to staging
aui env production # Switch to production
aui env custom # Switch to custom
```
The active environment is stored in `~/.aui/environment`.
Display current session info, linked agent, and a summary of local project files.
```bash theme={null}
aui status
```
***
## Agent Management
Manage agents interactively. Alias: `aui agent`.
```bash theme={null}
aui agents # Interactive agent menu
aui agents --list # List all agents in the account
aui agents --create # Create a new agent
aui agents --switch # Switch to a different agent
aui agents --import # Import an agent locally
```
| Option | Description |
| ---------- | -------------------------------- |
| `--list` | List all agents |
| `--create` | Create a new agent interactively |
| `--switch` | Switch active agent |
| `--import` | Import agent config files |
Quick table view of all agents in the current account. Alias: `aui ls`.
```bash theme={null}
aui ls
```
Manage accounts (projects). Alias: `aui accounts`.
```bash theme={null}
aui account # Interactive account menu
aui account --list # List all accounts
aui account --create # Create a new account
aui account --switch # Switch active account
```
| Option | Description |
| ----------------- | ---------------------------------------- |
| `--list` | List all accounts |
| `--create ` | Create a new account with the given name |
| `--switch` | Switch active account |
***
## Import & Create
Download an agent's configuration as local `.aui.json` files. Alias: `aui import`.
```bash theme={null}
aui import-agent # Import the currently selected agent
aui import-agent # Import a specific agent by ID
aui import-agent --dir ./my-agent # Import into a specific directory
```
| Option | Description |
| ----------------- | ------------------------------------ |
| `--dir ` | Target directory for imported files |
| `--api-key ` | Use API key instead of session token |
Downloads from 6 backend endpoints: general settings, parameters, entities, integrations, tools, and rules. Also fetches JSON schemas for editor autocomplete and generates a `GUIDE.md`.
Scaffold a new blank agent project with example files.
```bash theme={null}
aui create-agent # Scaffold in current directory
aui create-agent ./my-agent # Scaffold in a specific directory
aui create-agent --force # Overwrite existing files
```
| Option | Description |
| --------- | -------------------------------- |
| `--force` | Overwrite existing project files |
***
## Push, Diff & Validate
Upload local changes to the AUI backend.
```bash theme={null}
aui push
aui push --dry-run
aui push --force
```
| Option | Description |
| ------------------- | ------------------------------------------------ |
| `--dry-run` | Show what would be pushed without making changes |
| `--force` | Push all files, not just changed ones |
| `--skip-validation` | Skip local validation before pushing |
| `--api-key ` | Use API key instead of session token |
Push uses smart patching: **PATCH** for modified fields, **POST** for new tools, **PUT** (upsert) for parameters, entities, and rules. Changes are detected via git diff against the last push baseline.
Compare two agent configurations, or show changes since the last import/push.
```bash theme={null}
aui diff # Show local changes since import
aui diff a.json b.json # Compare two files
```
Validate `.aui.json` files against domain schemas.
```bash theme={null}
aui validate # Validate all files in current directory
aui validate ./agent.aui.json # Validate a specific file
aui validate --verbose # Show detailed validation output
```
| Option | Description |
| ----------- | --------------------------------- |
| `--verbose` | Show detailed validation messages |
Performs:
* JSON syntax checking
* Required fields validation
* Cross-reference integrity (e.g., tools referencing valid integrations)
Fetch the latest domain schemas (`.dschema.json`) from the backend for local validation and editor autocomplete.
```bash theme={null}
aui pull-schema
aui pull-schema --improved
```
| Option | Description |
| ----------------- | -------------------------------------------------- |
| `--api-key ` | Use API key instead of session token |
| `--improved` | Fetch improved schemas optimized for coding agents |
***
## Development & Testing
Start an interactive conversation with an AUI agent in the terminal.
```bash theme={null}
aui chat
aui chat --rest # Use REST API instead of WebSocket
aui chat --user-id # Set a custom user ID
```
| Option | Description |
| ----------------- | ------------------------------------------------ |
| `--api-key ` | Use API key instead of session token |
| `--env ` | Target environment |
| `--user-id ` | Custom user identifier |
| `--rest` | Use REST fallback instead of WebSocket streaming |
Features:
* Real-time streaming via WebSocket
* Inline product cards with images
* AI-generated follow-up suggestions
See [Chat Commands](/cli/workflows#chat-commands) for in-session commands.
Launch a web-based chat playground on localhost.
```bash theme={null}
aui serve
aui serve --port 4000
aui serve --no-open
```
| Option | Description |
| ----------------- | ----------------------------------------- |
| `--port ` | Port to run the server on (default: 3000) |
| `--no-open` | Don't auto-open the browser |
***
## Runtime Messaging — Apollo
Start a new conversation thread with an agent.
```bash theme={null}
aui apollo create-thread
aui apollo create-thread --agent-id
aui apollo create-thread --user-id
```
| Option | Description |
| --------------------------- | ------------------------------------------------------------ |
| `--agent-id ` | Agent to start conversation with (defaults to current agent) |
| `--user-id ` | User identifier (defaults to logged-in user) |
| `--task-origin-type ` | Origin type (default: `web-widget`) |
| `--version-id ` | Pin to a specific draft version |
| `--version-tag ` | Pin to a specific revision tag |
| `--json` | Output JSON format |
Returns a task ID that you use for sending messages.
Send a message to an agent and get a reply. Forwards your local agent files by default.
```bash theme={null}
aui apollo send-message --task-id --text "Hello"
aui apollo send-message --task-id --text "Hello" --no-bundle
aui apollo send-message --task-id --text "Hello" --no-include-trace
```
| Option | Description |
| -------------------- | --------------------------------------------------- |
| `--task-id ` | **Required.** The conversation thread ID |
| `--text ""` | **Required.** The message to send |
| `--no-bundle` | Don't forward local agent files (use stored config) |
| `--no-include-trace` | Don't include trace info in response |
| `--agent-id ` | Agent to check (defaults to current agent) |
| `--path ` | Read agent files from another folder |
| `--json` | Output JSON format |
By default, your local `.aui.json` files are validated and forwarded to the runtime so the reply reflects your latest edits. Use `--no-bundle` to skip this and use the agent's stored configuration instead.
Regenerate a previous interaction with edited text. Forwards your local agent files by default.
```bash theme={null}
aui apollo rerun --task-id --interaction-id --text "Edited message"
aui apollo rerun --task-id --interaction-id --text "Edited" --no-bundle
```
| Option | Description |
| ----------------------- | ---------------------------------------- |
| `--task-id ` | **Required.** The conversation thread ID |
| `--interaction-id ` | **Required.** Which message to rerun |
| `--text ""` | **Required.** The message to replay |
| `--no-bundle` | Don't forward local agent files |
| `--no-include-trace` | Don't include trace info in response |
| `--version-id ` | Pin to a specific version |
| `--version-tag ` | Pin to a specific revision tag |
| `--agent-id ` | Agent to check |
| `--path ` | Read agent files from another folder |
| `--json` | Output JSON format |
Returns a new regenerated task ID and the agent's reply.
Fetch interaction traces for a conversation thread. Always outputs JSON.
```bash theme={null}
aui apollo trace --task-id # All traces
aui apollo trace --task-id --interaction-id # Single trace
```
| Option | Description |
| ----------------------- | ------------------------------------------------ |
| `--task-id ` | **Required.** The conversation thread to inspect |
| `--interaction-id ` | Fetch a single interaction trace instead of all |
| `--agent-id ` | Agent to check (defaults to current agent) |
This command always emits JSON output. There is no human-rendered (Ink) output mode.
***
## Version Management
Interactive version menu for managing agent versions.
```bash theme={null}
aui version # Interactive menu
aui version list # List all versions
aui version create # Create new draft version
aui version publish [id] # Publish a draft (locks permanently)
aui version activate [id] # Activate a published version as live
aui version archive [id] # Archive a published version
aui version get [id] # View version details
aui version update [id] # Update label, tags, or notes
```
Version states:
* **Draft** — editable, not live
* **Published** — locked, can be activated
* **Active** — the live version users talk to
* **Archived** — preserved but inactive
Manage version snapshots for comparing agent configurations.
```bash theme={null}
aui version snapshot # Interactive menu
aui version snapshot list # List snapshots
aui version snapshot get # Show snapshot manifest
aui version snapshot diff # File-level diff
aui version snapshot diff --full # Field-level JSON diff
```
Snapshots capture the complete agent configuration at a point in time for version comparison and rollback.
***
## Integrations
Interactive menu for managing integrations (MCP and Composio).
```bash theme={null}
aui integration # Interactive menu
aui integration toolkits # List Composio toolkits
aui integration tools --slugs # Fetch tool descriptors
aui integration discover --url # Discover MCP tools
aui integration create --full --name --url --all-tools # Create MCP
aui integration create --full --name --toolkit --all-tools # Create Composio
aui integration test --params '' # Test an endpoint
```
| Option | Description |
| ------------------ | -------------------------------- |
| `--json` | Output structured JSON |
| `--search ` | Search toolkits by keyword |
| `--all` | Show all results (no pagination) |
| `--limit ` | Limit results |
| `--cursor ` | Pagination cursor |
Supports both manual MCP server integrations (your own server) and native Composio integrations (from the toolkit directory).
***
## Agent Configuration
Manage RAG (Retrieval-Augmented Generation) knowledge bases.
```bash theme={null}
aui rag # Interactive RAG management menu
aui rag --add-file # Upload a file to a knowledge base
```
| Option | Description |
| ------------ | ---------------------------------------- |
| `--add-file` | Upload a file or URL to a knowledge base |
Capabilities:
* List knowledge bases
* Upload files and URLs
* Export knowledge base content
* Bulk-edit knowledge base entries
The RAG API key is stored securely at `~/.aui/kbm-key` (file mode 600).
Add an integration (API, RAG, or MCP) to the current agent project interactively.
```bash theme={null}
aui add-integration
```
Walks you through selecting the integration type and configuring it.