Installation

Install the AUI Agent Builder CLI and authenticate with your account.

System Requirements

Before installing the CLI, make sure the following are installed on your machine:

• Node.js 18 or later
• npm (included with Node.js)
• Git — the CLI relies on Git (for example, for change detection in aui push and aui diff), so it must be installed and available on your PATH

Both Node.js and Git are required. Install them first — npm install -g aui-agent-builder needs Node.js/npm, and the CLI will not function correctly without Git available.

Install

npm install -g aui-agent-builder

Verify the installation:

aui --version

Already installed? Update to the latest version at any time with aui upgrade.

Authentication

Authenticate with the --environment option:

aui login --environment staging        # Development and testing
aui login --environment production     # Live environment (default)
aui login --environment eu-production  # EU-hosted production
aui login --environment custom         # Custom environment

This opens the AUI playground in your browser; sign in and you’re redirected back automatically.

After authenticating, the CLI walks you through selecting your Organization, Account, and Agent.

Session credentials are stored in ~/.aui/session.json. They persist across terminal sessions.

Post-Login Setup

1. Verify your session

   aui status
   

   You should see your account info, active agent, and current environment.

2. Set your environment

   aui env staging        # Development and testing
   aui env production      # Live environment (default)
   aui env eu-production   # EU-hosted production
   aui env custom          # Custom environment
   

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

3. Create or import an agent

   # Create a brand-new agent (provisioned end-to-end, then imported locally)
   aui agent --create
   
   # Or import an existing agent
   aui import-agent
   

Imported an agent that lives in a different organization than your login default? Run aui sync-session to re-scope your session to the project’s .auirc so every command works. The CLI also runs this reconciliation automatically before most commands.

Uninstall

npm uninstall -g aui-agent-builder

To remove stored credentials and session data:

rm -rf ~/.aui

This removes all stored sessions, API keys, and cached schemas. You’ll need to run aui login again.

Next Steps

Command Reference

Full reference for all CLI commands.

Configuration

Project structure, config files, and environment variables.