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

Table of Contents

• Installation
• Quick Start
• Core Concepts
• Commands Reference
• Workflows
• Project Structure
• Configuration File Reference
• Version Management
• Scope Levels
• Knowledge Bases
• CI/CD & Automation
• Configuration
• Troubleshooting
• Local Development

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

Authentication

aui login                        # Open browser for authentication
aui login --environment staging  # Login to a specific environment
aui login --token <jwt>          # Login with a JWT token (for CI/CD)
aui logout                       # Clear session and credentials

Agent Management

aui agents                       # Interactive menu: list, create, switch, import
aui agents --list                # List all agents in the current account
aui agents --create              # Interactive creation (org → account → name)
aui agents --switch              # Switch the active agent in your session

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

# Create + v1.0 draft (ready to import, edit, and push)
aui agents --create --name "My Agent" --account-id <id> --draft

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

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 --scope-level category   # Import at category scope
aui import-agent --dir ./my-folder        # Output to a specific directory
aui import-agent --skip-kb-files          # Skip knowledge base file downloads
aui import-agent --skills claude,cursor   # Generate AI coding skills
aui import-agent --no-skills             # Skip skill generation
aui import-agent --include-evaluate       # Include test_questions schema

aui pull                                  # Pull latest into existing project
aui pull --force                          # Skip overwrite confirmation
aui pull --scope-level <level>            # Pull at a specific scope level

Push

aui push                                  # Push changes (auto-creates version draft)
aui push --dry-run                        # Preview without pushing
aui push --scope-level category           # Push at a specific scope level
aui push --version-id <id>               # Push into a specific draft
aui push --force                          # Push even with validation errors
aui push --skip-validation                # Skip validation step
aui push --api-key <key>                 # Use a specific API key

Version Management

aui version                               # Interactive version menu
aui version list                          # List all versions
aui version list --base-only              # List base versions only (no revisions)
aui version list --version-number 3       # List all revisions of v3

# Create
aui version create                                        # Interactive
aui version create --source agent-scope                   # Major version from live (v2.0)
aui version create --source version --from <id>           # Revision (v1.0 → v1.1)
aui version create --source version --from <id> --bump version_number  # Major from clone

# Lifecycle
aui version publish                       # Interactive — select draft to publish
aui version publish <id>                  # Publish a specific draft
aui version activate                      # Interactive — select version to activate
aui version activate <id>                 # Activate a specific version
aui version archive <id>                  # Archive (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"

Knowledge Bases & Documents

# RAG management
aui rag                                   # Interactive KB menu
aui rag --list                            # List all knowledge bases
aui rag --export                          # Export KBs to knowledge-hubs/
aui rag --import                          # Import KBs from knowledge-hubs/

# Document upload
aui document report.pdf data.csv --kb "Policies"   # Upload files
aui document --url "https://docs.example.com" --kb "Docs"  # Scrape URLs
aui document status                                  # Recent upload status
aui document status --hours 24 --kb "Policies"       # Filtered status

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

Chat & Testing

aui chat                                  # Interactive conversation with agent
aui chat --api-key <key>                 # Chat with a specific API key
aui chat --rest                           # REST API only (no streaming)
aui serve                                 # Web chat playground (localhost:3141)
aui serve --port 8080                     # Custom port

Configuration & Utilities

aui account                               # Manage accounts (list, create, switch)
aui env                                   # Show current environment
aui env staging                           # Switch environment
aui pull-schema                           # Fetch domain schemas from backend
aui add-integration                       # Add API / RAG / MCP integration
aui upgrade                               # Update to latest version

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 |

Workflows

Create and Deploy a New Agent

# Step 1: Create the agent (with a v1.0 draft ready to edit)
aui agents --create --name "Support Agent" --account-id <id> --draft

# Step 2: Import as local files
aui import-agent

# Step 3: Edit configuration in your editor
cd ./support-agent
# → Edit agent.aui.json, tools/*.aui.json, parameters.aui.json, etc.

# Step 4: Validate and push
aui validate
aui push

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

Three creation modes:

# Agent only (no version) — create version manually later
aui agents --create --name "Support Agent" --account-id <id>

# Agent + v1.0 draft — ready to import, edit, and push
aui agents --create --name "Support Agent" --account-id <id> --draft

# 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

aui import-agent                  # Downloads active version as .aui.json files
cd ./my-agent

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

aui diff                          # See what changed
aui validate                      # Validate against schemas
aui push                          # Push changes into a new draft

aui version publish               # Lock the draft
aui version activate              # Make it live

Version Branching

# Create a revision from v1.0 (→ v1.1)
aui version create --source version --from <v1.0-id>

# Or create a new major version from live scope (→ v2.0)
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
├── BEST_PRACTICES.md              # Configuration best practices
│
├── .cursor/rules/                 # Cursor AI rules 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

1. Import downloads the active version's configuration as local files
2. Push auto-creates a draft version and pushes changes into it
3. Publish locks the draft permanently
4. Activate makes the published version the live configuration

aui import-agent          # Get active version (e.g. v1.0)
# Edit files...
aui push                  # Creates draft v1.1, pushes changes
aui version publish       # Locks v1.1
aui version activate      # v1.1 is now live

Version Numbering

• Revisions increment the minor number: v1.0 → v1.1 → v1.2
• Major versions increment the major number: v1.x → v2.0
• Use --source version --from <id> for revisions
• Use --source agent-scope for new major versions

Scope Levels

Scope levels control which hierarchy level you're reading from or writing to:

| Level | IDs Sent | Use Case | |-------|----------|----------| | network | network_id + account_id + org_id + category_id | Agent-specific configuration (default) | | account | account_id + org_id + category_id | Shared across all agents in an account | | organization | org_id + category_id | Shared across all accounts in an org | | category | category_id only | Shared across all agents in a category (e.g. Amazon) |

aui import-agent --scope-level category <agent-id>
aui push --scope-level category

Note: Scope-level operations skip versioning. Changes are applied directly to the live scope.

Knowledge Bases

Upload Documents

# Upload files
aui document report.pdf handbook.docx --kb "Company Policies"

# Scrape web pages
aui document --url "https://docs.example.com/faq" --kb "FAQ"

Check Upload Status

aui document status                        # Last 6 hours
aui document status --hours 24             # Last 24 hours
aui document status --kb "Company Policies"  # Filter by KB

Export & Import

aui rag --export    # Save all KB metadata and files to knowledge-hubs/
aui rag --import    # Restore KBs from knowledge-hubs/

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, or production | | AUI_ACCOUNT_ID | Account ID | | AUI_ORGANIZATION_ID | Organization ID | | AUI_KBM_API_KEY | RAG API key | | AUI_AGENT_TOOLS_API_KEY | Agent Settings API key | | AUI_API_WORKFLOW_KEY | API Workflow key | | AUI_DEBUG | Enable verbose debug logging (AUI_DEBUG=1) |

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/agent-settings-key | Agent Settings API key (fallback) | | ~/.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 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 | | 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 | Provide an API key: aui push --api-key <key> | | 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 upgrade aui                     # Manual Homebrew

The CLI checks for updates every 24 hours and shows a notification banner when a new version is available.

License

Proprietary — Copyright (c) 2026 AUI. All rights reserved. See LICENSE.