> ## 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. Almost every command accepts a global `--json` flag that emits a structured envelope (`{ "success": true, "data": {...} }`) to stdout for scripting, piping, and coding agents. Run `aui --help` to see the full, non-interactive option list for any command. ## Quick Reference | Command | Alias | Description | | ------------------------------------------------------- | -------------------- | ---------------------------------------------- | | [`aui login`](#aui-login) | | Authenticate with the AUI platform | | [`aui logout`](#aui-logout) | | Clear session and credentials | | [`aui status`](#aui-status) | | Display session and project info | | [`aui env`](#aui-env) | | Show or switch environment | | [`aui sync-session`](#aui-sync-session) | `aui update-session` | Re-scope the session to the project's `.auirc` | | [`aui account`](#aui-account) | `aui accounts` | Manage accounts (projects) | | [`aui agent`](#aui-agent) | `aui agents` | Manage agents and versions | | [`aui list-agents`](#aui-list-agents) | `aui ls` | Quick table of all agents | | [`aui import-agent`](#aui-import-agent) | `aui import` | Download agent config locally | | [`aui pull`](#aui-pull) | | Pull latest agent files from backend | | [`aui push`](#aui-push) | | Upload local changes to backend | | [`aui diff`](#aui-diff) | | Compare agent configurations | | [`aui validate`](#aui-validate) | | Validate `.aui.json` files | | [`aui pull-schema`](#aui-pull-schema) | | Fetch latest domain schemas | | [`aui revert`](#aui-revert) | | Reset to HEAD (discard local changes) | | **Runtime Messaging** | | | | [`aui apollo create-thread`](#aui-apollo-create-thread) | `create-task` | Start a conversation thread | | [`aui apollo send-message`](#aui-apollo-send-message) | | Send a message and get a 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 | | [`aui version snapshot`](#aui-version-snapshot) | | Browse, inspect, and diff snapshots | | **Integrations** | | | | [`aui integration`](#aui-integration) | `aui integrations` | Manage MCP and Composio integrations | | **Mock DB** | | | | [`aui mockdb`](#aui-mockdb) | | Per-agent test database | | **Agent Configuration** | | | | [`aui rag`](#aui-rag) | | Manage RAG knowledge bases | | [`aui vault`](#aui-vault) | | Store and manage secrets | | [`aui scenarios`](#aui-scenarios) | | Evaluation scenarios and scores | | **Tools** | | | | [`aui serve`](#aui-serve) | | Web-based chat playground | | [`aui upgrade`](#aui-upgrade) | | Update the CLI to the latest version | | [`aui curl`](#aui-curl) | | Show the last command's HTTP calls as curl | | [`aui report`](#aui-report) | | Report a CLI/agent issue or learning | *** ## Authentication & Session Authenticate with the AUI platform using the `--environment` option. It opens the browser to sign you in to the chosen environment (`production` is the default): ```bash theme={"dark"} aui login --environment production # Log in to production (default) aui login --environment staging # Log in to staging aui login --environment eu-production # Log in to EU-hosted production aui login --environment custom # Log in to a custom environment ``` | Option | Description | | --------------------- | --------------------------------------------------------------- | | `--environment ` | `staging`, `custom`, `production` (default), or `eu-production` | Clear the local session and stored credentials. ```bash theme={"dark"} aui logout ``` Display current session info, linked agent, and a summary of local project files. Renders a human-readable view by default; pass `--json` for the structured envelope. ```bash theme={"dark"} aui status aui status --json ``` Show or switch the active environment. ```bash theme={"dark"} aui env # Show current environment aui env staging # Switch to staging aui env production # Switch to production aui env eu-production # Switch to EU-hosted production aui env custom # Switch to custom ``` The active environment is stored in `~/.aui/environment`. Re-scope your local session (organization, account, and token) to match this project's `.auirc`. Alias: `aui update-session`. ```bash theme={"dark"} aui sync-session aui sync-session --path ./my-agent aui sync-session --json ``` | Option | Description | | --------------- | -------------------------------------------------------- | | `--path ` | Project directory containing `.auirc` (default: nearest) | `aui login` issues a token scoped to your default organization. If you imported an agent that lives in a different org, `push` / `pull` / `apollo` calls return `403` or `404` until the session is re-scoped. This command fixes that — and the CLI runs the same reconciliation automatically before most commands. It's a no-op (zero network calls) when already in sync. *** ## Accounts & Agents Manage accounts (projects). Alias: `aui accounts`. ```bash theme={"dark"} aui account # Interactive account menu aui account --list # List accounts in the session's org aui account --create # Create a new account aui account --switch [id] # Switch the session's current account ``` | Option | Description | | ----------------- | ----------------------------------------------------------------------- | | `--list` | List all accounts in your current session's org (session-scoped) | | `--create ` | Create a new account | | `--switch [id]` | Switch the session's current account (pass an id, or omit for a picker) | Manage agents and versions — list, create, switch, import, delete. Alias: `aui agents`. ```bash theme={"dark"} aui agent # Interactive agent menu aui agent --list # List agents for an account aui agent --create # Create a new agent (provisioned end-to-end) aui agent --create --name X --account-id # Non-interactive create aui agent --create --full # Create + version + publish + activate aui agent --switch # Set the session's current agent aui agent --versions [agentId] # List versions for an agent aui agent --delete --network-id --yes # Delete an entire agent ``` | Option | Description | | ------------------------ | ----------------------------------------------------------------------------- | | `--list` | List agents for an account (scope: `--account-id`, else the project `.auirc`) | | `--categories` | List available network categories (id, key, name) | | `--create` | Create a new agent (bundle-mode, provisioned server-side) | | `--if-not-exists` | With `--create`: import the existing agent on a name conflict (409) | | `--full` | Create + version + publish + activate in one step | | `--name ` | Agent name (skips the name prompt) | | `--category ` | Category id, key, or name (default: General) | | `-d, --dir ` | Import the new agent into this directory after `--create` | | `--template` | Create a reusable template (kind=template) at category scope | | `--account-id ` | Account ID — scopes `--list`, pins org+account on `--create` | | `--organization-id ` | Organization ID for `--create` | | `--switch` | Set the session's current agent + version (interactive picker) | | `--import` | Import an agent from the backend | | `--versions [agentId]` | List versions for an agent | | `--use ` | Select an agent directly by ID | | `--delete` | Delete an agent or a version | | `-y, --yes` | Skip confirmation prompts (required for non-interactive `--delete`) | Agent creation is always bundle-mode: one call provisions everything server-side (network → agent → first version → publish → activate). After creating, the CLI auto-imports the agent into a `./` folder and drops you into an interactive subshell — run `exit` to return. Quick table view of all agents in the current account. Alias: `aui ls`. ```bash theme={"dark"} aui ls ``` Download an agent's configuration as local `.aui.json` files. Alias: `aui import`. ```bash theme={"dark"} 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 aui import-agent --version # Import a specific version aui import-agent --tag v3.2 # Import a specific revision tag ``` | Option | Description | | -------------------- | ------------------------------------------------------------------------------- | | `-d, --dir ` | Target directory for imported files | | `--version ` | Import a specific agent version | | `--tag ` | Pull a specific revision tag (e.g. `v3.2`) | | `--templates` | Pick from category-scoped template agents instead of your agents | | `--skills ` | Comma-separated coding agents to generate skills for (claude, cursor, opencode) | | `--no-skills` | Skip skill generation entirely | | `--with-kb-files` | Also download original KB binaries (PDF, CSV, …) | | `--reset-git` | On re-import, wipe local git history and start a fresh baseline | Downloads general settings, parameters, entities, integrations, tools, and rules; fetches JSON schemas for editor autocomplete; generates a `GUIDE.md`; and (by default) scaffolds coding-agent skills. Pull the latest agent files from the backend, overwriting local `.aui.json` files. ```bash theme={"dark"} aui pull aui pull --force # Skip the overwrite confirmation aui pull --version # Pull a specific version aui pull --tag v3.2 # Pull a specific revision tag ``` | Option | Description | | -------------------- | -------------------------------------------- | | `-f, --force` | Skip the overwrite confirmation | | `--version ` | Pull a specific version (defaults to active) | | `--tag ` | Pull a specific revision tag | | `--no-skills` | Skip skill generation | *** ## Push, Diff & Validate Upload local changes to the AUI backend as a new revision on your draft version. Changes are detected via git diff against the last push baseline. ```bash theme={"dark"} aui push aui push --dry-run aui push --commit-message "Tighten refund eligibility rule" ``` | Option | Description | | ------------------------ | ----------------------------------------------------- | | `--dry-run` | Preview what would be pushed without making changes | | `--agent-id ` | Override the agent target (defaults to `.auirc`) | | `--version-id ` | Override the target draft version | | `--commit-message ` | Save note attached to the new revision (≤ 4000 chars) | Compare two agent configurations, or show changes since the last import/push. ```bash theme={"dark"} aui diff # Show local changes since last push aui diff --sinceImport # Show all changes since first import aui diff ./a ./b # Compare two agent folders ``` | Option | Description | | --------------- | ------------------------------------------------------- | | `--sinceImport` | Show all changes since the first import (not last push) | Validate `.aui.json` files against domain schemas (`*.dschema.json`). ```bash theme={"dark"} aui validate # Validate all files in the current directory aui validate ./agent.aui.json # Validate a specific file aui validate --verbose # Detailed validation output aui validate --strict # Treat warnings as errors ``` | Option | Description | | --------------- | ---------------------------------------------------- | | `-v, --verbose` | Detailed output | | `--strict` | Treat warnings as errors (e.g. `test_curl` warnings) | Performs JSON syntax checking, required-field validation, and 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={"dark"} aui pull-schema aui pull-schema --improved ``` | Option | Description | | ------------- | ----------------------------------------------------- | | `--improved` | Apply schema improvements optimized for coding agents | | `--no-skills` | Skip skill generation | Reset the project to `HEAD`, discarding all local changes. Uses git under the hood. ```bash theme={"dark"} aui revert aui revert -f # Also delete untracked files aui revert --steps 2 # Revert back 2 commits ``` | Option | Description | | ------------- | -------------------------------- | | `-f` | Also delete untracked files | | `--steps ` | Number of commits to revert back | *** ## Runtime Messaging — Apollo The `aui apollo` commands wrap the Apollo runtime endpoints. They **default to JSON output** (built for tooling and coding agents) — pass `--pretty` for the human terminal view. `send-message` and `rerun` validate and forward your local `.aui.json` files, so replies reflect your latest edits. Start a new conversation thread with an agent. Alias: `create-task`. ```bash theme={"dark"} aui apollo create-thread aui apollo create-thread --active # Run against the live version aui apollo create-thread --version-id # Pin to a specific version ``` | Option | Description | | --------------------------- | --------------------------------------------------- | | `--agent-id ` | Agent to start with (defaults to the current agent) | | `--user-id ` | User identifier (defaults to the logged-in user) | | `--task-origin-type ` | Origin type (default: `web-widget`) | | `--version-id ` | Pin to a specific version | | `--version-tag ` | Pin to a specific revision tag | | `--active` | Run against the agent's currently active version | | `--pretty` | Human-readable output instead of JSON | Returns a task ID you pass to the other commands as `--task-id`. Send a message to an agent and get a reply. Forwards your local agent files by default so the reply reflects your latest edits. ```bash theme={"dark"} aui apollo send-message --task-id --text "Hello" aui apollo send-message --task-id --image ./receipt.png aui apollo send-message --task-id --text "Search jackets" \ --selected-tools '[{"tool":"INVENTORY_SEARCH","input":"winter jackets under $80"}]' ``` | Option | Description | | -------------------------------------------------------- | ----------------------------------------------------------------------- | | `--task-id ` | **Required.** The conversation thread ID | | `--text ""` | The message to send (optional when `--selected-tools` is set) | | `--image ` | Attach an image (local file or `http(s)` URL) | | `--selected-tools ` | JSON array of tools to trigger directly for this message | | `--agent-context ` | Seed per-message session facts: `{"agent_variables":{…},"context":{…}}` | | `--path ` | Read agent files from another folder | | `--version-id ` / `--version-tag ` / `--active` | Pin THIS message to a specific version | | `--pretty` | Human-readable output instead of JSON | The reply always includes the trace (`trace_info`). The id it returns is the interaction id for `rerun` / `trace --interaction-id`. Regenerate a thread from a given interaction with edited text, then replay. Forwards your local agent files by default. ```bash theme={"dark"} aui apollo rerun --task-id --interaction-id --text "Edited message" ``` | Option | Description | | -------------------------------------------------------- | ---------------------------------------- | | `--task-id ` | **Required.** The conversation thread ID | | `--interaction-id ` | **Required.** Which interaction to rerun | | `--text ""` | **Required.** The message to replay | | `--version-id ` / `--version-tag ` / `--active` | Pin to a specific version | | `--path ` | Read agent files from another folder | | `--pretty` | Human-readable output instead of JSON | Fetch interaction traces for a conversation thread. Saves traces to `traces/trace_{sequence}.json` and prints a compact summary by default. ```bash theme={"dark"} aui apollo trace --task-id # All traces (summary) aui apollo trace --task-id --interaction-id # A single trace aui apollo trace --task-id --full # Raw JSON ``` | Option | Description | | ----------------------- | ------------------------------------------------- | | `--task-id ` | **Required.** The conversation thread to inspect | | `--interaction-id ` | Fetch a single interaction trace instead of all | | `--full` | Print the raw JSON instead of the compact summary | *** ## Version Management Manage the agent version lifecycle. The agent and target version default to your project's `.auirc`. ```bash theme={"dark"} aui version # Interactive menu aui version list # List all versions aui version create # Create a new draft (updates .auirc to point at it) aui version publish [id] # Publish a draft (locks it 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 Browse, inspect, and diff version snapshots — the complete agent configuration captured at a point in time. ```bash theme={"dark"} aui version snapshot # Interactive menu aui version snapshot list # List snapshots for the current version aui version snapshot get # Show a snapshot manifest + signed download URLs aui version snapshot diff # File-level diff aui version snapshot diff --full # Field-level JSON diff (downloads files) ``` *** ## Integrations Wire up external capabilities as **manual MCP** integrations (your own MCP server) or **native Composio** integrations (from the toolkit directory). The discovery, create, and test subcommands are fully non-interactive with `--json` support. Alias: `aui integrations`. ```bash theme={"dark"} aui integration # Interactive menu (create / discover) ``` ```bash theme={"dark"} aui integration toolkits # List native Composio toolkits aui integration tools --slugs GMAIL_SEND_EMAIL # Fetch Composio tool metadata by slug aui integration discover --url # Discover tools from a manual MCP server aui integration mcp-url --toolkit gmail --all-tools # Provision/reuse a Composio MCP server ``` | Option | Description | | ------------------ | ------------------------------- | | `--search ` | Filter toolkits by keyword | | `--all` | Follow pagination (all results) | | `--limit ` | Page size (default: 50) | | `--cursor ` | Pagination cursor | Use `--full` for a fully non-interactive create (missing required flags fail instead of prompting). ```bash theme={"dark"} # Manual MCP integration (your own server) aui integration create --full --name my-mcp --url --all-tools \ --auth-type bearer_token --auth-token # Native Composio integration (toolkit from the directory) aui integration create --full --name gmail --toolkit gmail --all-tools ``` | Option | Description | | ------------------------------- | ---------------------------------------------------------------- | | `--name ` | Integration name | | `--url ` | MCP server URL (manual integrations) | | `--toolkit ` | Composio toolkit slug (native integrations) | | `--tools ` / `--all-tools` | Tools to include | | `--transport-type ` | `STREAMABLE_HTTP` (default) or `SSE` | | `--auth-type ` | `none`, `bearer_token`, `api_key`, or `oauth_client_credentials` | | `--auth-token ` | Credential value for the authentication block | | `--auth-header-name ` | Header carrying the credential (required for `api_key`) | | `--full` | Fully non-interactive | OAuth client-credentials and Composio BYO-auth flags (`--oauth-*`, `--composio-*`) are also supported — run `aui integration create --help` for the complete list. Both test commands always emit JSON and are fully non-interactive. ```bash theme={"dark"} # Live-call an integration endpoint (returns test_data + parsed_test_response + mapped_entities) aui integration test --params '' aui integration test --raw --url --method POST --auth-type BEARER_TOKEN --auth-token # Execute an MCP tool directly aui integration mcp-test --type composio --toolkit gmail --tool GMAIL_SEND_EMAIL --arguments '' aui integration mcp-test --type direct --url --tool --arguments '{}' --raw ``` By default `integration test` sends a `bundle_mapping` so the response also returns `mapped_entities` — a preview of the entities the runtime would extract. Pass `--raw` for a plain endpoint call with no mapping. *** ## Mock DB `aui mockdb` provisions a per-agent test database so you can develop and test tools against realistic data without touching production systems. All subcommands emit JSON. ```bash theme={"dark"} aui mockdb provision # Create the mock DB; store runtime + management keys aui mockdb describe # Schemas, relationships, endpoints, row counts aui mockdb status # Verify where this agent's mock DB lives aui mockdb keys # Show locally stored key prefixes (no secrets) aui mockdb guide # Write the full mock DB how-to to GUIDE.md ``` ```bash theme={"dark"} aui mockdb collections create --name orders --schema '' aui mockdb collections list aui mockdb seed --collection orders --rows '' aui mockdb endpoint create --slug get-order --spec '' --param-schema '' aui mockdb endpoint list aui mockdb execute --slug get-order --session --body '' ``` Seed rows accept relative date tokens like `now-30d`. Endpoint kinds are read / insert / update / delete; writes via `execute` require a `--session` (copy-on-write overlay). Create parent collections before children so foreign keys resolve. ```bash theme={"dark"} aui mockdb session-get --session # Inspect a session's overlay aui mockdb session-reset --session # Reset a session to pristine base data aui mockdb rotate-runtime-key # Mint a new runtime key aui mockdb rotate-mgmt-key # Mint a new management key aui mockdb export # Export schema + base data + endpoints aui mockdb delete --force # Permanently delete the mock DB ``` *** ## Agent Configuration Manage RAG (Retrieval-Augmented Generation) knowledge bases and files. ```bash theme={"dark"} aui rag # Interactive RAG management menu aui rag --add-file # Upload a file or URL to a knowledge base aui rag --status # Per-resource indexing status for each knowledge base ``` | Option | Description | | ------------ | ------------------------------------------------------- | | `--add-file` | Add a file or URL to a knowledge hub | | `--status` | Show indexing status (completed / failed / in-progress) | The RAG API key is stored securely at `~/.aui/kbm-key` (file mode 600). Store and manage secrets referenced by your integrations. Secrets are scoped and never printed back in full. ```bash theme={"dark"} aui vault set # Create or rotate a secret (upsert by name + scope) aui vault list # List secrets visible in the current scope (masked) aui vault get # Show a secret's metadata (never the value) aui vault rm # Delete a secret (409 if still referenced) ``` Evaluation scenarios and scores. Run these from **inside** an agent project directory (they read `agent_management_id` / `version_id` / `version_tag` from `.auirc`) and are fully non-interactive. ```bash theme={"dark"} aui scenarios generate # Scaffold scenarios/ (intent/ + skeleton scenarios.aui.json) aui scenarios pull # Pull the latest scenarios bundle + scores aui scenarios pull --version 3 # Pull a specific build-bundle version aui scenarios push # Push the bundle, then the local scores aui scenarios push --notes "…" # Attach a note to the build bundle aui scenarios score # Show local scores (pass/total) aui scenarios score --remote # List the version's recorded score history ``` Local layout: `scenarios/scenarios.aui.json`, `scenarios/scenarios-scores.aui.json`, and `scenarios/intent/` (raw intent files, docs, sample data). Scenario generation is skill-driven — the coding agent fills in scenarios from the intent files. *** ## Tools Launch a web-based chat playground on localhost to test your agent in the browser. ```bash theme={"dark"} aui serve aui serve --port 4000 aui serve --no-open ``` | Option | Description | | ---------------- | --------------------------------- | | `-p, --port ` | Port to listen on (default: 3141) | | `--no-open` | Don't auto-open the browser | Update `aui-agent-builder` to the latest version published on npm. ```bash theme={"dark"} aui upgrade ``` Show the HTTP requests made by the **last** command, rendered as reproducible `curl` commands. Useful for debugging and for understanding exactly what the CLI sent. ```bash theme={"dark"} aui curl aui curl --failed # Only failed requests aui curl --last 3 # Only the last 3 requests aui curl --method POST # Filter by HTTP method aui curl --search tasks # Filter by URL or label substring ```
Beta
Report a CLI or agent issue, a learning, or a suggestion back to AUI. Coding agents driving the CLI are expected to use this to surface problems. ```bash theme={"dark"} aui report "push failed with a confusing error" aui report -t learning -m "rules.aui.json ordering matters for sequencing" aui report --dry-run -m "…" # Print the payload without sending ``` | Option | Description | | ------------------- | -------------------------------------------------- | | `-t, --type ` | `issue` (default), `learning`, or `suggestion` | | `-m, --message ` | Report message (alternative to the positional arg) | | `--context ` | Extra context (raw text or JSON) | | `--dry-run` | Print the payload without sending it | | `--no-bundle` | Skip attaching the local `.aui.json` bundle |