> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aui.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`

<Note>
  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.
</Note>

## Install

```bash theme={"dark"}
npm install -g aui-agent-builder
```

Verify the installation:

```bash theme={"dark"}
aui --version
```

<Info>
  Already installed? Update to the latest version at any time with `aui upgrade`.
</Info>

## Authentication

Authenticate with the `--environment` option:

```bash theme={"dark"}
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**.

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

## Post-Login Setup

<Steps>
  <Step title="Verify your session">
    ```bash theme={"dark"}
    aui status
    ```

    You should see your account info, active agent, and current environment.
  </Step>

  <Step title="Set your environment">
    ```bash theme={"dark"}
    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`.
  </Step>

  <Step title="Create or import an agent">
    ```bash theme={"dark"}
    # Create a brand-new agent (provisioned end-to-end, then imported locally)
    aui agent --create

    # Or import an existing agent
    aui import-agent
    ```
  </Step>
</Steps>

<Note>
  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.
</Note>

## Uninstall

```bash theme={"dark"}
npm uninstall -g aui-agent-builder
```

To remove stored credentials and session data:

```bash theme={"dark"}
rm -rf ~/.aui
```

<Warning>
  This removes all stored sessions, API keys, and cached schemas. You'll need to run `aui login` again.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Command Reference" icon="terminal" href="/cli/commands">
    Full reference for all CLI commands.
  </Card>

  <Card title="Configuration" icon="gear" href="/cli/configuration">
    Project structure, config files, and environment variables.
  </Card>
</CardGroup>