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 <command> --help to see the full, non-interactive option list for any command.

Quick Reference

Command	Alias	Description
aui login		Authenticate with the AUI platform
aui logout		Clear session and credentials
aui status		Display session and project info
aui env		Show or switch environment
aui sync-session	aui update-session	Re-scope the session to the project’s .auirc
aui account	aui accounts	Manage accounts (projects)
aui agent	aui agents	Manage agents and versions
aui list-agents	aui ls	Quick table of all agents
aui import-agent	aui import	Download agent config locally
aui pull		Pull latest agent files from backend
aui push		Upload local changes to backend
aui diff		Compare agent configurations
aui validate		Validate .aui.json files
aui pull-schema		Fetch latest domain schemas
aui revert		Reset to HEAD (discard local changes)
Runtime Messaging
aui apollo create-thread	create-task	Start a conversation thread
aui apollo send-message		Send a message and get a reply
aui apollo rerun		Regenerate a previous interaction
aui apollo trace		Fetch interaction traces
Version Management
aui version		Manage agent versions
aui version snapshot		Browse, inspect, and diff snapshots
Integrations
aui integration	aui integrations	Manage MCP and Composio integrations
Mock DB
aui mockdb		Per-agent test database
Agent Configuration
aui rag		Manage RAG knowledge bases
aui vault		Store and manage secrets
aui scenarios		Evaluation scenarios and scores
Tools
aui serve		Web-based chat playground
aui upgrade		Update the CLI to the latest version
aui curl		Show the last command’s HTTP calls as curl
aui report		Report a CLI/agent issue or learning

---

Authentication & Session

aui login

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

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 <env>	staging, custom, production (default), or eu-production

aui logout

Clear the local session and stored credentials.

aui logout

aui status

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.

aui status
aui status --json

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 eu-production  # Switch to EU-hosted production
aui env custom         # Switch to custom

The active environment is stored in ~/.aui/environment.

aui sync-session

Re-scope your local session (organization, account, and token) to match this project’s .auirc. Alias: aui update-session.

aui sync-session
aui sync-session --path ./my-agent
aui sync-session --json

Option	Description
--path <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

aui account

Manage accounts (projects). Alias: aui accounts.

aui account                   # Interactive account menu
aui account --list            # List accounts in the session's org
aui account --create <name>   # 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 <name>	Create a new account
--switch [id]	Switch the session’s current account (pass an id, or omit for a picker)

aui agent

Manage agents and versions — list, create, switch, import, delete. Alias: aui agents.

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 <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 <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 <name>	Agent name (skips the name prompt)
--category <id>	Category id, key, or name (default: General)
-d, --dir <path>	Import the new agent into this directory after --create
--template	Create a reusable template (kind=template) at category scope
--account-id <id>	Account ID — scopes --list, pins org+account on --create
--organization-id <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 <agentId>	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 ./<agent-name> folder and drops you into an interactive subshell — run exit to return.

aui list-agents

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

aui ls

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
aui import-agent --version <id>     # Import a specific version
aui import-agent --tag v3.2         # Import a specific revision tag

Option	Description
-d, --dir <path>	Target directory for imported files
--version <id>	Import a specific agent version
--tag <versionTag>	Pull a specific revision tag (e.g. v3.2)
--templates	Pick from category-scoped template agents instead of your agents
--skills <agents>	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.

aui pull

Pull the latest agent files from the backend, overwriting local .aui.json files.

aui pull
aui pull --force            # Skip the overwrite confirmation
aui pull --version <id>     # Pull a specific version
aui pull --tag v3.2         # Pull a specific revision tag

Option	Description
-f, --force	Skip the overwrite confirmation
--version <id>	Pull a specific version (defaults to active)
--tag <versionTag>	Pull a specific revision tag
--no-skills	Skip skill generation

---

Push, Diff & Validate

aui push

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.

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 <id>	Override the agent target (defaults to .auirc)
--version-id <id>	Override the target draft version
--commit-message <msg>	Save note attached to the new revision (≤ 4000 chars)

aui diff

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

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)

aui validate

Validate .aui.json files against domain schemas (*.dschema.json).

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

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
--improved	Apply schema improvements optimized for coding agents
--no-skills	Skip skill generation

aui revert

Reset the project to HEAD, discarding all local changes. Uses git under the hood.

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

aui apollo create-thread

Start a new conversation thread with an agent. Alias: create-task.

aui apollo create-thread
aui apollo create-thread --active            # Run against the live version
aui apollo create-thread --version-id <id>   # Pin to a specific version

Option	Description
--agent-id <id>	Agent to start with (defaults to the current agent)
--user-id <id>	User identifier (defaults to the logged-in user)
--task-origin-type <type>	Origin type (default: web-widget)
--version-id <id>	Pin to a specific version
--version-tag <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.

aui apollo send-message

Send a message to an agent and get a reply. Forwards your local agent files by default so the reply reflects your latest edits.

aui apollo send-message --task-id <id> --text "Hello"
aui apollo send-message --task-id <id> --image ./receipt.png
aui apollo send-message --task-id <id> --text "Search jackets" \
  --selected-tools '[{"tool":"INVENTORY_SEARCH","input":"winter jackets under $80"}]'

Option	Description
--task-id <id>	Required. The conversation thread ID
--text "<message>"	The message to send (optional when --selected-tools is set)
--image <path|url>	Attach an image (local file or http(s) URL)
--selected-tools <json>	JSON array of tools to trigger directly for this message
--agent-context <json>	Seed per-message session facts: {"agent_variables":{…},"context":{…}}
--path <dir>	Read agent files from another folder
--version-id <id> / --version-tag <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.

aui apollo rerun

Regenerate a thread from a given interaction with edited text, then replay. Forwards your local agent files by default.

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

Option	Description
--task-id <id>	Required. The conversation thread ID
--interaction-id <id>	Required. Which interaction to rerun
--text "<message>"	Required. The message to replay
--version-id <id> / --version-tag <tag> / --active	Pin to a specific version
--path <dir>	Read agent files from another folder
--pretty	Human-readable output instead of JSON

aui apollo trace

Fetch interaction traces for a conversation thread. Saves traces to traces/trace_{sequence}.json and prints a compact summary by default.

aui apollo trace --task-id <id>                        # All traces (summary)
aui apollo trace --task-id <id> --interaction-id <id>  # A single trace
aui apollo trace --task-id <id> --full                 # Raw JSON

Option	Description
--task-id <id>	Required. The conversation thread to inspect
--interaction-id <id>	Fetch a single interaction trace instead of all
--full	Print the raw JSON instead of the compact summary

---

Version Management

aui version

Manage the agent version lifecycle. The agent and target version default to your project’s .auirc.

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

aui version snapshot

Browse, inspect, and diff version snapshots — the complete agent configuration captured at a point in time.

aui version snapshot                     # Interactive menu
aui version snapshot list                # List snapshots for the current version
aui version snapshot get <tag>           # Show a snapshot manifest + signed download URLs
aui version snapshot diff <a> <b>        # File-level diff
aui version snapshot diff <a> <b> --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.

aui integration (menu)

aui integration          # Interactive menu (create / discover)

Discovery

aui integration toolkits                          # List native Composio toolkits
aui integration tools --slugs GMAIL_SEND_EMAIL    # Fetch Composio tool metadata by slug
aui integration discover --url <mcp-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 <query>	Filter toolkits by keyword
--all	Follow pagination (all results)
--limit <n>	Page size (default: 50)
--cursor <c>	Pagination cursor

Create

Use --full for a fully non-interactive create (missing required flags fail instead of prompting).

# Manual MCP integration (your own server)
aui integration create --full --name my-mcp --url <mcp-url> --all-tools \
  --auth-type bearer_token --auth-token <tok>

# Native Composio integration (toolkit from the directory)
aui integration create --full --name gmail --toolkit gmail --all-tools

Option	Description
--name <name>	Integration name
--url <url>	MCP server URL (manual integrations)
--toolkit <slug>	Composio toolkit slug (native integrations)
--tools <a,b> / --all-tools	Tools to include
--transport-type <t>	STREAMABLE_HTTP (default) or SSE
--auth-type <type>	none, bearer_token, api_key, or oauth_client_credentials
--auth-token <value>	Credential value for the authentication block
--auth-header-name <h>	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.

Test

Both test commands always emit JSON and are fully non-interactive.

# Live-call an integration endpoint (returns test_data + parsed_test_response + mapped_entities)
aui integration test --params '<json>'
aui integration test --raw --url <url> --method POST --auth-type BEARER_TOKEN --auth-token <tok>

# Execute an MCP tool directly
aui integration mcp-test --type composio --toolkit gmail --tool GMAIL_SEND_EMAIL --arguments '<json>'
aui integration mcp-test --type direct --url <mcp-url> --tool <name> --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.

Provision & inspect

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

Data & endpoints

aui mockdb collections create --name orders --schema '<json>'
aui mockdb collections list
aui mockdb seed --collection orders --rows '<json>'
aui mockdb endpoint create --slug get-order --spec '<json>' --param-schema '<json>'
aui mockdb endpoint list
aui mockdb execute --slug get-order --session <key> --body '<json>'

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.

Sessions, keys & lifecycle

aui mockdb session-get --session <key>     # Inspect a session's overlay
aui mockdb session-reset --session <key>   # 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

aui rag

Manage RAG (Retrieval-Augmented Generation) knowledge bases and files.

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

aui vault

Store and manage secrets referenced by your integrations. Secrets are scoped and never printed back in full.

aui vault set <name>     # Create or rotate a secret (upsert by name + scope)
aui vault list           # List secrets visible in the current scope (masked)
aui vault get <name>     # Show a secret's metadata (never the value)
aui vault rm <name>      # Delete a secret (409 if still referenced)

aui scenarios

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.

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

aui serve

Launch a web-based chat playground on localhost to test your agent in the browser.

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

Option	Description
-p, --port <n>	Port to listen on (default: 3141)
--no-open	Don’t auto-open the browser

aui upgrade

Update aui-agent-builder to the latest version published on npm.

aui upgrade

aui curl

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.

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

aui report

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.

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 <type>	issue (default), learning, or suggestion
-m, --message <m>	Report message (alternative to the positional arg)
--context <json>	Extra context (raw text or JSON)
--dry-run	Print the payload without sending it
--no-bundle	Skip attaching the local .aui.json bundle