Command Reference

Complete reference for every AUI Agent Builder CLI command.

Quick Reference

Command	Alias	Description
aui login		Authenticate with the AUI platform
aui logout		Clear session and credentials
aui env		Show or switch environment
aui status		Display session and project info
aui agents	aui agent	Manage agents
aui list-agents	aui ls	Quick table of all agents
aui account	aui accounts	Manage accounts
aui import-agent	aui import	Download agent config locally
aui push		Upload local changes to backend
aui pull		Pull latest agent files from backend
aui diff		Compare agent configurations
aui validate		Validate .aui.json files
aui pull-schema		Fetch latest domain schemas
aui chat		Interactive terminal chat
aui serve		Web-based chat playground
Runtime Messaging
aui apollo create-thread		Start a conversation thread
aui apollo send-message		Send a message and get reply
aui apollo rerun		Regenerate a previous interaction
aui apollo trace		Fetch interaction traces
Version Management
aui version		Manage agent versions
Integrations
aui integration		Manage MCP and Composio integrations
aui rag		Manage knowledge bases

---

Authentication & Session

aui login

Authenticate with the AUI platform.

aui login
aui login --email [e-mail]
aui login --token <jwt>
aui login --api-key <key> --account-id <id>

Option	Description
--email <email>	Authenticate with email + OTP
--token <jwt>	Authenticate with an access token
--environment <env>	Target environment (staging, custom, production)
--account-id <id>	Pre-select account
--api-key <key>	Use API key authentication
--url <url>	Override API base URL

aui logout

Clear the local session and stored credentials.

aui logout

aui env

Show or switch the active environment.

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.

aui status

Display current session info, linked agent, and a summary of local project files.

aui status

---

Agent Management

aui agents

Manage agents interactively. Alias: aui agent.

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

aui list-agents

Quick table view of all agents in the current account. Alias: aui ls.

aui ls

aui account

Manage accounts (projects). Alias: aui accounts.

aui account              # Interactive account menu
aui account --list       # List all accounts
aui account --create <name>   # Create a new account
aui account --switch     # Switch active account

Option	Description
--list	List all accounts
--create <name>	Create a new account with the given name
--switch	Switch active account

---

Import & Create

aui import-agent

Download an agent’s configuration as local .aui.json files. Alias: aui import.

aui import-agent                  # Import the currently selected agent
aui import-agent <agent-id>      # Import a specific agent by ID
aui import-agent --dir ./my-agent # Import into a specific directory

Option	Description
--dir <path>	Target directory for imported files
--api-key <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.

aui create-agent

Scaffold a new blank agent project with example files.

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

aui push

Upload local changes to the AUI backend.

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

aui diff

Compare two agent configurations, or show changes since the last import/push.

aui diff                 # Show local changes since import
aui diff a.json b.json   # Compare two files

aui validate

Validate .aui.json files against domain schemas.

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)

aui pull-schema

Fetch the latest domain schemas (.dschema.json) from the backend for local validation and editor autocomplete.

aui pull-schema
aui pull-schema --improved

Option	Description
--api-key <key>	Use API key instead of session token
--improved	Fetch improved schemas optimized for coding agents

---

Development & Testing

aui chat

Start an interactive conversation with an AUI agent in the terminal.

aui chat
aui chat --rest            # Use REST API instead of WebSocket
aui chat --user-id <id>    # Set a custom user ID

Option	Description
--api-key <key>	Use API key instead of session token
--env <env>	Target environment
--user-id <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 for in-session commands.

aui serve

Launch a web-based chat playground on localhost.

aui serve
aui serve --port 4000
aui serve --no-open

Option	Description
--port <number>	Port to run the server on (default: 3000)
--no-open	Don’t auto-open the browser

---

Runtime Messaging — Apollo

aui apollo create-thread

Start a new conversation thread with an agent.

aui apollo create-thread
aui apollo create-thread --agent-id <id>
aui apollo create-thread --user-id <id>

Option	Description
--agent-id <id>	Agent to start conversation with (defaults to current agent)
--user-id <id>	User identifier (defaults to logged-in user)
--task-origin-type <type>	Origin type (default: web-widget)
--version-id <id>	Pin to a specific draft version
--version-tag <tag>	Pin to a specific revision tag
--json	Output JSON format

Returns a task ID that you use for sending messages.

aui apollo send-message

Send a message to an agent and get a reply. Forwards your local agent files by default.

aui apollo send-message --task-id <id> --text "Hello"
aui apollo send-message --task-id <id> --text "Hello" --no-bundle
aui apollo send-message --task-id <id> --text "Hello" --no-include-trace

Option	Description
--task-id <id>	Required. The conversation thread ID
--text "<message>"	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 <id>	Agent to check (defaults to current agent)
--path <dir>	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.

aui apollo rerun

Regenerate a previous interaction with edited text. Forwards your local agent files by default.

aui apollo rerun --task-id <id> --interaction-id <id> --text "Edited message"
aui apollo rerun --task-id <id> --interaction-id <id> --text "Edited" --no-bundle

Option	Description
--task-id <id>	Required. The conversation thread ID
--interaction-id <id>	Required. Which message to rerun
--text "<message>"	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 <id>	Pin to a specific version
--version-tag <tag>	Pin to a specific revision tag
--agent-id <id>	Agent to check
--path <dir>	Read agent files from another folder
--json	Output JSON format

Returns a new regenerated task ID and the agent’s reply.

aui apollo trace

Fetch interaction traces for a conversation thread. Always outputs JSON.

aui apollo trace --task-id <id>                              # All traces
aui apollo trace --task-id <id> --interaction-id <id>        # Single trace

Option	Description
--task-id <id>	Required. The conversation thread to inspect
--interaction-id <id>	Fetch a single interaction trace instead of all
--agent-id <id>	Agent to check (defaults to current agent)

This command always emits JSON output. There is no human-rendered (Ink) output mode.

---

Version Management

aui version

Interactive version menu for managing agent versions.

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

aui version snapshot

Manage version snapshots for comparing agent configurations.

aui version snapshot                    # Interactive menu
aui version snapshot list               # List snapshots
aui version snapshot get <tag>          # Show snapshot manifest
aui version snapshot diff <a> <b>       # File-level diff
aui version snapshot diff <a> <b> --full # Field-level JSON diff

Snapshots capture the complete agent configuration at a point in time for version comparison and rollback.

---

Integrations

aui integration

Interactive menu for managing integrations (MCP and Composio).

aui integration                                  # Interactive menu
aui integration toolkits                         # List Composio toolkits
aui integration tools --slugs <A,B>              # Fetch tool descriptors
aui integration discover --url <mcp-url>         # Discover MCP tools
aui integration create --full --name <n> --url <url> --all-tools  # Create MCP
aui integration create --full --name <n> --toolkit <slug> --all-tools  # Create Composio
aui integration test --params '<json>'           # Test an endpoint

Option	Description
--json	Output structured JSON
--search <query>	Search toolkits by keyword
--all	Show all results (no pagination)
--limit <n>	Limit results
--cursor <c>	Pagination cursor

Supports both manual MCP server integrations (your own server) and native Composio integrations (from the toolkit directory).

---

Agent Configuration

aui rag

Manage RAG (Retrieval-Augmented Generation) knowledge bases.

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

aui add-integration

Add an integration (API, RAG, or MCP) to the current agent project interactively.

aui add-integration

Walks you through selecting the integration type and configuring it.