aui-agent-builder

v0.4.58

Published

a day ago

CLI for building, managing, and deploying AUI AI agent configurations

Downloads

11,923

0High
0Medium
0Low

aui cli agent conversational-ai agent-builder chatbot

AUI Agent Builder CLI

Build, version, and deploy AI agents from your terminal. Import agent configurations as local JSON files, edit them in your editor with full schema autocomplete, validate changes, push to the backend, and manage versions — all from the command line.

Features

Code-first agent development — Edit agent configurations as JSON files in your editor with schema-driven autocomplete
Version management — Create drafts, publish, activate, and archive agent versions with full lifecycle control
Smart diff & validation — See exactly what changed, validate against domain schemas before pushing
Knowledge base management — Upload documents and URLs, export/import KB configurations
Scope-level control — Import and push at network, account, organization, or category scope
IDE integration — Auto-generated schemas, Cursor rules, Claude skills, and OpenCode skills for AI-assisted editing
CI/CD ready — Every command has a non-interactive mode with flags for automation
Web playground — Built-in chat UI for testing agents locally

Installation

npm install -g aui-agent-builder

Requires Node.js 18+.

Verify installation:

aui -v

Quick Start

# 1. Authenticate
aui login

# 2. Import an existing agent (or create one with: aui agents --create)
aui import-agent

# 3. Edit .aui.json files in your editor (schema autocomplete works out of the box)

# 4. See what changed
aui diff

# 5. Validate
aui validate

# 6. Push changes
aui push

# 7. Publish and go live
aui version publish
aui version activate

Core Concepts

Hierarchy

Organization
└── Account (Project)
    └── Agent (Network)
        └── Version (v1.0, v1.1, v2.0, ...)

| Concept | Description | |---------|-------------| | Organization | Top-level workspace, tied to your login credentials | | Account | A project within the organization | | Agent | An AI agent (also called a "network") within a project | | Version | An immutable snapshot of the agent's full configuration |

Agent Configuration

Each agent is composed of these configuration types:

| Config | File | Purpose | |--------|------|---------| | General Settings | agent.aui.json | Name, objective, persona, tone, guardrails | | Parameters | parameters.aui.json | Data the agent collects from users and outputs | | Entities | entities.aui.json | Groups of related parameters | | Integrations | integrations.aui.json | API, RAG, and MCP connections | | Tools | tools/*.aui.json | Agent capabilities (one file per tool) | | Rules | rules.aui.json | Global behavioral rules | | Computations | computations.aui.json | Deterministic calculation nodes (bundle-mode agents only) | | Widgets | widgets.aui.json | Card templates for rich UI responses |

Version Lifecycle

draft ──→ published ──→ active
                    └──→ archived

| State | Editable | Can Activate | Description | |-------|----------|-------------|-------------| | Draft | Yes | No | Work in progress. Receives pushes | | Published | No | Yes | Locked permanently. Ready to go live | | Active | No | — | The live production configuration | | Archived | No | No | Retired. Can still be viewed and cloned |

Commands Reference

Discovering commands

aui --help                  # Human-readable command overview
aui <command> --help        # Options for any command (e.g. aui integration test --help)
aui --help --json           # Full command tree as a JSON envelope (for tooling / coding agents)
aui <command> --help --json # JSON help scoped to a single command/subcommand

aui --help --json emits { "success": true, "data": { name, version, command } }, where command recursively lists every subcommand with its description, arguments, and options (each option carries flags, description, default, and takesRequiredValue / takesOptionalValue).

Authentication

aui login                              # Open browser for authentication (defaults to the production environment)
aui login --email <email>              # Login with email (OTP)
aui login --environment staging        # Login to a specific environment (staging | custom | production | eu-production)
aui login --token <jwt>                # Login with a JWT token (for CI/CD)
aui login --token <jwt> --refresh-token <jwt>   # Token + refresh token (auto-renewal in automated pipelines)
aui login --account-id <id>            # Skip account selection
aui login --url <url>                  # Override the default login/playground URL
aui logout                             # Clear local session and credentials

Agent Management

aui agents                       # Interactive menu: list, create, switch, import, delete
aui agents --list                # List agents (scope: --account-id, else the project's .auirc account)
aui agents --create              # Create, then auto-import into ./<agent-name> and drop you in
aui agents --create --template --category <id>   # Create a clone-source template at category scope
aui agents --switch              # Switch the SESSION's current agent + version (interactive picker)
aui agents --versions [agentId]  # List versions for an agent (accepts an agent-management OR network id)
aui agents --use <agentId>       # Select an agent directly by ID
aui agents --delete              # Interactive: org → account → agent → choose scope (whole / one version / all versions)

aui agents --create is end-to-end. It creates the agent + its first version, auto-imports the editable draft into a new ./<agent-name> folder (use --dir <path> to override), and drops you into that folder via an interactive subshell so you can start editing immediately — run exit to return. Agents are always created in bundle mode in every environment — staging, custom, production, and eu-production alike (provisioned end-to-end via Apollo). Records-mode creation has been retired.

The Apollo endpoint provisions everything server-side (network → agent → version → publish → activate) and creates a draft for editing; the CLI imports that draft (resolved via GET .../versions), not the published active version — you can only aui push into a draft. It never creates a draft itself (falls back to the active version only if none is found). Non-interactive creation is create-only: --json, piped output, CI, and the agent-builder-bff sandbox skip BOTH the auto-import and the subshell and behave like a plain create (set AUI_AUTO_IMPORT=1 to force the import in automation; AUI_AUTO_IMPORT=0 to disable it in a terminal). A child process can't change the parent shell's cwd, which is why the interactive case opens a nested shell.

Non-interactive creation:

# Minimal — still prompts for org/account
aui agents --create --name "My Agent"

# Fully non-interactive
aui agents --create --name "My Agent" --account-id <id>

# With a specific category (e.g. Amazon, Google Flights)
aui agents --create --name "My Agent" --account-id <id> --category Amazon

# Import the new agent into a specific folder instead of ./<agent-name>
aui agents --create --name "My Agent" --account-id <id> --dir ./my-agent

# One-step: create + version + publish + activate
aui agents --create --name "My Agent" --account-id <id> --full

Interactive flow:

aui agents --delete walks you through the same picker the create / import flows use:

Select organization
Select account
Select agent (with the active version surfaced inline)
Choose what to delete:
- Delete entire agent — single API call, removes ALL versions. Confirmed by typing the agent name.
- Delete a specific version — pick from the version list. Yes/no confirm.
- Delete all versions — loops per-version DELETEs, keeps the agent shell. The currently active version is attempted last and may be rejected by the backend.

Non-interactive deletion (irreversible — requires --yes to skip confirmation):

# Delete an entire agent (and ALL of its versions) by network ID — single API call
aui agents --delete --network-id <network-id> --yes

# Loop per-version DELETE for an agent (keeps the agent shell, removes every version)
aui agents --delete --agent-id <agent-id> --all-versions --yes

# Delete a specific version of the current agent
aui agents --delete --version <version-id> --yes

# Delete a specific version of a specific agent (fully explicit)
aui agents --delete --agent-id <agent-id> --version <version-id> --yes

# JSON output (for CI/CD; --yes is mandatory for actual delete)
aui agents --delete --network-id <network-id> --yes --json

Notes
--delete --network-id <id> is a single DELETE /v1/agents/network/{network_id} — removes the agent record AND every version in one call.
--delete --agent-id <id> --all-versions loops per-version DELETE /v1/agents/{agent_id}/versions/{version_id} calls — useful when you want to clear history but keep the agent shell. The active version is attempted last; the backend may reject it.
Deleting a single version is also rejected by the backend if it is currently active — activate a different version first, or delete the entire agent instead.
If you delete the agent or version that's currently selected in your session, the CLI clears the session pointer and tells you to switch.
All DELETE calls are captured by aui curl for inspection / replay.

Import & Pull

aui import-agent                              # Interactive: select org → account → agent
aui import-agent <agent-id>                   # Import by network ID
aui import-agent --version <id>               # Import a specific version
aui import-agent --tag <vX.Y>                 # Pull a specific revision tag (e.g. v3.2)
aui import-agent --scope-level category       # Import at category scope
aui import-agent --dir ./my-folder            # Output to a specific directory
aui import-agent --templates                  # Pick from category-scoped template agents (kind=template)
aui import-agent --templates --category <id>  # Restrict the template picker to one category
aui import-agent --with-kb-files              # Also download original KB binaries (skipped by default)
aui import-agent --skip-kb-files              # Skip the knowledge-base-files schema fetch
aui import-agent --skills claude,cursor,opencode   # Generate AI coding skills
aui import-agent --no-skills                  # Skip skill generation
aui import-agent --exclude-skills             # Write .claude/.cursor/.opencode to the CWD instead of --dir
aui import-agent --skills-env <env>           # Override env for Notion skill/doc pages
aui import-agent --include-evaluate           # Include the evaluate (test_questions) schema
aui import-agent --reset-git                  # On re-import, wipe local git history and start a fresh baseline

[!IMPORTANT] aui import-agent defaults to the active version. With no --version (or --tag), you silently get whatever is live in the backend — not the version you think you're editing. The version that's active can change out from under you (someone else activates a new one, a rollback happens, etc.).
Always pass --version <id> (or --tag <vX.Y>) to pin exactly what you import, and then fingerprint-check the result before you start editing — confirm you got the right version by spot-checking something cheap and deterministic, e.g. the parameter count, the number of tools/rules, or the version tag printed in the import summary. If the fingerprint doesn't match what you expect, you imported the wrong version — re-import with the correct --version.

aui pull                                  # Pull latest into existing project (defaults to the active version)
aui pull --force                          # Skip overwrite confirmation
aui pull --version <id>                   # Pull a specific agent version by ID
aui pull --tag <vX.Y>                     # Pull a specific revision tag (e.g. v3.2)
aui pull --scope-level <level>            # Pull at a specific scope level
aui pull --with-kb-files                  # Also download original KB binaries
aui pull --skip-kb-files                  # Skip the knowledge-base-files schema fetch
aui pull --skills claude,cursor,opencode  # Regenerate AI coding skills
aui pull --no-skills                      # Skip skill generation
aui pull --include-evaluate               # Include the evaluate (test_questions) schema

Push

Push is only allowed to draft versions. If no draft exists, the CLI will reject the push and guide you to create one first.

aui push                                  # Push changes into the current draft version
aui push --dry-run                        # Preview without pushing
aui push --scope-level category           # Push at a specific scope level
aui push --agent-id <id>                  # Override agent target (agent_management_id or network_id; defaults to .auirc)
aui push --version-id <id>                # Push into a specific draft (must be a draft)
aui push --commit-message "<msg>"         # Save note attached to the new revision (≤ 4000 chars)
aui push --caller <agent_builder|ui|cli>  # Multipart "caller" field for the /push endpoint (default: cli)
aui push --force                          # Accepted for back-compat (no-op under the current endpoint)
aui push --skip-validation                # Accepted for back-compat (no-op under the current endpoint)

If push fails partially, re-run aui push to retry the failed changes.

Version Management

aui version                               # Interactive version menu
aui version list                          # List all versions
aui version list --json                   # Machine-readable: full (untruncated) IDs + stats

# Create — single step, NO prompts (always bumps version number: v1, v2, v3, ...)
aui version create                                        # Auto: picks source by agent mode
aui version create --source agent-scope                   # Override: new version from live scope
aui version create --source version --from <id>           # Override: clone from a specific version
aui version create --source template --from-template <id> # Override: clone from a template agent's bundle
aui version create --agent-id <agent-management-id>       # Target a specific agent explicitly
aui version create --label "Release 2" --tags "prod" --notes "..."   # Optional metadata

# Lifecycle (no prompts — resolve agent + version from .auirc, or pass them explicitly)
aui version publish                       # Publish the .auirc draft
aui version publish <id>                  # Publish a specific draft (overrides .auirc)
aui version activate                      # Activate the .auirc version as live
aui version activate <id>                 # Activate a specific version (overrides .auirc)
aui version archive <id>                  # Archive a published version (cannot be re-activated)

# Metadata
aui version get <id>                      # View full version details
aui version update <id> --label "Release 2" --tags "prod,stable" --notes "Bug fixes"

Which agent does aui version * target? Resolution order: --agent-id (explicit) → the project's .auirc (agent_management_id, then agent_id) → the active session's agent. Inside a project, the CLI resolves the project's own agent; if its .auirc ids don't resolve it now errors instead of silently falling back to your session's "current" agent. This is the same resolver aui push uses, so version and push always target the same agent.
version create is single-step and never prompts. It inspects the agent's storage mode (the same detectAgentBundleMode switch push / pull / import use — honours AUI_FORCE_AGENT_MODE, defaults to records on older backends) and creates the draft directly:
| Agent mode | Request body | |------------|--------------| | bundle (bundle_mode=true) | source: "version", from_version: <active version> (override with --from) | | records (bundle_mode=false / missing) | source: "agent-scope" |
--source / --from / --from-template / --label / --tags / --notes all override; with no flags it "just works" for the agent's mode. Because it never prompts, it's safe for Claude Code, CI, and agent-builder-bff sandboxes.
Non-interactive / automation for other version subcommands. list, get, etc. run without prompts in --json mode or when stdin/stdout isn't a TTY. When several agents could match and none is selected, pass --agent-id rather than relying on the picker. For programmatic consumers, always read IDs and stats from --json — the human table abbreviates IDs to fit the terminal.

Knowledge Bases & Documents

All knowledge-base work goes through aui rag. The bare command opens an interactive menu (list KBs, upload files, upload URLs, export, import); the flags jump straight to a specific action.

aui rag                # Interactive menu: list, upload files, upload URLs, export, import
aui rag --add-file     # Jump straight to the upload flow (files or URLs)
aui rag --status       # Per-resource indexing status (completed / failed / in-progress) for each KB

The standalone aui document … command has been folded into aui rag — uploads and indexing status now live under the single rag command.

Development Tools

aui validate                              # Validate all .aui.json files
aui validate ./tools/                     # Validate specific directory
aui validate --strict                     # Treat warnings as errors
aui diff                                  # Changes since last import/push
aui diff ./folder-a ./folder-b            # Compare two directories
aui status                                # Session, agent, and project info
aui revert                                # Discard local changes

Integrations

aui integration                   # Interactive menu — Create or Discover
aui integration create            # Guided flow — org, account, agent, Manual or Native MCP (add --full for non-interactive)
aui integration discover          # Guided MCP tool discovery
aui integration toolkits          # List native (Composio) toolkits  (non-interactive, --json)
aui integration tools --slugs ... # Fetch Composio tool descriptors by slug  (non-interactive, --json)
aui integration mcp-url --toolkit <slug>   # Provision (or reuse) a Composio MCP server → { server_id, server_url }
aui integration test --params ... # Live-call an HTTP endpoint, return raw + parsed response  (always JSON)
aui integration mcp-test ...      # Execute an MCP tool directly (Composio or Direct) and return the raw response (always JSON)

Discovery (fully non-interactive, --json):

aui integration toolkits --all --json                       # every native toolkit
aui integration toolkits --search notion --json             # filter the directory
aui integration tools --slugs GMAIL_SEND_EMAIL,GMAIL_CREATE_EMAIL_DRAFT --json
aui integration discover --url <mcp-url> --json             # tools from a manual MCP server
aui integration mcp-url --toolkit gmail --all-tools --json  # provision/reuse a Composio MCP server

Non-interactive — Manual MCP (add --full to skip every prompt):

aui integration create --full --name "My MCP" --url <url> --all-tools
aui integration create --full --name "My MCP" --url <url> --tools tool1,tool2
aui integration create --full --name "My MCP" --url <url> --all-tools --auth-type token --auth-token <token>
aui integration discover --url <url>
aui integration discover --url <url> --auth-type token --auth-token <token>
aui integration discover --url <url> --auth-type api_key --auth-token <key> --auth-header-name X-API-Key

Non-interactive — Native MCP (add --full to skip every prompt):

aui integration create --full --toolkit notion --name "Notion" --all-tools
aui integration create --full --toolkit github --name "GitHub" --tools GITHUB_CREATE_ISSUE,GITHUB_GET_ISSUE

MCP authentication (--auth-type). Manual MCP, discover, and mcp-test share the same canonical auth surface (the CLI alias token maps to bearer_token before anything is sent to the wire):

| Auth type | Flags | |-----------|-------| | none | (default) | | bearer_token (alias token) | --auth-type bearer_token --auth-token <tok> | | api_key | --auth-type api_key --auth-token <key> --auth-header-name <Header> | | oauth_client_credentials | --auth-type oauth_client_credentials --oauth-url <token-endpoint> --oauth-client-id <id> --oauth-client-secret <secret> [--oauth-method GET\|POST] [--oauth-grant-type <grant>] |

Shared flags (both Manual & Native):

| Flag | Description | |------|-------------| | --organization-id <id> | Skip org selection | | --account-id <id> | Skip account selection | | --network-id <id> | Skip agent selection | | --version-id <id> | Agent version ID | | --config-method <manual\|native> | Force config method | | --json | Machine-readable JSON output |

Test an integration endpoint (aui integration test):

Live-call an integration endpoint and get back the raw response (test_data), what the response_parser extracts (parsed_test_response), and — on the default path — mapped_entities (how the response maps onto the agent's entities). The programmatic replacement for hand-running curl. Always emits a JSON envelope and is fully non-interactive.

--raw vs. the default differ only in what is sent:

--raw → calls the endpoint without bundle_mapping (plain integration test; no mapped_entities).
default → also sends bundle_mapping (response_mapping + parameters + scope_entities), so the endpoint also returns mapped_entities. This is the path the LLM uses while building an agent.

# Default — full simulation incl. entity mapping
aui integration test --params '{
  "url": "https://www.themealdb.com/api/json/v1/1/search.php",
  "method": "GET",
  "query_params": { "s": "pasta" },
  "bundle_mapping": {
    "response_mapping": { "entities": [ { "code": "Meal", "identifier": "meal-id", "paths": ["meals"], "mappings": [ { "key": "idMeal", "param": "meal-id" }, { "key": "strMeal", "param": "meal-name" } ] } ] },
    "parameters": [ { "code": "meal-id", "type": "string" }, { "code": "meal-name", "type": "string" } ],
    "scope_entities": [ { "name": "Meal", "identifier": "meal-id", "reference": "meal-name", "parameters": ["meal-id","meal-name"] } ]
  }
}'

# Raw — no bundle_mapping / mapped_entities
aui integration test --raw --url https://www.themealdb.com/api/json/v1/1/search.php --query-params '{"s":"pasta"}'

| Flag | Description | |------|-------------| | --params <json> | Full request body (see fields below) | | --params-file <path> | Read the request body JSON from a file | | --url <url> | Endpoint URL (overrides params.url) | | --method <method> | HTTP method (default GET) | | --request-body <json> | Request body JSON | | --query-params <json> | Query params JSON | | --headers <json> | Extra request headers JSON | | --auth-type <type> | BEARER_TOKEN, API_KEY, BASIC, NONE | | --auth-token <token> | Auth token used with --auth-type | | --response-parser <js> | JS snippet run against response | | --bundle-mapping <json> | Full bundle_mapping (response_mapping, parameters, scope_entities) | | --response-mapping <json> | bundle_mapping.response_mapping (from integrations.aui.json → settings.response_mapping) | | --parameters <json> | bundle_mapping.parameters (from parameters.aui.json → parameters) | | --scope-entities <json> | bundle_mapping.scope_entities (from entities.aui.json → entities) | | --raw | Plain call without bundle_mapping (no mapped_entities) |

authentication is a discriminated union keyed on type (BEARER_TOKEN, API_KEY, BASIC, …). An empty {} or one without a type is treated as "no auth" and dropped automatically (it would otherwise 422), so you can paste an integration config verbatim.

Output: { "success": true, "data": { url, method, raw, bundle_mapping_sent, test_data, parsed_test_response, mapped_entities } }.

Execute an MCP tool (aui integration mcp-test):

Live-execute a single MCP tool — either a Composio (native) tool or a tool on a Direct (manual) MCP server — and get the raw tool response back. Like integration test, it returns mapped_entities when a bundle_mapping is sent. Always emits a JSON envelope; non-interactive when --toolkit+--tool or --url+--tool are provided.

# Composio — send an email
aui integration mcp-test --type composio --toolkit gmail --tool GMAIL_SEND_EMAIL \
  --arguments '{"to":"[email protected]","subject":"Hi","body":"Test"}'

# Direct MCP server — bearer token (raw, no mapping)
aui integration mcp-test --type direct --url https://my-mcp.example.com/mcp \
  --transport-type STREAMABLE_HTTP \
  --auth-type bearer_token --auth-token <token> \
  --tool <tool-name> --arguments '{}' --raw

# Direct MCP server — API key in a custom header
aui integration mcp-test --type direct --url https://my-mcp.example.com/mcp \
  --auth-type api_key --auth-token <key> --auth-header-name X-API-Key \
  --tool <tool-name> --arguments '{}' --raw

Output: { "success": true, "data": { type, tool, raw, bundle_mapping_sent, response, mapping_data, status, elapsed_sec } }.

Provision a Composio MCP server (aui integration mcp-url):

aui integration mcp-url --toolkit gmail --all-tools --json   # → { server_id, server_url }
aui integration mcp-url --toolkit notion --tools NOTION_CREATE_PAGE --server-id <existing-id> --json

Chat & Testing

aui serve                                 # Web chat playground (localhost:3141)
aui serve --port 8080                     # Custom port

Runtime Messaging — Apollo

Drive an agent at runtime through the Apollo messaging API. These four commands are fully non-interactive, output JSON by default (pass --pretty for the human view on all but trace), and work for any agent (bundle-mode or records-mode). The target agent is resolved from --agent-id or .auirc.agent_management_id, and authentication uses your normal CLI session (Authorization: Bearer — the gateway forwards Apollo's service auth for you).

# Start a conversation thread (alias: create-task) — JSON output by default
aui apollo create-thread                                 # uses .auirc agent + logged-in user
aui apollo create-thread --agent-id <id> --user-id <id> --task-origin-type web-widget
aui apollo create-thread --active                        # run against the agent's live version
aui apollo create-thread --pretty                        # human terminal view instead of JSON

# Send a message. It validates + forwards your local .aui.json edits, so the
# reply reflects them; the returned `id` IS the interaction id.
aui apollo send-message --task-id <id> --text "Hello"                       # trace_info always included
# Trigger a tool directly by code + order (--text optional when --selected-tools is given):
aui apollo send-message --task-id <id> \
  --selected-tools '[{"tool":"INVENTORY_SEARCH","input":"winter jackets","order":1,"identifiers":["sku-123"]}]'
# Seed caller-known session facts (pre-populates the task; not raw LLM input):
aui apollo send-message --task-id <id> --text "show my orders" \
  --agent-context '{"agent_variables":{"user_id":"u_123","locale":"en-US"},"context":{"url":"https://example.com"}}'

# Regenerate a thread from an interaction and replay a message (bundle + trace always sent)
aui apollo rerun --task-id <id> --interaction-id <iid> --text "Edited"
aui apollo rerun --task-id <id> --interaction-id <iid> --text "Edited" --version-id <vid>
aui apollo rerun --task-id <id> --interaction-id <iid> --text "Edited" --active   # vs the live version

# Inspect the agent's reasoning (trace) — always JSON
aui apollo trace --task-id <id>                          # all interaction traces
aui apollo trace --task-id <id> --interaction-id <iid>   # a single interaction's trace

Flags by command

| Command | Required | Optional | |---|---|---| | create-thread (alias create-task) | — | --agent-id, --user-id, --task-origin-type, --version-id, --version-tag, --active, --pretty | | send-message | --task-id, (--text and/or --selected-tools) | --selected-tools, --agent-id, --agent-context, --version-id, --version-tag, --active, --path, --pretty | | rerun | --task-id, --interaction-id, --text | --version-id, --version-tag, --active, --agent-id, --path, --pretty | | trace | --task-id | --interaction-id, --agent-id (always JSON) |

JSON by default: create-thread, send-message, and rerun emit the JSON envelope by default; pass --pretty for the human Ink view. trace is always JSON.

--active (create-thread, send-message, rerun): run against the agent's currently active (live) version instead of the local draft / passed version. Resolves the agent's active_version_id from agent-management. Mutually exclusive with --version-id / --version-tag.

--version-id / --version-tag / --active (send-message): run a single message on a specific agent version without changing the version stored on the task (Apollo's message-level agent override). The override applies only to that one interaction; the next message (without these flags) runs on the task-level version again. --version-id is the selector; --version-tag is auto-filled by the runtime when omitted; --active pins the live version. Unlike create-thread / rerun, the version is never defaulted from .auirc / the session — it's an explicit opt-in.

--agent-context (send-message): a JSON object {"agent_variables":{…},"context":{…}} of caller-known session facts. agent_variables are consumed by the runtime as the agent's agent_context config to pre-populate the task (not sent to the LLM as raw text); context is optional extra per-message fields (url, welcome_message, …).

--selected-tools (send-message): a JSON array of tools to trigger directly — [{"tool":"<CODE>","input":"…","order":1,"identifiers":["…"]}] (Apollo ExternalSelectedTool). tool is the tool code from your agent's tools/ files (required); input is an optional argument string; order (default 1) sets ascending run order across multiple tools; identifiers (default []) scope the call. Use it to run specific capabilities deterministically instead of inferring them from --text (which becomes optional when --selected-tools is given — pass one or both).

Bundle always sent: both send-message and rerun validate + forward your local agent files (so the reply reflects your edits). Run these inside an imported agent folder (or pass --path <dir>).

Interaction IDs: the id returned by aui apollo send-message is the interaction id — pass it to rerun --interaction-id and trace --interaction-id.

Validate-before-send: by default send-message / rerun run the remote validator on your local files first and abort if they're invalid — a broken config never reaches the runtime. Run aui validate to see specific errors.

Configuration & Utilities

aui account                               # Manage accounts (list, create, switch)
aui env                                   # Show current environment
aui env staging                           # Switch environment (staging | custom | production | eu-production)
aui pull-schema                           # Fetch domain schemas from backend
aui pull-schema --improved                # Apply coding-agent-friendly schema improvements
aui sync-session                          # Re-scope your session (org/account/token) to this project's .auirc
aui integration create                    # Create MCP integration (Manual or Native)
aui curl                                  # Show the last command's HTTP requests as curl commands
aui report "<message>"                    # BETA: report a CLI/agent issue or learning
aui upgrade                               # Update to the latest version

Session Sync

aui login issues a token scoped to your default organization. If you import an agent that lives in a different org, push / pull / apollo calls return 403 or 404 ("Agent not found") until the session is re-scoped. aui sync-session reconciles your local session (~/.aui/session.json) with this project's .auirc — organization, account, and the token's org claim — so every command targets the right org.

aui sync-session                  # Reconcile the session with the nearest .auirc
aui sync-session --path ./my-agent   # Point at a specific project directory
aui sync-session --json           # Machine-readable (for scripts / the BFF)
aui update-session                # Alias for sync-session

Behavior: no-op (zero network) when already in sync. Cross-org → mints and persists an org-scoped token. Cross-env (the .auirc env differs from the session env) → a token can't be re-scoped across environments, so it switches the env and exits non-zero asking you to aui login on that env. Fully non-interactive — safe to run from agent-builder-bff in the sandbox.

Inspecting HTTP requests — `aui curl`

Every command's HTTP calls are captured and can be replayed as curl commands for debugging.

aui curl                          # All requests from the last command
aui curl --failed                 # Only failed requests
aui curl --last <n>               # Only the last N requests
aui curl --method PATCH           # Filter by HTTP method
aui curl --search <term>          # Filter by URL or label substring

Reporting issues — `aui report` (BETA)

Report a CLI or agent issue, a learning, or a suggestion. Coding agents are expected to use this to surface problems they hit.

aui report "Push failed with a confusing 422"        # type defaults to "issue"
aui report -t learning -m "PATCH is idempotent on retry"
aui report --dry-run "..."                           # Print the payload without sending

| Flag | Description | |------|-------------| | -t, --type <type> | issue (default), learning, or suggestion | | -m, --message <msg> | Report message (alternative to the positional argument) | | --agent <name> | Override the detected coding agent (claude / cursor / opencode) | | --context <json> | Extra context — raw text or a JSON string | | --dry-run | Print the payload without sending it | | --task-id / --session-id / --interaction-id <id> | Associate the report with a task / session / interaction |

Command Aliases

| Alias | Equivalent | |-------|------------| | aui import | aui import-agent | | aui accounts | aui account | | aui agents | aui agent | | aui ls | aui list-agents | | aui versions | aui version | | aui integrations | aui integration | | aui update-session | aui sync-session | | aui apollo create-task | aui apollo create-thread | | aui version snapshots | aui version snapshot |

Workflows

Create and Deploy a New Agent

# Step 1: Create the agent. This also auto-imports it into ./support-agent
# and drops you into that folder via an interactive subshell — no separate
# `aui import-agent` needed. (Use --dir to choose a different folder.)
aui agents --create --name "Support Agent" --account-id <id>

# Step 2: Edit configuration in your editor (you're already in the folder)
# → Edit agent.aui.json, tools/*.aui.json, parameters.aui.json, etc.

# Step 3: Validate and push
aui validate
aui push

# Step 4: Publish and activate
aui version publish
aui version activate

Prefer the classic two-step flow? It still works: create with --json (which skips the auto-import/subshell), then run aui import-agent yourself.

Creation modes:

# Default — creates the agent + a v1.0 draft version (ready to import & edit).
# A draft is always created; there is no flag to skip it.
aui agents --create --name "Support Agent" --account-id <id>

# Agent + v1.0 + publish + activate — fully deployed in one step (CI/CD)
aui agents --create --name "Support Agent" --account-id <id> --full

Edit → Push → Deploy Cycle

# 1. Create a draft version first
aui version create                # Creates draft v2

# 2. Import the draft as local files
aui import-agent --version <draft-id>
cd ./my-agent

# 3. Make changes to any .aui.json file...

# 4. Validate and push
aui diff                          # See what changed
aui validate                      # Validate against schemas
aui push                          # Push changes into the draft

# 5. If push fails partially, re-run to retry
aui push                          # Retries only failed changes

# 6. Publish and go live
aui version publish               # Lock the draft
aui version activate              # Make it live

Version Branching

# Clone from an existing version (→ v3)
aui version create --source version --from <v2-id>

# New version from live scope (→ v3)
aui version create --source agent-scope

# Import a specific version for editing
aui import-agent --version <version-id>

Project Structure

After aui import-agent, your project folder contains:

my-agent/
│
├── agent.aui.json                 # Agent identity and behavior
├── parameters.aui.json            # Parameters (input/output data)
├── entities.aui.json              # Entity groups
├── integrations.aui.json          # API / RAG / MCP connections
├── rules.aui.json                 # Global behavioral rules
├── widgets.aui.json               # Card templates (JSX + field mappings)
│
├── tools/                         # One file per agent tool/capability
│   ├── product_search.aui.json
│   ├── generative_ai.aui.json
│   └── ...
│
├── knowledge-hubs/                # Knowledge base data
│   ├── policies/
│   │   ├── kb.json                #   KB metadata
│   │   └── company-policies.pdf   #   Downloaded files
│   └── ...
│
├── schemas/                       # Domain schemas (auto-fetched)
│   ├── agent.dschema.json
│   ├── tools.dschema.json
│   ├── parameters.dschema.json
│   ├── entities.dschema.json
│   ├── integrations.dschema.json
│   ├── rules.dschema.json
│   ├── widgets.dschema.json
│   └── knowledge-bases.dschema.json
│
├── memory/                        # Push logs (auto-generated)
├── .auirc                         # Project config (agent ID, version, env)
├── .vscode/settings.json          # Schema autocomplete for VS Code / Cursor
├── .gitignore
│
├── GUIDE.md                       # Getting started guide
├── AGENTS.md                      # Agent documentation
│
├── .cursor/skills/                # Cursor skills per config type
├── .claude/skills/                # Claude Code skills per config type
└── .opencode/skills/              # OpenCode skills per config type

Configuration File Reference

agent.aui.json

The agent's identity and top-level behavior:

{
  "general_settings": {
    "name": "Support Agent",
    "objective": "Help customers find products and resolve issues",
    "persona_guidelines": "You are a friendly and knowledgeable support agent...",
    "tone_of_voice": "Professional but approachable",
    "guardrails": "Never share internal pricing. Always verify identity...",
    "brevity": "concise",
    "context": "This agent serves an e-commerce platform..."
  }
}

parameters.aui.json

Parameters the agent collects from users or outputs:

{
  "parameters": [
    {
      "code": "product-type",
      "description": "The type of product the customer is looking for",
      "type": "string",
      "usage": "ALL"
    },
    {
      "code": "budget-range",
      "description": "Customer's budget",
      "type": "enum",
      "usage": "INPUT",
      "values": ["under-50", "50-100", "100-200", "200-plus"]
    }
  ]
}

tools/*.aui.json

Each tool defines a capability with triggers, parameters, integrations, and rules:

{
  "tool": {
    "name": "Product Search",
    "code": "PRODUCT_SEARCH",
    "goal": "Help the user find products that match their preferences",
    "when_to_use": "When the user asks to browse, search, or find products",
    "status": true,
    "response_type": "TEXT_CARDS",
    "config": {
      "params": {
        "required": [["product-type"]],
        "optional": ["budget-range", "color", "size"]
      }
    },
    "integrations": [
      { "code": "product-api", "is_main": true }
    ],
    "card_template_code": "product-card"
  }
}

widgets.aui.json

Card templates with JSX and field mappings:

{
  "widgets": [
    {
      "name": "product-card",
      "jsx_template": "<Card><Image src={image} /><Text value={title} /></Card>",
      "fields": [
        { "name": "image", "param": "product-image" },
        { "name": "title", "param": "product-name" }
      ],
      "tool_name": "PRODUCT_SEARCH"
    }
  ]
}

Version Management

How Versioning Works

Pushing is only allowed to draft versions. The CLI will never auto-create drafts during push — you must create one explicitly first.

Create a draft version using aui version create
Import the draft to get local files: aui import-agent --version <draft-id>
Edit the local .aui.json files
Push changes into the draft (the CLI validates the target is a draft)
Publish to lock the draft permanently
Activate to make it the live configuration

aui version create        # Create draft v2 (always bumps version number)
aui import-agent --version <draft-id>  # Get the draft as local files
# Edit files...
aui push                  # Pushes into the draft (rejects if not a draft)
aui version publish       # Locks v2
aui version activate      # v2 is now live

Push Flow (detailed)

When you run aui push, the following happens:

Draft validation — The CLI checks that the target version is a draft. If the version in .auirc or --version-id is not a draft (e.g. published, archived), push is rejected with a descriptive error and next steps.
Entity push (Step A) — The CLI pushes individual entity changes (parameters, tools, integrations, etc.) to the agent-settings API. Each task is tracked with success/failure, and the flow continues even when some entities fail.
Snapshot push (Step B — last step) — After entity push completes, the CLI uploads the local file state as a snapshot to the server. This always runs regardless of entity-push outcomes, because files are the source of truth — the snapshot preserves your local state even if some DB updates failed. Version tag is bumped automatically on the server when the snapshot succeeds (e.g. v3.2 → v3.3).
Baseline update — Local git baseline is committed only if the snapshot succeeded. Within that, only files whose entity-push succeeded are added to the baseline.

Why snapshot-last?

The snapshot is meant to reflect what's actually been applied to the agent. Putting it after the entity push means:

Snapshot ≈ DB state — the IA/AI tooling can rely on the snapshot files as the source of truth without ever hitting the entity DB
Auto-bump represents real updates — v{N}.X only increments when a push attempt actually completed
File-level rejections are caught locally by aui validate (schema + cross-ref checks) before push, so server-side snapshot validation rarely fails
Partial DB failures are tolerable — the snapshot still uploads, preserving file history. Re-running aui push retries the failed entities (PATCHes are idempotent)

Failure scenarios

| What failed | What happens | Next step | |-------------|--------------|-----------| | Entity push partial | Snapshot still uploads (captures file state). Baseline committed only for succeeded files. | Re-run aui push to retry failed entity updates. | | Snapshot fails after entity push succeeded | Baseline is not updated. Entity changes already in DB. | Re-run aui push. Entities will re-PATCH (idempotent), then snapshot retries. | | Both fail | Baseline unchanged. | Fix issues from error output, re-run aui push. |

If push partially fails, it's the user's responsibility to re-run aui push to retry. The CLI shows descriptive errors with "What to do next" guidance for every failure mode.

Version Numbering

Versions use simple incrementing numbers: v1, v2, v3, etc. There are no revision/minor numbers.

Use --source version --from <id> to clone from an existing version
Use --source agent-scope for a new version from the current live scope

Knowledge Bases

Everything below runs through the single aui rag command — either via its interactive menu (aui rag) or the action flags.

Upload Documents & URLs

aui rag --add-file    # Pick a KB, then upload local files or scrape web pages
aui rag               # Or use the menu → "Upload files…" / "Upload URLs…"

Check Indexing Status

aui rag --status      # Per-resource status (completed / failed / in-progress) for each KB

List, Export & Import

aui rag               # Menu → "List knowledge bases"
aui rag               # Menu → "Export to knowledge-hubs/"  (saves KB metadata + files locally)
aui rag               # Menu → "Import from knowledge-hubs/" (restores KBs from the local folder)

CI/CD & Automation

Every command supports non-interactive flags for pipeline integration.

Environment Variables for CI

export AUI_AUTH_TOKEN="<jwt-token>"
export AUI_ENVIRONMENT="production"
export AUI_ACCOUNT_ID="<account-id>"
export AUI_ORGANIZATION_ID="<org-id>"

Example Pipeline

# Login with token
aui login --token "$AUI_AUTH_TOKEN" --environment production

# Import, validate, push
aui import-agent <agent-id> --dir ./agent-config
cd ./agent-config
aui validate --strict
aui push

# Publish and activate
aui version publish
aui version activate

All Environment Variables

| Variable | Description | |----------|-------------| | AUI_AUTH_TOKEN | Auth token (skip interactive login) | | AUI_API_URL | Override API base URL | | AUI_ENVIRONMENT | staging, custom, production, or eu-production | | AUI_ACCOUNT_ID | Account ID | | AUI_ORGANIZATION_ID | Organization ID | | AUI_KBM_API_KEY | RAG API key | | AUI_API_WORKFLOW_KEY | API Workflow key | | AUI_AGENT_CODE | Override the agent code resolved from .auirc | | AUI_DEBUG | Enable verbose debug logging (AUI_DEBUG=1) | | AUI_AUTO_IMPORT | Force (1) or disable (0) the auto-import + subshell after aui agents --create | | AUI_FORCE_AGENT_MODE | Force storage mode for push/pull/import/version (bundle or records) | | AUI_FETCH_TIMEOUT_MS | Per-request fetch timeout in ms (default 60000; 0 disables) | | AUI_NO_UPDATE_CHECK | Disable the background update-check / notification banner | | AUI_DISABLE_TELEMETRY / AUI_TELEMETRY=0 | Opt out of OpenTelemetry tracing | | AUI_NO_AGENT_INJECTION | Suppress the "For Coding Agents" guidance block | | AUI_HOME | Override the config directory (default ~/.aui) |

Configuration

Global Config Files

| File | Purpose | |------|---------| | ~/.aui/session.json | Auth token, org, account, agent, environment | | ~/.aui/environment | Selected environment | | ~/.aui/kbm-key | RAG API key | | ~/.aui/api-workflow-key | API Workflow key |

Project Config (.auirc)

Created during import, stored in the project root:

{
  "agent_code": "support-agent",
  "agent_id": "69cd0a61b6924d36aafaf3f6",
  "environment": "custom",
  "account_id": "69c919bcb506d3e323e0397e",
  "organization_id": "68c004560ed54fdf78c551d1",
  "network_category_id": "69b2e9385d33a2096c543294",
  "version_id": "69cd0ca8168d739104520c60",
  "version_label": "v1.2"
}

Environments

aui env                   # Show current
aui env staging           # Switch to staging
aui env custom            # Switch to custom (v3 endpoints)
aui env production        # Switch to production
aui env eu-production     # Switch to EU production
aui login --environment staging  # Set during login

Troubleshooting

Enable Debug Logging

AUI_DEBUG=1 aui push
AUI_DEBUG=1 aui import-agent <id>

Debug mode logs every API request URL, response status, and body.

Common Issues

| Issue | Solution | |-------|---------| | Not logged in | Run aui login | | Missing network_category_id | Re-import the agent: aui import-agent | | Version not found | Run aui version list to see available versions | | Version not found (id looks truncated) | The human version list table abbreviates IDs. Scrape IDs from aui version list --json | | Could not resolve the agent for this project (.auirc) | Pass aui version … --agent-id <agent-management-id>, or re-run aui import / aui pull to refresh .auirc | | version create made a draft on the wrong agent | Fixed — version now targets the project's .auirc agent (or --agent-id), not the session's "current" agent | | 422 with no detail | The CLI now surfaces the API's validation detail in the error message. Re-run; for full bodies use AUI_DEBUG=1 | | 422 on push | Check aui validate --strict for schema errors. Review .aui/push-logs/ for API details | | No changes detected | The push baseline matches your files. Make an edit and try again | | Agent settings 401/403 | Your session is invalid or lacks permission. Run aui login --environment <custom\|production> to re-authenticate | | README not showing on npm | Ensure README.md is at the package root before npm publish |

Push Logs

Every push saves detailed API call logs:

.aui/push-logs/
├── POST-tool-product_search.txt
├── PATCH-param-budget-range.txt
└── ...

Push Memory

Push results are saved as markdown for reference:

memory/
└── push-2026-04-01T12-16-41-772Z.md

Local Development

git clone <repo-url>
cd aui-agent-builder
npm install
npm run build
npm link              # Makes `aui` available globally from source

npm run watch         # Recompile on file changes
npm test              # Run tests

Updating

aui upgrade                          # Auto-detect npm or Homebrew
npm install -g aui-agent-builder     # Manual npm
brew update ; brew upgrade aui-io/homebrew-tap/aui    # Manual Homebrew

The CLI checks for updates at most once per hour and shows a notification banner when a new version is available.

Architecture & Developer Context

This section provides context for developers (and AI assistants) working on the CLI codebase.

Project Structure (source)

aui-agent-builder/
├── bin/aui.js                    # Executable shim → dist/index.js
├── src/
│   ├── index.ts                  # CLI entry — Commander program, all command wiring
│   ├── telemetry.ts              # OpenTelemetry tracing (Logfire)
│   ├── commands/                 # One file per command
│   │   ├── push.tsx              # Push flow (snapshot → entity push → bump)
│   │   ├── version.tsx           # Version lifecycle (create, publish, activate, archive)
│   │   ├── agents.tsx            # Agent management (create, list, switch, import)
│   │   ├── import-agent.tsx      # Import agent as local .aui.json files
│   │   ├── pull-agent.tsx        # Pull latest from backend
│   │   ├── login.tsx             # Authentication flow
│   │   └── ...                   # Other commands
│   ├── api-client/
│   │   ├── index.ts              # AUIClient — all HTTP calls to backend
│   │   ├── kb-view-client.ts     # Knowledge base API client
│   │   └── rag-client.ts         # RAG API client
│   ├── config/
│   │   └── index.ts              # Config resolution (env → .auirc → session → defaults)
│   ├── errors/
│   │   └── index.ts              # Structured error types (AuthError, ConfigError, etc.)
│   ├── services/                 # Business logic services
│   ├── types/                    # TypeScript interfaces for local agent files
│   ├── ui/                       # Ink components and views
│   │   ├── components/           # Reusable UI atoms (Spinner, StatusLine, etc.)
│   │   ├── views/                # Command-specific views (PushView, etc.)
│   │   └── theme.ts              # Colors, icons, labels
│   └── utils/                    # Git, JSON output, schema improvements
└── package.json

Key Patterns

Commander for CLI argument parsing, Ink + React for terminal UI
AUIClient in api-client/index.ts is the single HTTP layer; all API calls go through it
Two API surfaces: Agent Management (versions lifecycle) and Agent Settings (entity CRUD for push)
Config resolution: getConfig() merges env vars → .auirc → ~/.aui/session.json → defaults
Git baseline: Push uses an internal git repo to track diffs between pushes

Push Flow (current implementation)

Validate auth and project config
Read local .aui.json files
Git diff to detect changes since last push
Draft validation: Verify the target version is a draft (reject otherwise)
Entity push: PATCH/POST/DELETE individual entities (parameters, tools, integrations, rules, etc.) — track per-task success, continue on failures
Snapshot push (last step): Multipart POST of all local files to /v1/agents/{agentId}/versions/{versionId}/snapshot
- Uses JWT auth (Bearer token)
- Runs regardless of entity-push outcomes (files = source of truth, DB = best effort)
- Version tag is bumped automatically on snapshot success (no separate bump endpoint)
- Snapshot tags follow the pattern v{N}.0, v{N}.1, v{N}.2, ... where N is the version number; the first push to a version creates .0
- Implemented in: pushSnapshot() in src/commands/push.tsx + client.agentManagement.pushSnapshot() in src/api-client/index.ts
Baseline update: Git baseline is committed only when the snapshot succeeded. Within that, only files whose entity-push succeeded are added.

Snapshot Endpoints

POST /v1/agents/{agentId}/versions/{versionId}/snapshot — Upload local files as multipart form data. Version tag bumps automatically on success.
GET /v1/agents/{agentId}/versions/{versionId}/snapshot?version_tag=v1.0&expires_in=15 — Retrieve a specific snapshot's manifest + signed download URLs (15-minute expiry).

Snapshot Browsing (CLI)

| Command | Purpose | |---------|---------| | aui version snapshot | Interactive menu (list / get / diff) | | aui version snapshot list | List all snapshots for the current version | | aui version snapshot get <tag> | Show snapshot manifest + signed URLs | | aui version snapshot diff <a> <b> | File-level diff (SHA-256 + size) | | aui version snapshot diff <a> <b> --full | Field-level JSON diff (downloads files) |

All snapshot commands support --agent-id, --version-id, and --json for scripting.

Version Numbering

Versions use simple incrementing numbers (v1, v2, v3). No revision/minor numbers. The bump_mode parameter in CreateDraftRequest is always set to "version_number".

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

AUI Agent Builder CLI

Features

Table of Contents

Installation

Quick Start

Core Concepts

Hierarchy

Agent Configuration

Version Lifecycle

Commands Reference

Discovering commands

Authentication

Agent Management

Import & Pull

Push

Version Management

Knowledge Bases & Documents

Development Tools

Integrations

Chat & Testing

Runtime Messaging — Apollo

Configuration & Utilities

Session Sync

Inspecting HTTP requests — aui curl

Reporting issues — aui report (BETA)

Command Aliases

Workflows

Create and Deploy a New Agent

Edit → Push → Deploy Cycle

Version Branching

Project Structure

Configuration File Reference

agent.aui.json

parameters.aui.json

tools/*.aui.json

widgets.aui.json

Version Management

How Versioning Works

Push Flow (detailed)

Why snapshot-last?

Failure scenarios

Version Numbering

Knowledge Bases

Upload Documents & URLs

Check Indexing Status

List, Export & Import

CI/CD & Automation

Environment Variables for CI

Example Pipeline

All Environment Variables

Configuration

Global Config Files

Project Config (.auirc)

Environments

Troubleshooting

Enable Debug Logging

Common Issues

Push Logs

Push Memory

Local Development

Updating

Architecture & Developer Context

Project Structure (source)

Key Patterns

Push Flow (current implementation)

Snapshot Endpoints

Snapshot Browsing (CLI)

Version Numbering

License

Inspecting HTTP requests — `aui curl`

Reporting issues — `aui report` (BETA)