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
• 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, delete
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
aui agents --delete              # Interactive: org → account → agent → choose scope (whole / one version / all versions)

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

Interactive flow:

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

1. Select organization
2. Select account
3. Select agent (with the active version surfaced inline)
4. 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 --scope-level category   # Import at category scope
aui import-agent --dir ./my-folder        # Output to a specific directory
aui import-agent --with-kb-files          # Also download original KB binaries (skipped by default)
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

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 --version-id <id>               # Push into a specific draft (must be a 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

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

# Create (always bumps version number: v1, v2, v3, ...)
aui version create                                        # Interactive
aui version create --source agent-scope                   # New version from live scope
aui version create --source version --from <id>           # Clone from existing version

# 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

Integrations

aui integration                   # Interactive menu — Create or Discover
aui integration create            # Guided flow — org, account, agent, Manual or Native MCP
aui integration discover          # Guided MCP tool discovery

Non-interactive — Manual MCP:

aui integration create --name "My MCP" --url <url> --all-tools
aui integration create --name "My MCP" --url <url> --tools tool1,tool2
aui integration create --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>

Non-interactive — Native MCP:

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

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 |

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 (legacy)
aui integration create                    # Create MCP integration (Manual or Native)
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 | | aui integrations | aui integration |

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

# 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
├── 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

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

1. Create a draft version using aui version create
2. Import the draft to get local files: aui import-agent --version <draft-id>
3. Edit the local .aui.json files
4. Push changes into the draft (the CLI validates the target is a draft)
5. Publish to lock the draft permanently
6. 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:

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

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

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

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

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.

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)

1. Validate auth and project config
2. Read local .aui.json files
3. Git diff to detect changes since last push
4. Draft validation: Verify the target version is a draft (reject otherwise)
5. Entity push: PATCH/POST/DELETE individual entities (parameters, tools, integrations, rules, etc.) — track per-task success, continue on failures
6. 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
7. 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".

License

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