Skip to main content

​
Quick Reference

CommandAliasDescription
aui loginAuthenticate with the AUI platform
aui logoutClear session and credentials
aui envShow or switch environment
aui statusDisplay session and project info
aui agentsaui agentManage agents
aui list-agentsaui lsQuick table of all agents
aui accountaui accountsManage accounts
aui import-agentaui importDownload agent config locally
aui pushUpload local changes to backend
aui pullPull latest agent files from backend
aui diffCompare agent configurations
aui validateValidate .aui.json files
aui pull-schemaFetch latest domain schemas
aui chatInteractive terminal chat
aui serveWeb-based chat playground
Runtime Messaging
aui apollo create-threadStart a conversation thread
aui apollo send-messageSend a message and get reply
aui apollo rerunRegenerate a previous interaction
aui apollo traceFetch interaction traces
Version Management
aui versionManage agent versions
Integrations
aui integrationManage MCP and Composio integrations
aui ragManage knowledge bases

​
Authentication & Session

Authenticate with the AUI platform.
aui login
aui login --email user@example.com
aui login --token <jwt>
aui login --api-key <key> --account-id <id>
OptionDescription
--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
Clear the local session and stored credentials.
aui logout
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.
Display current session info, linked agent, and a summary of local project files.
aui status

​
Agent Management

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
OptionDescription
--listList all agents
--createCreate a new agent interactively
--switchSwitch active agent
--importImport agent config files
Quick table view of all agents in the current account. Alias: aui ls.
aui ls
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
OptionDescription
--listList all accounts
--create <name>Create a new account with the given name
--switchSwitch active account

​
Import & Create

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
OptionDescription
--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.
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
OptionDescription
--forceOverwrite existing project files

​
Push, Diff & Validate

Upload local changes to the AUI backend.
aui push
aui push --dry-run
aui push --force
OptionDescription
--dry-runShow what would be pushed without making changes
--forcePush all files, not just changed ones
--skip-validationSkip 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.
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
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
OptionDescription
--verboseShow 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.
aui pull-schema
aui pull-schema --improved
OptionDescription
--api-key <key>Use API key instead of session token
--improvedFetch improved schemas optimized for coding agents

​
Development & Testing

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
OptionDescription
--api-key <key>Use API key instead of session token
--env <env>Target environment
--user-id <id>Custom user identifier
--restUse 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.
Launch a web-based chat playground on localhost.
aui serve
aui serve --port 4000
aui serve --no-open
OptionDescription
--port <number>Port to run the server on (default: 3000)
--no-openDon’t auto-open the browser

​
Runtime Messaging — Apollo

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>
OptionDescription
--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
--jsonOutput 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.
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
OptionDescription
--task-id <id>Required. The conversation thread ID
--text "<message>"Required. The message to send
--no-bundleDon’t forward local agent files (use stored config)
--no-include-traceDon’t include trace info in response
--agent-id <id>Agent to check (defaults to current agent)
--path <dir>Read agent files from another folder
--jsonOutput 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.
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
OptionDescription
--task-id <id>Required. The conversation thread ID
--interaction-id <id>Required. Which message to rerun
--text "<message>"Required. The message to replay
--no-bundleDon’t forward local agent files
--no-include-traceDon’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
--jsonOutput JSON format
Returns a new regenerated task ID and the agent’s reply.
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
OptionDescription
--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

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

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
OptionDescription
--jsonOutput structured JSON
--search <query>Search toolkits by keyword
--allShow 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

Manage RAG (Retrieval-Augmented Generation) knowledge bases.
aui rag                    # Interactive RAG management menu
aui rag --add-file         # Upload a file to a knowledge base
OptionDescription
--add-fileUpload 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.
aui add-integration
Walks you through selecting the integration type and configuring it.