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

# Configuration

> Project structure, config files, and environment variables for the AUI Agent Builder CLI.

## Project Structure

After running `aui import-agent` or `aui agent --create`, your project directory looks like this:

```
my-agent/
├── agent.aui.json              # Agent identity, objective, guardrails, tone
├── parameters.aui.json         # Data units (input/output definitions)
├── entities.aui.json           # Groups of related parameters (the ontology)
├── integrations.aui.json       # API, RAG, and MCP connections
├── rules.aui.json              # Global behavioral rules
├── tools/                      # Agent capabilities (one file per tool)
│   ├── product_search.aui.json
│   └── generative_ai.aui.json
├── scenarios/                  # Evaluation scenarios and scores
│   ├── scenarios.aui.json
│   ├── scenarios-scores.aui.json
│   └── intent/                 # Raw intent files, docs, sample data
├── traces/                     # Saved interaction traces (aui apollo trace)
├── GUIDE.md                    # Step-by-step building guide
├── .auirc                      # Project config (agent, version, account, env)
├── .aui-schema/                # JSON schemas for validation
│   └── aui.dschema.json
├── .vscode/
│   └── settings.json           # Schema autocomplete for VSCode/Cursor
└── .cursor/ · .claude/ · .opencode/   # Coding-agent skills (generated on import)
```

### File Reference

| File                    | Purpose                                                                            |
| ----------------------- | ---------------------------------------------------------------------------------- |
| `agent.aui.json`        | Core agent configuration — name, objective, personality, guardrails, tone of voice |
| `parameters.aui.json`   | Defines data units the agent collects or outputs                                   |
| `entities.aui.json`     | Groups related parameters into logical entities (the agent's ontology)             |
| `integrations.aui.json` | External connections — APIs, RAG knowledge bases, MCP servers                      |
| `rules.aui.json`        | Global behavioral rules that govern agent behavior                                 |
| `tools/*.aui.json`      | Individual tool definitions — each tool is a separate file                         |
| `scenarios/`            | Evaluation scenarios and recorded scores (managed by `aui scenarios`)              |
| `GUIDE.md`              | Auto-generated step-by-step building guide                                         |
| `.auirc`                | Project-level config linking to your account, agent, and version                   |
| `.aui-schema/`          | JSON schemas for local validation and editor autocomplete                          |

<Info>
  VSCode and Cursor get automatic JSON schema autocomplete for `.aui.json` files via the `.vscode/settings.json` generated during import. Coding-agent skill folders (`.cursor/`, `.claude/`, `.opencode/`) are also generated so agents like Cursor and Claude Code understand how to build AUI agents. Skip them with `--no-skills`.
</Info>

***

## Session

Stored at `~/.aui/session.json` after login. Contains:

* Auth token (JWT) and refresh token
* User info (ID, email, name)
* Organization ID and name
* Account ID and name
* Agent ID and name
* Environment and API URL
* Token expiry timestamp

<Warning>
  Do not commit `~/.aui/` to version control. It contains authentication tokens and API keys.
</Warning>

***

## Project Config (.auirc)

Created in your project directory by `aui import-agent` or `aui agent --create`. It links your local project to a specific agent **and version** on the AUI platform:

```json .auirc theme={"dark"}
{
  "agent_code": "my_agent",
  "agent_id": "abc123",
  "agent_management_id": "am_abc123",
  "version_id": "ver_abc123",
  "version_tag": "v3.2",
  "environment": "staging",
  "account_id": "...",
  "organization_id": "...",
  "network_category_id": "...",
  "network_api_key": "..."
}
```

<Info>
  Commands like `push`, `pull`, `apollo`, `version`, and `scenarios` read their target from `.auirc`. If your session is scoped to a different organization than the project, run `aui sync-session` (the CLI also does this automatically before most commands).
</Info>

***

## Environment Variables

Environment variables override file-based configuration. Useful for CI/CD pipelines.

| Variable                  | Description                                                          |
| ------------------------- | -------------------------------------------------------------------- |
| `AUI_AUTH_TOKEN`          | Skip login — use this JWT directly                                   |
| `AUI_API_URL`             | Override API base URL                                                |
| `AUI_ENVIRONMENT`         | Set environment (`staging`, `custom`, `production`, `eu-production`) |
| `AUI_ACCOUNT_ID`          | Account ID                                                           |
| `AUI_ORGANIZATION_ID`     | Organization ID                                                      |
| `AUI_AGENT_CODE`          | Agent code                                                           |
| `AUI_KBM_API_KEY`         | RAG knowledge base API key                                           |
| `AUI_AGENT_TOOLS_API_KEY` | Agent Settings API key                                               |
| `AUI_API_WORKFLOW_KEY`    | API Workflow key                                                     |

```bash theme={"dark"}
# Example: run a command against production without switching env
AUI_ENVIRONMENT=production aui list-agents
```

***

## Secure Key Files

Additional credentials are stored as secure files (mode 600) in `~/.aui/`:

| File                        | Purpose                |
| --------------------------- | ---------------------- |
| `~/.aui/kbm-key`            | RAG API key            |
| `~/.aui/agent-settings-key` | Agent Settings API key |
| `~/.aui/api-workflow-key`   | API Workflow key       |

Mock DB runtime and management keys are stored per-agent when you run `aui mockdb provision`. Inspect their prefixes (never the secrets) with `aui mockdb keys`.

***

## Environments

AUI supports the following environments:

| Environment     | Description                           |
| --------------- | ------------------------------------- |
| `staging`       | Development and testing               |
| `production`    | Live production environment (default) |
| `eu-production` | EU-hosted production                  |
| `custom`        | Custom environment                    |

Switch environments:

```bash theme={"dark"}
aui env staging
aui env production
aui env eu-production
aui env custom
```

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

## Next Steps

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

  <Card title="Workflows" icon="route" href="/cli/workflows">
    Common development workflows and patterns.
  </Card>
</CardGroup>