Workflows

Common development workflows, chat commands, and best practices for the AUI Agent Builder CLI.

Import and Edit an Existing Agent

The most common workflow: pull an agent from the cloud, edit it locally, validate, and push back.

# Login and select your org/account/agent
aui login

# Import the agent configuration locally
aui import-agent

# Open the directory in your IDE
cd my-agent
code .    # or: cursor .

# Edit any .aui.json file — you get schema autocomplete in VSCode/Cursor

# Validate your changes
aui validate

# See what changed
aui diff

# Push to the cloud
aui push

After importing, your IDE gets automatic JSON schema autocomplete for all .aui.json files. No additional setup required in VSCode or Cursor.

---

Create a New Agent from Scratch

Scaffold a blank agent project and build it up step by step.

# Login first
aui login

# Scaffold a new agent project
aui create-agent ./my-new-agent
cd my-new-agent

# Follow GUIDE.md for step-by-step instructions
# Edit the .aui.json files

# Validate and push
aui validate
aui push

The generated GUIDE.md walks you through configuring each file in order.

---

Validate and Push Changes

Always validate before pushing. Use --dry-run to preview.

# Validate all project files
aui validate

# Preview what will be pushed
aui push --dry-run

# Push changes
aui push

# Force push everything (not just diffs)
aui push --force

aui push --force sends all files, not just changed ones. Use it when you want to ensure the remote matches your local state exactly.

---

Switch Between Environments

Test on staging before deploying to production.

# Work on staging
aui env staging
aui import-agent
# ... make changes ...
aui validate
aui push

# When ready, switch to production
aui env production
aui push

---

CI/CD Integration

Use environment variables to skip interactive login in CI pipelines.

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

# Validate and push
aui validate
aui push

Or use API key authentication:

aui login --api-key <key> --account-id <id>
aui push

---

Chat Commands

When inside aui chat, the following commands are available:

Command	Description
/exit	Exit the chat session
/clear	Clear conversation history
/history	Show conversation history
/suggest	Get AI-generated follow-up suggestions
/task	Manage tasks
/help	Show available chat commands

Start a chat session:

aui chat                  # WebSocket streaming (default)
aui chat --rest           # REST API fallback
aui chat --user-id u123   # Custom user ID

Features:

• Real-time streaming via WebSocket
• Inline product cards with images
• AI-generated follow-up suggestions

---

Next Steps

Command Reference

Full reference for all CLI commands.

Configuration

Project structure, config files, and environment variables.