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

# CLI Reference

> Complete command-line interface reference for GAIA with examples and options

<Info>
  **Source Code:** [`src/gaia/cli.py`](https://github.com/amd/gaia/blob/main/src/gaia/cli.py)
</Info>

GAIA provides a comprehensive command-line interface (CLI) for interacting with AI models and agents. The CLI allows you to query models directly, manage chat sessions, and access various utilities without writing code.

## Platform Support

<CardGroup cols={2}>
  <Card title="Windows 11" icon="windows">
    Full GUI and CLI support
  </Card>

  <Card title="Linux" icon="linux">
    Full GUI and CLI support via source installation (Ubuntu/Debian)
  </Card>
</CardGroup>

## Quick Start

<Tabs>
  <Tab title="Windows">
    1. Follow the [Quickstart](/docs/quickstart) to install GAIA
    2. Open PowerShell and run `gaia` to launch the Agent UI, or `gaia --cli` for terminal chat
    3. GAIA automatically starts Lemonade Server when needed, or start manually:

    ```bash theme={null}
    lemonade-server serve
    ```
  </Tab>

  <Tab title="Linux">
    1. Install from source: Follow [Linux Installation](/docs/quickstart)
    2. Install Lemonade Server from [lemonade-server.ai](https://www.lemonade-server.ai)
    3. Start the server:

    ```bash theme={null}
    lemonade-server serve
    ```

    4. Verify installation:

    ```bash theme={null}
    gaia -v
    gaia llm "Hello, world!"
    ```
  </Tab>
</Tabs>

***

## Top-Level Flags

Running `gaia` with no subcommand launches the **Agent UI** by default:

```bash theme={null}
gaia            # Launches Agent UI on port 4200
gaia --ui       # Same — explicit flag
gaia --cli      # Launch interactive CLI chat instead
```

| Flag               | Description                                                                                                                                              |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--ui`             | Launch the Agent UI (browser-based chat interface) — this is the default                                                                                 |
| `--ui-port <port>` | Port for the Agent UI server (default: 4200)                                                                                                             |
| `--ui-dist <path>` | Serve an alternative prebuilt Agent UI bundle (e.g., a PR preview) instead of the one shipped in the installed package                                   |
| `--cli`            | Launch interactive CLI chat                                                                                                                              |
| `--base-url <url>` | Use a remote Lemonade server (e.g. `https://host:13305/api/v1`). Also accepted as a global option on most subcommands (e.g. `gaia chat --base-url ...`). |

**Examples:**

<CodeGroup>
  ```bash Launch Agent UI (default) theme={null}
  gaia
  ```

  ```bash Agent UI on Custom Port theme={null}
  gaia --ui-port 8080
  ```

  ```bash Launch CLI Chat theme={null}
  gaia --cli
  ```

  ```bash Remote Lemonade Server theme={null}
  gaia --ui --base-url https://your-server:13305/api/v1
  ```
</CodeGroup>

<Note>
  `gaia chat --ui` continues to work as an alias. The Agent UI requires an AMD Ryzen AI Max (Strix Halo) or an AMD Radeon GPU with ≥ 24 GB VRAM. If your device is not supported, a dismissible warning banner will appear in the UI.
</Note>

### Agent step limit

Agents stop after a maximum number of reasoning/tool steps. The default is **50**, applied consistently across the CLI, the Agent UI, and background runs.

* **Per-invocation:** pass `--max-steps <n>` to any agent command (e.g. `gaia browse --max-steps 80`). `gaia blender` uses `--steps <n>`.
* **Fleet-wide:** set the `GAIA_AGENT_MAX_STEPS` environment variable to change the default for every agent at once, without per-command flags.

```bash theme={null}
# Raise the limit for every agent in this shell
export GAIA_AGENT_MAX_STEPS=80
gaia browse "research the latest AMD Ryzen AI news"
```

A few agents intentionally override the default (e.g. the Code agent uses 100 for multi-file generation). An invalid `GAIA_AGENT_MAX_STEPS` value (non-integer or ≤ 0) fails fast with an actionable error rather than silently capping agents.

### Per-tool execution timeout

Each tool call is bounded so a hung tool (e.g. a stuck connector or network request) surfaces an actionable error instead of leaving the agent — and the UI — stuck indefinitely. The default is **180 seconds** per tool.

* **Fleet-wide:** set `GAIA_AGENT_TOOL_TIMEOUT` (seconds) to change the default for every tool at once.

```bash theme={null}
# Allow long-running tools more headroom in this shell
export GAIA_AGENT_TOOL_TIMEOUT=300
```

Tools that legitimately run longer opt out in code via `@tool(timeout=...)` — for example image generation, which may need to download a model on first use. An invalid `GAIA_AGENT_TOOL_TIMEOUT` value (non-numeric or ≤ 0) fails fast with an actionable error rather than silently removing the guard.

***

## Initialization

### Init Command

<Note>
  **New users start here!** The `gaia init` command is the easiest way to get GAIA running.
</Note>

Initialize GAIA with a single command: installs Lemonade Server and downloads required models.

<video controls autoPlay loop muted playsInline className="w-full rounded-lg" src="https://assets.amd-gaia.ai/videos/gaia-init.webm" />

```bash theme={null}
gaia init [OPTIONS]
```

**Options:**

| Option              | Type   | Default | Description                                                                                                                                           |
| ------------------- | ------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--profile, -p`     | string | chat    | Profile to initialize (minimal, sd, chat, code, rag, mcp, vlm, email, npu, all)                                                                       |
| `--minimal`         | flag   | false   | Shortcut for `--profile minimal`                                                                                                                      |
| `--skip-models`     | flag   | false   | Skip model downloads (only install Lemonade)                                                                                                          |
| `--skip-lemonade`   | flag   | false   | Skip Lemonade installation check (for CI with pre-installed Lemonade)                                                                                 |
| `--force-reinstall` | flag   | false   | Force reinstall even if compatible version exists                                                                                                     |
| `--force-models`    | flag   | false   | Force re-download models (deletes then re-downloads each model)                                                                                       |
| `--yes, -y`         | flag   | false   | Skip confirmation prompts (non-interactive)                                                                                                           |
| `--verbose`         | flag   | false   | Enable verbose output                                                                                                                                 |
| `--remote`          | flag   | false   | Use remote Lemonade Server (skip local install/start, download models via API). Auto-detected when `LEMONADE_BASE_URL` is set to a non-localhost URL. |

**Available Profiles:**

The `--profile` flag accepts one of the following values (see
[`src/gaia/cli.py`](https://github.com/amd/gaia/blob/main/src/gaia/cli.py) for the
canonical choices list):

| Profile   | Models                                             | Description                                                                                          | Approx Size |
| --------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ----------- |
| `minimal` | Gemma-4-E4B-it-GGUF                                | Fast setup with Gemma 4 E4B multimodal model                                                         | \~3 GB      |
| `sd`      | SDXL-Turbo, Gemma-4-E4B-it-GGUF                    | Image generation with multi-modal AI (LLM + SD)                                                      | \~10 GB     |
| `chat`    | Gemma-4-E4B-it-GGUF, user.embeddinggemma-300m-GGUF | Interactive chat with RAG and vision support                                                         | \~4 GB      |
| `code`    | Gemma-4-E4B-it-GGUF                                | Autonomous coding assistant                                                                          | \~3 GB      |
| `rag`     | Gemma-4-E4B-it-GGUF, user.embeddinggemma-300m-GGUF | Document Q\&A with retrieval                                                                         | \~4 GB      |
| `mcp`     | *(none)*                                           | Sets up the MCP servers config (`~/.gaia/mcp_servers.json`) — no Lemonade install or model downloads | –           |
| `vlm`     | Gemma-4-E4B-it-GGUF                                | Vision pipeline for document and image extraction                                                    | \~3 GB      |
| `email`   | Gemma-4-E4B-it-GGUF                                | Gmail/Outlook triage with local inference                                                            | \~3 GB      |
| `npu`     | gemma4-it-e2b-FLM, embed-gemma-300m-FLM            | Ryzen AI NPU acceleration via FLM backend (requires XDNA2 NPU)                                       | \~3 GB      |
| `all`     | All models                                         | All models for all agents                                                                            | \~26 GB     |

<Note>
  The `talk`, `blender`, `jira`, and `docker` agents all rely on the `chat` profile —
  there is no dedicated profile for each. Run `gaia init --profile chat` (or `all`)
  to prepare their dependencies.
</Note>

<Note>
  `gaia llm` quick queries use the global default model (`Gemma-4-E4B-it-GGUF`).
</Note>

**Examples:**

<CodeGroup>
  ```bash Quick Start (Recommended) theme={null}
  gaia init
  ```

  ```bash Minimal Setup (Fast) theme={null}
  gaia init --minimal
  ```

  ```bash Code Development theme={null}
  gaia init --profile code
  ```

  ```bash Vision Pipeline (Lightweight) theme={null}
  gaia init --profile vlm
  ```

  ```bash Non-Interactive CI/CD theme={null}
  gaia init --profile chat --yes
  ```

  ```bash Remote Lemonade Server theme={null}
  gaia init --remote
  ```

  ```bash Remote via Environment Variable theme={null}
  LEMONADE_BASE_URL=http://192.168.1.100:13305/api/v1 gaia init
  ```

  ```bash Force Reinstall Lemonade theme={null}
  gaia init --force-reinstall
  ```

  ```bash Force Re-download Models theme={null}
  gaia init --force-models
  ```
</CodeGroup>

**What It Does:**

GAIA works with Lemonade Server in two modes:

* **Local** — Lemonade runs on the same machine (default)
* **Remote** — Lemonade runs on another machine; enable with `--remote` or by setting `LEMONADE_BASE_URL`

<Tabs>
  <Tab title="Local Mode">
    1. **Checks Lemonade Server** - Detects if installed and verifies version compatibility
    2. **Installs/Upgrades Lemonade** - Downloads and installs from GitHub releases (Windows/Linux only). Automatically uninstalls old version if version mismatch detected.
    3. **Starts Server** - Ensures Lemonade server is running, prompts to start if not
    4. **Downloads Models** - Pulls required models for the selected profile
    5. **Verifies Setup** - Tests each model with inference to detect corrupted downloads
  </Tab>

  <Tab title="Remote Mode">
    Enable with `--remote`, or set `LEMONADE_BASE_URL` to a remote URL
    (e.g., `http://192.168.1.100:13305/api/v1`). The environment variable auto-detects
    remote mode when the hostname is not localhost/127.0.0.1/::1.

    If the remote Lemonade Server requires authentication, also set
    `LEMONADE_API_KEY` to the regular API key — GAIA sends it as
    `Authorization: Bearer <key>` on every Lemonade-bound request
    (see [Lemonade docs](https://lemonade-server.ai/docs/guide/configuration/#api-key-and-security)).

    1. **Checks Remote Server** — Verifies remote Lemonade server version via API
    2. **Checks Connectivity** — Verifies remote server is reachable
    3. **Downloads Models** — Downloads models on the remote server via REST API
    4. **Verifies Setup** — Tests each model with inference to detect corrupted downloads
  </Tab>
</Tabs>

<Warning>
  **Platform Support:** Automatic installation supports Windows (MSI) and Linux (DEB) only. macOS users should install Lemonade Server manually from [lemonade-server.ai](https://www.lemonade-server.ai).
</Warning>

<Tip>
  **Automatic Upgrade:** If your installed Lemonade version doesn't match the expected version, `gaia init` will offer to automatically uninstall the old version and install the correct one.
</Tip>

<Tip>
  **Corrupted Model Detection:** `gaia init` verifies each model with a quick inference test. If a model fails verification (e.g., corrupted download), you'll see instructions to manually delete and re-download it, or use `gaia init --force-models` to force re-download all models.
</Tip>

### Install Command

Install individual GAIA components.

```bash theme={null}
gaia install [OPTIONS]
```

**Options:**

| Option       | Type | Description               |
| ------------ | ---- | ------------------------- |
| `--lemonade` | flag | Install Lemonade Server   |
| `--yes, -y`  | flag | Skip confirmation prompts |

**Examples:**

<CodeGroup>
  ```bash Install Lemonade theme={null}
  gaia install --lemonade
  ```

  ```bash Non-Interactive theme={null}
  gaia install --lemonade --yes
  ```
</CodeGroup>

<Note>
  If a different version of Lemonade is already installed, you'll be prompted to uninstall first.
</Note>

### Uninstall Command

Tiered cleanup of GAIA components. By default, the OS-native uninstall (Add or Remove Programs, drag to Trash, `apt remove`) only removes the app — user data in `~/.gaia/` is preserved. This command lets you escalate cleanup as far as you want.

```bash theme={null}
gaia uninstall [OPTIONS]
```

**Options:**

| Option             | Type | Description                                                 |
| ------------------ | ---- | ----------------------------------------------------------- |
| `--venv`           | flag | Remove the Python environment (`~/.gaia/venv/`)             |
| `--purge`          | flag | Remove venv + chats + documents + config + logs             |
| `--purge-lemonade` | flag | Also remove Lemonade Server (requires `--purge`)            |
| `--purge-models`   | flag | Also remove downloaded Lemonade models (requires `--purge`) |
| `--purge-hf-cache` | flag | Also remove `~/.cache/huggingface/` (requires `--purge`)    |
| `--dry-run`        | flag | Show what would be removed without deleting anything        |
| `--yes, -y`        | flag | Skip confirmation prompts                                   |

**Examples:**

<CodeGroup>
  ```bash Preview theme={null}
  gaia uninstall --dry-run
  ```

  ```bash Remove Python Environment Only theme={null}
  gaia uninstall --venv
  ```

  ```bash Full Purge (venv + chats + documents + config) theme={null}
  gaia uninstall --purge
  ```

  ```bash Purge Including Models theme={null}
  gaia uninstall --purge --purge-models
  ```

  ```bash Purge Including Lemonade Server theme={null}
  gaia uninstall --purge --purge-lemonade --yes
  ```
</CodeGroup>

<Warning>
  `--purge` permanently deletes your chat history, uploaded documents, and configuration. Use `--dry-run` first to preview what will be removed.
</Warning>

### Kill Command

Stop running GAIA services.

```bash theme={null}
gaia kill [OPTIONS]
```

**Options:**

| Option       | Type    | Description                              |
| ------------ | ------- | ---------------------------------------- |
| `--lemonade` | flag    | Kill Lemonade Server and child processes |
| `--port`     | integer | Kill process on specific port            |

**Examples:**

<CodeGroup>
  ```bash Kill Lemonade Server theme={null}
  gaia kill --lemonade
  ```

  ```bash Kill Process on Port theme={null}
  gaia kill --port 8080
  ```
</CodeGroup>

<Note>
  On Windows, `--lemonade` also kills orphaned `llama-server.exe` and `lemonade-tray.exe` processes.
</Note>

### Agent Command

Author, version, validate, and share GAIA agents.

#### Developer workflow: `init`, `version`, `test`

Scaffold a new agent package, bump its version, and run the quality gates that publishing requires. The scaffold mirrors the canonical hub package layout (`hub/agents/python/summarize/`).

```bash theme={null}
gaia agent init <name> [--language python|cpp] [--output DIR] [--force]
gaia agent version <patch|minor|major> [--path DIR]
gaia agent test [--lint | --live] [--path DIR] [--timeout SECONDS]
```

**`init`** scaffolds a package directory named after `<name>`:

* **Python:** `gaia-agent.yaml`, `pyproject.toml` (with the `gaia.agent` entry point), a `gaia_agent_<id>/` package (`__init__.py` + `agent.py` skeleton), `tests/test_agent.py`, and `README.md`.
* **C++:** `gaia-agent.yaml`, `CMakeLists.txt`, `src/agent.cpp`, `tests/`, and `README.md`.

| Option         | Type   | Description                                                       |
| -------------- | ------ | ----------------------------------------------------------------- |
| `name`         | string | Agent id/name — lowercase, hyphens allowed (positional, required) |
| `--language`   | choice | `python` (default) or `cpp`                                       |
| `--output, -o` | string | Parent directory to create the package in (default: current dir)  |
| `--force`      | flag   | Overwrite an existing package directory                           |

**`version`** bumps the SemVer in `gaia-agent.yaml` and keeps `pyproject.toml` / `__init__.py` in sync.

**`test`** runs quality gates in two modes:

| Mode               |     LLM required?     | Checks                                                                                                                                             |
| ------------------ | :-------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--lint` (default) |      No (CI-safe)     | Manifest valid + complete, package structure, Python sources parse + imports resolve, `black` + `isort` clean (Python); manifest + structure (C++) |
| `--live`           | Yes (Lemonade Server) | Agent answers each declared `conversation_starter` within `--timeout` without crashing                                                             |

The publish workflow requires `--lint` to pass; `--live` is recommended but not enforced.

**Examples:**

<CodeGroup>
  ```bash Scaffold and validate theme={null}
  gaia agent init my-agent
  cd my-agent
  gaia agent test --lint
  ```

  ```bash Bump version theme={null}
  gaia agent version patch    # 0.1.0 -> 0.1.1
  ```

  ```bash Live smoke test theme={null}
  gaia agent test --live --timeout 90
  ```
</CodeGroup>

#### Lifecycle: `configure`, `health`, `status`

Manage an *installed* agent: set per-agent configuration, verify it loads, and inspect its state. Configuration is persisted under `~/.gaia/agents/<id>/config.json` and survives restarts.

```bash theme={null}
gaia agent configure <id> [--model NAME] [--set KEY=VALUE ...] [--replace] [--show]
gaia agent health <id>
gaia agent status [<id>]
```

**`configure`** writes per-agent settings (e.g. a preferred model). `--set` values are JSON-decoded when possible (`--set temperature=0.2` stores a number, `--set verbose=true` a boolean), otherwise kept as strings. Settings merge into the existing config by default; pass `--replace` to overwrite it wholesale, or `--show` to print the current config without changing it.

**`health`** verifies that an installed agent actually loads — its registration resolves and its entry point imports. It reports one of `healthy`, `degraded` (loads but something optional is off, e.g. a corrupt config), `error` (a required piece fails to load), or `not_installed`, and exits non-zero for `error` / `not_installed` so scripts can gate on it.

**`status`** aggregates installed version, health, config summary, and source for one agent — or every discovered agent when `<id>` is omitted.

| Option            | Applies to  | Description                                                      |
| ----------------- | ----------- | ---------------------------------------------------------------- |
| `id`              | all         | Agent id (positional; optional for `status`, required otherwise) |
| `--model`         | `configure` | Preferred model, stored as the `model` setting                   |
| `--set KEY=VALUE` | `configure` | Set an arbitrary setting (repeatable)                            |
| `--replace`       | `configure` | Replace the whole config instead of merging                      |
| `--show`          | `configure` | Print the current config and exit                                |

**Examples:**

<CodeGroup>
  ```bash Set a model preference theme={null}
  gaia agent configure chat --model Qwen3.5-35B-A3B-GGUF
  ```

  ```bash Check health and status theme={null}
  gaia agent health chat
  gaia agent status            # every discovered agent
  ```
</CodeGroup>

#### Distribution: `pack`, `publish`, `login`

Build a distributable wheel from a Python agent package, then dual-publish it to the Agent Hub (R2, the source for the Hub UI) **and** PyPI (the source for `pip install`).

```bash theme={null}
gaia agent login [--hub-token TOKEN | --hub] [--pypi-token TOKEN | --pypi]
gaia agent pack [PATH] [--output DIR]
gaia agent publish [PATH] [--output DIR] [--hub-url URL] [--skip-r2] [--skip-pypi]
```

**`pack`** runs `python -m build --wheel` against the package's `pyproject.toml`, writing `gaia_agent_<id>-<version>-py3-none-any.whl` to `dist/` and printing its SHA-256. Python agents only — native (C++) agents ship a CMake-built binary, not a wheel.

**`publish`** packs the wheel and uploads it to both targets. R2 receives a multipart POST (`gaia-agent.yaml` + wheel) authenticated with a Bearer token; PyPI receives a `twine upload` authenticated with an API token. Both enforce version immutability — bump the version with `gaia agent version` before re-publishing.

**`login`** stores publisher tokens in your OS keyring. Tokens may also be supplied via the `GAIA_HUB_TOKEN` and `PYPI_TOKEN` environment variables (useful in CI), which take precedence over the keyring.

| Option                    | Applies to        | Description                                                             |
| ------------------------- | ----------------- | ----------------------------------------------------------------------- |
| `PATH`                    | `pack`, `publish` | Agent package directory (positional, default: current dir)              |
| `--output, -o`            | `pack`, `publish` | Output directory for the wheel (default: `<package>/dist`)              |
| `--hub-url`               | `publish`         | R2 Worker origin (default: `GAIA_HUB_URL` or `https://hub.amd-gaia.ai`) |
| `--skip-r2`               | `publish`         | Publish to PyPI only                                                    |
| `--skip-pypi`             | `publish`         | Publish to R2 only                                                      |
| `--hub-token` / `--hub`   | `login`           | Store the R2 Hub token (pass a value, or `--hub` to be prompted)        |
| `--pypi-token` / `--pypi` | `login`           | Store the PyPI token (pass a value, or `--pypi` to be prompted)         |

The packaging toolchain (`build`, `twine`) ships in the `publish` extra:

```bash theme={null}
pip install "amd-gaia[publish]"
```

**Examples:**

<CodeGroup>
  ```bash Build a wheel theme={null}
  gaia agent pack hub/agents/python/summarize/
  ```

  ```bash Store tokens, then dual-publish theme={null}
  gaia agent login --hub --pypi          # prompts for each token
  gaia agent publish hub/agents/python/summarize/
  ```

  ```bash Publish to PyPI only theme={null}
  gaia agent publish --skip-r2
  ```
</CodeGroup>

##### Installing a published agent

The two publish targets back two install paths, and both register the agent the
same way — via the `gaia.agent` entry point, so the registry discovers it
automatically:

```bash From PyPI (pip) theme={null}
pip install gaia-agent-summarize          # one agent
pip install "amd-gaia[agents]"            # every AMD production agent
```

The **Hub (R2)** path is the Agent UI's discover/install panel, which downloads
the wheel from R2 into `~/.gaia/agents/<id>/` (`POST /api/agents/install`, backed
by `gaia.hub.installer`). Use it when browsing the Hub UI; use `pip install` for
scripted or headless setups.

##### Automated PyPI publishing (CI)

`.github/workflows/publish_agents.yml` builds every production agent wheel and
publishes it to PyPI on a version tag (`v*`). Its matrix is derived from the
`agents` extra in `setup.py` (via `util/list_agent_packages.py`), so adding an
agent there is all it takes to start publishing it. The workflow uploads with
[`pypa/gh-action-pypi-publish`](https://github.com/pypa/gh-action-pypi-publish)
using the `PYPI_API_TOKEN` secret and `skip-existing: true`, so an unchanged
agent version is a no-op rather than an error — PyPI enforces version
immutability natively.

#### Sharing: `export`, `import`

Export every custom agent installed under `~/.gaia/agents/` into a single `.zip` bundle, and import a bundle produced on another machine.

```bash theme={null}
gaia agent export [--output PATH]
gaia agent import PATH [--yes]
```

**Export options:**

| Option            | Type   | Description                                             |
| ----------------- | ------ | ------------------------------------------------------- |
| `--output <path>` | string | Destination `.zip` file (default: `~/.gaia/export.zip`) |

**Import options:**

| Option      | Type   | Description                                                                 |
| ----------- | ------ | --------------------------------------------------------------------------- |
| `path`      | string | Path to the `.zip` bundle to import (positional, required)                  |
| `--yes, -y` | flag   | Skip the interactive trust prompt (required in non-interactive/CI contexts) |

**Examples:**

<CodeGroup>
  ```bash Export all custom agents theme={null}
  gaia agent export
  ```

  ```bash Export to a custom path theme={null}
  gaia agent export --output ./my-agents.zip
  ```

  ```bash Import a bundle (interactive) theme={null}
  gaia agent import ./my-agents.zip
  ```

  ```bash Import non-interactively (CI) theme={null}
  gaia agent import ./my-agents.zip --yes
  ```
</CodeGroup>

<Warning>
  Exported bundles contain your agent source files as-is. Any API keys or credentials present in `agent.py` will be included. Review bundles before sharing.
</Warning>

<Note>
  Importing a bundle runs third-party Python code on your machine. `gaia agent import` shows the agent IDs in the bundle and requires explicit `y`/`yes` confirmation (or `--yes`) before proceeding.
</Note>

***

## Core Commands

### LLM Direct Query

<Note>
  The fastest way to interact with AI models - no server management required.
</Note>

```bash theme={null}
gaia llm QUERY [OPTIONS]
```

**Options:**

| Option         | Type    | Default        | Description                                                                                           |
| -------------- | ------- | -------------- | ----------------------------------------------------------------------------------------------------- |
| `--model`      | string  | Client default | Specify the model to use. Overrides `default_model` from config (see [Configuration](#configuration)) |
| `--max-tokens` | integer | 512            | Maximum tokens to generate                                                                            |
| `--no-stream`  | flag    | false          | Disable streaming response                                                                            |

**Examples:**

<CodeGroup>
  ```bash Basic Query theme={null}
  gaia llm "What is machine learning?"
  ```

  ```bash Specify Model theme={null}
  gaia llm "Explain quantum computing" \
    --model Gemma-4-E4B-it-GGUF \
    --max-tokens 200
  ```

  ```bash No Streaming theme={null}
  gaia llm "Write a short poem about AI" --no-stream
  ```
</CodeGroup>

<Warning>
  The lemonade server must be running. If not available, the command will provide instructions on how to start it.
</Warning>

***

### Chat Command

Start an interactive conversation or send a single message with conversation history.

```bash theme={null}
gaia chat [MESSAGE] [OPTIONS]
```

**Modes:**

* **No message**: Starts interactive chat session
* **Message provided**: Sends single message and exits

**Options:**

| Option                    | Type                | Default                | Description                                                                                                                                                                               |
| ------------------------- | ------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--query, -q`             | string              | -                      | Single query to execute                                                                                                                                                                   |
| `--model`                 | string              | auto-selected by agent | Override the model used by `ChatAgent` (`None` means let the agent pick; see `ChatAgentConfig.model_id`). Falls back to `default_model` from config — see [Configuration](#configuration) |
| `--index, -i`             | path(s)             | -                      | PDF document(s) to index for RAG                                                                                                                                                          |
| `--watch, -w`             | path(s)             | -                      | Directories to monitor for new documents                                                                                                                                                  |
| `--chunk-size`            | integer             | 500                    | Document chunk size for RAG                                                                                                                                                               |
| `--max-chunks`            | integer             | 3                      | Maximum chunks to retrieve for RAG                                                                                                                                                        |
| `--max-indexed-files`     | integer             | 100                    | Maximum number of files to keep indexed. Evicts least-recently-accessed files when LRU eviction is enabled; rejects new files when disabled.                                              |
| `--max-total-chunks`      | integer             | 10000                  | Maximum total chunks across all indexed files. Same eviction behavior as `--max-indexed-files`.                                                                                           |
| `--device`                | `cpu`\|`gpu`\|`npu` | gpu                    | Inference device — selects the model and backend for this session                                                                                                                         |
| `--mcp-tool-limit`        | integer             | 50                     | Maximum MCP tools to register. Larger tool sets bloat the system prompt and degrade small-model tool-calling accuracy — keep as low as your workflow allows                               |
| `--allowed-paths`         | path(s)             | -                      | Restrict RAG/file tools to these directories (security sandbox)                                                                                                                           |
| `--stats`, `--show-stats` | flag                | false                  | Show performance statistics                                                                                                                                                               |
| `--stream`                | flag                | false                  | Enable streaming responses                                                                                                                                                                |
| `--show-prompts`          | flag                | false                  | Display prompts sent to LLM                                                                                                                                                               |
| `--debug`                 | flag                | false                  | Enable debug output                                                                                                                                                                       |
| `--list-tools`            | flag                | false                  | List available tools and exit                                                                                                                                                             |
| `--ui`                    | flag                | false                  | Launch the Chat Web UI (browser-based interface on port 4200)                                                                                                                             |
| `--ui-port`               | integer             | 4200                   | Port for the Agent UI server (used with `--ui`)                                                                                                                                           |
| `--ui-dist`               | path                | -                      | Serve an alternative prebuilt Agent UI bundle (e.g., a PR preview) instead of the one shipped in the package                                                                              |

**Examples:**

<CodeGroup>
  ```bash Interactive Mode theme={null}
  gaia chat
  ```

  ```bash Single Message theme={null}
  gaia chat --query "What is machine learning?"
  ```

  ```bash Single Document theme={null}
  gaia chat --index manual.pdf
  ```

  ```bash Multiple Documents theme={null}
  gaia chat --index doc1.pdf doc2.pdf doc3.pdf
  ```

  ```bash Index and Query theme={null}
  gaia chat --index report.pdf --query "Summarize the report"
  ```

  ```bash Watch Folder theme={null}
  # Auto-index every PDF in a folder, and any new ones dropped in later
  gaia chat --watch ./docs
  ```

  ```bash Custom Settings theme={null}
  gaia chat \
    --model Qwen3.5-35B-A3B-GGUF \
    --stream \
    --show-stats
  ```

  ```bash Web UI (preferred) theme={null}
  gaia --ui
  ```

  ```bash Web UI on Custom Port theme={null}
  gaia --ui --ui-port 8080
  ```

  ```bash Web UI (alias) theme={null}
  gaia chat --ui
  ```
</CodeGroup>

**Interactive Commands:**

During a chat session, use these special commands:

| Command               | Description                                                     |
| --------------------- | --------------------------------------------------------------- |
| `/clear`              | Clear conversation history                                      |
| `/history`            | Show conversation history                                       |
| `/system`             | Show current system prompt configuration                        |
| `/model`              | Show current model information                                  |
| `/prompt`             | Show complete formatted prompt sent to LLM                      |
| `/stats`              | Show performance statistics (tokens/sec, latency, token counts) |
| `/help`               | Show available commands                                         |
| `quit`, `exit`, `bye` | End the chat session                                            |

### Specialized Agent Commands

Use focused agent commands when you want a smaller tool surface than the full chat agent.

```bash theme={null}
gaia browse [OPTIONS]
gaia analyze [OPTIONS]
```

**Options:**

| Option                    | Type    | Default                | Description                                   |
| ------------------------- | ------- | ---------------------- | --------------------------------------------- |
| `--query, -q`             | string  | -                      | Single query to execute                       |
| `--model`                 | string  | auto-selected by agent | Override the model used by the agent          |
| `--allowed-paths`         | path(s) | -                      | Restrict local file paths used by agent tools |
| `--stats`, `--show-stats` | flag    | false                  | Show performance statistics                   |
| `--stream`                | flag    | false                  | Enable streaming responses                    |
| `--show-prompts`          | flag    | false                  | Display prompts sent to LLM                   |
| `--debug`                 | flag    | false                  | Enable debug output                           |
| `--list-tools`            | flag    | false                  | List available tools and exit                 |

**Examples:**

<CodeGroup>
  ```bash Browser Agent theme={null}
  gaia browse --query "Search the web for AMD GAIA documentation"
  ```

  ```bash Analyst Agent theme={null}
  gaia analyze --query 'Create a transactions table with date TEXT and amount REAL'
  ```

  ```bash Inspect Tools theme={null}
  gaia browse --list-tools
  gaia analyze --list-tools
  ```
</CodeGroup>

***

### Prompt Command

Send a single prompt to a GAIA agent.

```bash theme={null}
gaia prompt "MESSAGE" [OPTIONS]
```

**Options:**

| Option         | Type                | Default               | Description                                                                                                                             |
| -------------- | ------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `--model`      | string              | auto                  | Model ID to use (default: auto-selected by each agent). Falls back to `default_model` from config — see [Configuration](#configuration) |
| `--max-tokens` | integer             | 512                   | Maximum tokens to generate                                                                                                              |
| `--device`     | `cpu`\|`gpu`\|`npu` | gpu                   | Inference device (Ryzen AI for `npu`)                                                                                                   |
| `--config`     | path                | `~/.gaia/config.json` | GAIA config file used to resolve `default_model` (or `$GAIA_CONFIG_FILE`)                                                               |
| `--stats`      | flag                | false                 | Show performance statistics                                                                                                             |

**Examples:**

<CodeGroup>
  ```bash Basic theme={null}
  gaia prompt "What is the weather like today?"
  ```

  ```bash With Stats theme={null}
  gaia prompt "Create a poem about AI" \
    --model Gemma-4-E4B-it-GGUF \
    --stats
  ```

  ```bash Custom Tokens theme={null}
  gaia prompt "Write a story" \
    --model Gemma-4-E4B-it-GGUF \
    --max-tokens 1000
  ```
</CodeGroup>

***

## Specialized Agents

### Code Agent

<Card title="Code Development" icon="code" href="/docs/guides/code">
  AI-powered code generation, analysis, and linting for Python/TypeScript
</Card>

<Tip>
  The Code Agent requires extended context. Start Lemonade with:

  ```bash theme={null}
  lemonade-server serve --ctx-size 32768
  ```
</Tip>

**Features:**

* Intelligent Language Detection (Python/TypeScript)
* Code Generation (functions, classes, unit tests)
* Autonomous Workflow (planning → implementation → testing → verification)
* Automatic Test Generation
* Iterative Error Correction
* Code Analysis with AST
* Linting & Formatting

**Quick Examples:**

Routing detects "Express" and uses TypeScript:

<CodeGroup>
  ```bash TypeScript/Express theme={null}
  gaia-code "Create a REST API with Express and SQLite for managing products"
  ```
</CodeGroup>

Routing detects "Django" and uses Python:

<CodeGroup>
  ```bash Python/Django theme={null}
  gaia-code "Create a Django REST API with authentication"
  ```
</CodeGroup>

Routing detects "React" and uses TypeScript frontend:

<CodeGroup>
  ```bash React Frontend theme={null}
  gaia-code "Create a React dashboard with user management"
  ```
</CodeGroup>

<CodeGroup>
  ```bash Interactive Mode theme={null}
  gaia-code --interactive
  ```

  ```bash Cloud LLM theme={null}
  gaia-code "Create a REST API" --use-claude
  ```
</CodeGroup>

[→ Full Code Agent Documentation](/docs/guides/code)

#### Code Index

`gaia-code index` builds and queries a local FAISS-backed semantic index over a repository. Embeddings run on AMD NPU/GPU through Lemonade Server. Requires the `[rag]` extras.

```bash theme={null}
# Build / refresh the index for the current repo
gaia-code index

# Index a specific repo, capping discovery
gaia-code index --repo /path/to/repo --max-files 2000

# Semantic search
gaia-code index search "where do we mint JWT tokens"
gaia-code index search "auth flow" --scope code --top-k 5

# Inspect / wipe the cache
gaia-code index status
gaia-code index clear

# Interactive Q&A (CodeAgent + code_index tools)
gaia-code index chat
```

Common flags at the `index` level: `--repo`, `--max-files`, `--model`, `--base-url`, `--no-lemonade-check`, `--use-claude`, `--use-chatgpt`.

[→ Full Code Index Documentation](/docs/guides/code-index)

***

### Blender Agent

<Card title="3D Scene Creation" icon="cube" href="/docs/guides/blender">
  Natural language 3D modeling and scene manipulation
</Card>

**Features:**

* Natural Language 3D Modeling
* Interactive Planning
* Object Management
* Material Assignment
* MCP Integration

**Options:**

| Option            | Type    | Default | Description                                                                                                    |
| ----------------- | ------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| `--query`         | string  | –       | Custom query to run instead of the built-in examples                                                           |
| `--interactive`   | flag    | false   | Continuously input queries in interactive mode                                                                 |
| `--example`       | string  | –       | Run a specific built-in example (1-6); omit for interactive mode                                               |
| `--steps`         | integer | 50      | Maximum number of steps per query (defaults to the global agent step limit, or `$GAIA_AGENT_MAX_STEPS` if set) |
| `--output-dir`    | path    | output  | Directory to save output files                                                                                 |
| `--mcp-port`      | integer | 9876    | Port for the Blender MCP server                                                                                |
| `--debug-prompts` | flag    | false   | Show prompts sent to the LLM                                                                                   |
| `--print-result`  | flag    | false   | Print results to the console                                                                                   |

**Examples:**

Interactive Blender mode:

```bash theme={null}
gaia blender --interactive
```

Create specific objects:

```bash theme={null}
gaia blender --query "Create a red cube and blue sphere arranged in a line"
```

Run built-in examples:

```bash theme={null}
gaia blender --example 2
```

[→ Full Blender Agent Documentation](/docs/guides/blender)

***

### Email Command

<Card title="Email Triage" icon="envelope" href="/docs/guides/email">
  Read, organize, and reply to Gmail with all email content processed locally on your machine.
</Card>

```bash theme={null}
gaia email -q "<query>"           # one-shot
gaia email -i                     # interactive REPL
gaia email -v -q "Triage my inbox"  # verbose logs for benchmarking
```

**Options:**

| Option              | Type   | Default                            | Description                                                                                                    |
| ------------------- | ------ | ---------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `-q, --query`       | string | –                                  | Single query to send to the agent (non-interactive).                                                           |
| `-i, --interactive` | flag   | false                              | REPL loop until `/quit`.                                                                                       |
| `-v, --verbose`     | flag   | false                              | Emit structured logs for every triage decision and tool call.                                                  |
| `--debug`           | flag   | false                              | Adds full prompt + LLM-response logging (sensitive payloads in logs).                                          |
| `--spec`            | flag   | false                              | Generate the HTML endpoint spec page, write it to disk, and open it in a browser. No LLM or Lemonade required. |
| `--output PATH`     | path   | `~/.gaia/email/endpoint-spec.html` | Where to write the HTML spec (only used with `--spec`).                                                        |

**Setup:** requires the Google connector. Run `gaia connectors connect google` first; you'll be asked to grant Gmail and Calendar scopes.

**Privacy:** all email body inference runs locally on Lemonade — the agent **rejects** any non-local LLM endpoint at startup.

[→ Full Email Triage Agent Documentation](/docs/guides/email)

***

### SD Command

<Card title="Image Generation" icon="image" href="/docs/guides/sd">
  Generate images using Stable Diffusion on Ryzen AI
</Card>

```bash theme={null}
gaia sd <prompt> [OPTIONS]
```

**Options:**

| Option              | Type    | Default               | Description                                                                                                                     |
| ------------------- | ------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `prompt`            | string  | -                     | Text description of the image to generate                                                                                       |
| `-i, --interactive` | flag    | false                 | Run in interactive mode                                                                                                         |
| `--sd-model`        | string  | SDXL-Turbo            | Model: SDXL-Turbo (fast, good quality, default), SD-Turbo (faster, lower quality), SDXL-Base-1.0 (photorealistic, slow), SD-1.5 |
| `--size`            | string  | auto                  | Image size: 512x512, 768x768, 1024x1024 (auto-selected per model)                                                               |
| `--steps`           | integer | auto                  | Inference steps (auto: 4 for Turbo, 20 for Base)                                                                                |
| `--cfg-scale`       | float   | auto                  | CFG scale (auto: 1.0 for Turbo, 7.5 for Base)                                                                                   |
| `--output-dir`      | path    | .gaia/cache/sd/images | Directory to save images                                                                                                        |
| `--seed`            | integer | random                | Seed for reproducibility                                                                                                        |
| `--no-open`         | flag    | false                 | Skip prompt to open image in viewer                                                                                             |

**Examples:**

Fast, good-quality generation with the default (SDXL-Turbo, \~17s):

```bash theme={null}
gaia sd "a sunset over mountains"
```

Even faster (lower quality) with SD-Turbo (\~13s):

```bash theme={null}
gaia sd "cyberpunk city at night" --sd-model SD-Turbo
```

Photorealistic with SDXL-Base-1.0 (slow, \~9min):

```bash theme={null}
gaia sd "portrait, photorealistic, detailed" --sd-model SDXL-Base-1.0
```

For automation (no prompts):

```bash theme={null}
gaia sd "test image" --no-open
```

Interactive mode:

```bash theme={null}
gaia sd -i
```

[→ Full Image Generation Documentation](/docs/guides/sd)

***

### Talk Command

<Card title="Voice Interaction" icon="microphone" href="/docs/guides/talk">
  Speech-to-speech conversation with optional document Q\&A
</Card>

```bash theme={null}
gaia talk [OPTIONS]
```

**Options:**

| Option                 | Type    | Default     | Description                                                                 |
| ---------------------- | ------- | ----------- | --------------------------------------------------------------------------- |
| `--model`              | string  | auto        | Model ID to use (default: auto-selected by each agent)                      |
| `--max-tokens`         | integer | 512         | Maximum tokens to generate                                                  |
| `--no-tts`             | flag    | false       | Disable text-to-speech                                                      |
| `--audio-device-index` | integer | auto-detect | Audio input device index                                                    |
| `--whisper-model-size` | string  | base        | Whisper model \[tiny, base, small, medium, large]                           |
| `--silence-threshold`  | float   | 0.5         | Silence threshold in seconds                                                |
| `--mic-threshold`      | float   | 0.003       | Microphone amplitude threshold for voice detection (lower = more sensitive) |
| `--stats`              | flag    | false       | Show performance statistics                                                 |
| `--index, -i`          | path    | -           | PDF document for voice Q\&A                                                 |

**Examples:**

<CodeGroup>
  ```bash Basic theme={null}
  gaia talk
  ```

  ```bash With Document theme={null}
  gaia talk --index manual.pdf
  ```

  ```bash No TTS theme={null}
  gaia talk -i guide.pdf --no-tts
  ```
</CodeGroup>

[→ Full Voice Interaction Guide](/docs/guides/talk)

***

### Jira Command

<Card title="Jira / Atlassian" icon="ticket" href="/docs/guides/jira">
  Natural-language interface for Jira, Confluence, and Compass using your Atlassian credentials (REST API).
</Card>

```bash theme={null}
gaia jira "Create a bug report for the login issue"
gaia jira --interactive
```

**Options:**

| Option          | Type    | Default   | Description                                       |
| --------------- | ------- | --------- | ------------------------------------------------- |
| `command`       | string  | –         | Natural-language command to execute (positional). |
| `--interactive` | flag    | false     | Continuous interactive mode.                      |
| `--mcp-host`    | string  | localhost | MCP bridge host.                                  |
| `--mcp-port`    | integer | 8765      | MCP bridge port.                                  |
| `--verbose`     | flag    | false     | Verbose output.                                   |
| `--debug`       | flag    | false     | Debug logging.                                    |

[→ Full Jira Guide](/docs/guides/jira)

***

### Docker Command

<Card title="Docker" icon="docker" href="/docs/guides/docker">
  Natural-language interface for Docker containerization.
</Card>

```bash theme={null}
gaia docker "Create a Dockerfile for my Flask app"
gaia docker "Containerize this project" --directory ./myapp
```

**Options:**

| Option        | Type   | Default     | Description                                       |
| ------------- | ------ | ----------- | ------------------------------------------------- |
| `command`     | string | –           | Natural-language command to execute (positional). |
| `--directory` | path   | current dir | Directory to analyze/containerize.                |
| `--verbose`   | flag   | false       | Verbose output.                                   |
| `--debug`     | flag   | false       | Debug logging.                                    |

[→ Full Docker Guide](/docs/guides/docker)

***

### Summarize Command

Summarize meeting transcripts, emails, and PDFs.

```bash theme={null}
gaia summarize --input ./meeting.vtt
gaia summarize --input ./inbox/ --type email --format both
```

**Options:**

| Option              | Type                                 | Default                              | Description                                                                         |
| ------------------- | ------------------------------------ | ------------------------------------ | ----------------------------------------------------------------------------------- |
| `-i, --input`       | path                                 | –                                    | Input file or directory (required unless `--list-configs`).                         |
| `-o, --output`      | path                                 | auto                                 | Output file/directory (auto-adjusted to format).                                    |
| `-t, --type`        | `transcript`\|`email`\|`pdf`\|`auto` | auto                                 | Input type.                                                                         |
| `-f, --format`      | `json`\|`pdf`\|`email`\|`both`       | json                                 | Output format (`both` = json + pdf).                                                |
| `--styles`          | one or more styles                   | executive participants action\_items | `brief`, `detailed`, `bullets`, `executive`, `participants`, `action_items`, `all`. |
| `--max-tokens`      | integer                              | 1024                                 | Maximum tokens for the summary.                                                     |
| `--email-to`        | string                               | –                                    | Recipients (comma-separated) for `email` output format.                             |
| `--email-subject`   | string                               | auto                                 | Email subject line.                                                                 |
| `--email-cc`        | string                               | –                                    | CC recipients (comma-separated).                                                    |
| `--config`          | path                                 | –                                    | Use a predefined configuration file from `configs/`.                                |
| `--list-configs`    | flag                                 | false                                | List available configuration templates and exit.                                    |
| `--combined-prompt` | flag                                 | false                                | Combine styles into a single LLM call (experimental).                               |
| `--no-viewer`       | flag                                 | false                                | Don't auto-open the HTML viewer for JSON output.                                    |
| `--quiet`           | flag                                 | false                                | Minimal output.                                                                     |
| `--verbose`         | flag                                 | false                                | Detailed/debug output.                                                              |

***

### Telegram Command

<Card title="Telegram Adapter" icon="telegram" href="/docs/guides/telegram-adapter">
  Bridge a Telegram bot to GAIA so you can chat with your agents from Telegram.
</Card>

```bash theme={null}
gaia telegram start --token <BOT_TOKEN> --background
gaia telegram status
gaia telegram stop
```

**Subcommands & options:**

| Subcommand | Option               | Default   | Description                                     |
| ---------- | -------------------- | --------- | ----------------------------------------------- |
| `start`    | `--token` (required) | –         | Telegram bot token.                             |
| `start`    | `--allowed-users`    | allow all | Comma-separated user IDs permitted to interact. |
| `start`    | `--background`       | false     | Run as a daemon (writes PID + health endpoint). |
| `stop`     | `--force`            | false     | Force stop if graceful shutdown fails.          |
| `status`   | `--health-host`      | 127.0.0.1 | Health server host.                             |
| `status`   | `--health-port`      | 8765      | Health server port.                             |

[→ Telegram Adapter Guide](/docs/guides/telegram-adapter)

***

## API Server

<Card title="API Server" icon="server" href="/docs/reference/api">
  OpenAI-compatible REST API for VSCode and IDE integrations
</Card>

### Quick Start

1. Start Lemonade with extended context:

```bash theme={null}
lemonade-server serve --ctx-size 32768
```

2. Start GAIA API server:

```bash theme={null}
gaia api start
```

3. Test the server:

```bash theme={null}
curl http://localhost:8080/health
```

### Commands

<Tabs>
  <Tab title="Start">
    ```bash theme={null}
    gaia api start [OPTIONS]
    ```

    **Options:**

    * `--host` - Server host (default: localhost)
    * `--port` - Server port (default: 8080). <Warning>The `gaia mcp docker` bridge defaults to the same port — run them on different ports if you need both.</Warning>
    * `--debug` - Enable debug logging
    * `--show-prompts` - Log the prompts sent to the LLM for every request (useful for debugging)
    * `--streaming` - Stream tokens to clients via SSE (OpenAI-style)
    * `--step-through` - Pause between agent steps for manual inspection (development aid)

    **Examples:**

    Foreground:

    ```bash theme={null}
    gaia api start
    ```

    With debug logging:

    ```bash theme={null}
    gaia api start --debug
    ```

    Custom host/port:

    ```bash theme={null}
    gaia api start --host 0.0.0.0 --port 8888
    ```

    Streaming mode with prompt logging:

    ```bash theme={null}
    gaia api start --streaming --show-prompts
    ```
  </Tab>

  <Tab title="Status">
    ```bash theme={null}
    gaia api status
    ```

    Shows whether the API server is running and displays connection information.
  </Tab>

  <Tab title="Stop">
    ```bash theme={null}
    gaia api stop
    ```

    Stops the running API server gracefully.
  </Tab>
</Tabs>

[→ Full API Server Documentation](/docs/reference/api)

***

## MCP Client

<Card title="MCP Client" icon="plug" href="/docs/sdk/sdks/mcp">
  Connect GAIA agents to external MCP servers
</Card>

Configure MCP servers that your agents can connect to. Servers are saved to `~/.gaia/mcp_servers.json` by default, or to a custom config file using `--config`.

### Commands

#### Managing MCP servers (`add` / `remove`)

<Note>
  `gaia mcp add` and `gaia mcp remove` were removed in #977 — MCP servers are now
  configured through the connectors framework. Run `gaia connectors --help` for the
  current commands. `gaia mcp list` (below) still lists configured servers.
</Note>

#### `gaia mcp list`

List all configured MCP servers.

```bash theme={null}
gaia mcp list [--config PATH]
```

**Options:**

* `--config PATH` - Custom config file path (default: `~/.gaia/mcp_servers.json`)

**Example:**

```bash theme={null}
# List from user config
gaia mcp list

# List from project config
gaia mcp list --config ./mcp_servers.json
```

#### `gaia mcp tools`

List tools available from a configured MCP server.

```bash theme={null}
gaia mcp tools <server-name> [--config PATH]
```

**Arguments:**

* `<server-name>` - Name of the server to query

**Options:**

* `--config PATH` - Custom config file path (default: `~/.gaia/mcp_servers.json`)

**Example:**

```bash theme={null}
# List tools from time server
gaia mcp tools time

# List tools using project config
gaia mcp tools memory --config ./mcp_servers.json
```

#### `gaia mcp test-client`

Test connection to a configured MCP server.

```bash theme={null}
gaia mcp test-client <server-name> [--config PATH]
```

**Arguments:**

* `<server-name>` - Name of the server to test

**Options:**

* `--config PATH` - Custom config file path (default: `~/.gaia/mcp_servers.json`)

**Example:**

```bash theme={null}
gaia mcp test-client time
```

[→ Full MCP Client Guide](/docs/sdk/sdks/mcp)

***

## MCP Bridge

<Card title="MCP Bridge" icon="server" href="/docs/integrations/mcp">
  Expose GAIA agents as MCP servers
</Card>

The MCP Bridge allows other applications to use GAIA agents as MCP servers.

### Quick Start

Install MCP support:

```bash theme={null}
uv pip install -e ".[mcp]"
```

Start MCP bridge:

```bash theme={null}
gaia mcp start
```

Test basic functionality:

```bash theme={null}
gaia mcp test --query "Hello from GAIA MCP!"
```

### Commands

| Command  | Description                                                                            |
| -------- | -------------------------------------------------------------------------------------- |
| `start`  | Start the MCP bridge server                                                            |
| `status` | Check MCP server status                                                                |
| `stop`   | Stop background MCP bridge server                                                      |
| `test`   | Test MCP bridge functionality (optionally against a specific `--tool`)                 |
| `agent`  | Invoke the MCP orchestrator agent (positional `request` arg + `--domain`, `--context`) |
| `docker` | Start the Docker MCP server (default port 8080)                                        |
| `serve`  | Start the Agent UI MCP server (wraps the Agent UI backend)                             |

#### `gaia mcp start` options

| Option           | Default     | Description                                                      |
| ---------------- | ----------- | ---------------------------------------------------------------- |
| `--host`         | `localhost` | Bind address                                                     |
| `--port`         | `8765`      | Port for the MCP bridge                                          |
| `--auth-token`   | *none*      | If set, require `Authorization: Bearer <token>` on every request |
| `--no-streaming` | off         | Disable SSE streaming; reply synchronously                       |
| `--background`   | off         | Detach; use `gaia mcp stop` to terminate                         |
| `--log-file`     | stdout      | Write logs to this path (useful with `--background`)             |
| `--verbose`      | off         | Verbose logging                                                  |
| `--ctx-size`     | `32768`     | Context window hint passed to Lemonade for loaded models         |

#### `gaia mcp test` options

| Option    | Default     | Description                           |
| --------- | ----------- | ------------------------------------- |
| `--query` | *required*  | Text to send to the server            |
| `--tool`  | `gaia.chat` | Which MCP tool to invoke when testing |

#### `gaia mcp agent`

```bash theme={null}
gaia mcp agent <request> [--domain DOMAIN] [--context CONTEXT]
```

Pass a natural-language `request` and, optionally, a `--domain` (e.g. `jira`,
`docker`) and free-form `--context` string to steer the orchestrator.

#### `gaia mcp docker` options

`--port` defaults to `8080`. <Warning>This is the **same default** as `gaia api
start` — run them on different ports if you need both alive at once.</Warning>

[→ Full MCP Integration Guide](/docs/integrations/mcp)

***

## Connectors

<Card title="Connectors" icon="plug" href="/docs/connectors">
  OAuth providers, MCP-server connectors, and per-agent scope grants
</Card>

Manage external connectors (OAuth providers like Google/GitHub, MCP servers, API tokens) and control which agents may use them. Configure a connector once, then grant individual agents the scopes they need.

```bash theme={null}
gaia connectors <subcommand> [OPTIONS]
```

**Subcommands:**

| Subcommand                                 | Description                                                                                                           |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| `list` (alias `status`)                    | List connectors in the catalog with their status (`--json` for machine-readable output)                               |
| `connect <id>`                             | Authorize an OAuth connector (opens a browser); `--scopes` to request specific scopes                                 |
| `configure <id>`                           | Configure a connector — `--set KEY=VALUE` (repeatable) or `--json '<object>'` (e.g. MCP API keys, OAuth client creds) |
| `test <id>`                                | Run a health check for a configured connector                                                                         |
| `disconnect <id>`                          | Remove credentials and reset a connector's state                                                                      |
| `grants {list\|grant\|revoke}`             | Manage per-agent scope grants (credential access)                                                                     |
| `activations {list\|activate\|deactivate}` | Manage per-agent MCP tool visibility (`mcp_server` connectors only)                                                   |

**Examples:**

<CodeGroup>
  ```bash Authorize Google theme={null}
  gaia connectors connect google
  ```

  ```bash Configure an MCP server token theme={null}
  gaia connectors configure github --set GITHUB_TOKEN=ghp_xxx
  ```

  ```bash Grant an agent scopes theme={null}
  gaia connectors grants grant google builtin:chat --scopes gmail.readonly
  ```
</CodeGroup>

[→ Connectors Guide](/docs/connectors) · [→ Connectors SDK](/docs/sdk/infrastructure/connectors)

***

## Configuration

GAIA keeps a small persistent config at `~/.gaia/config.json` (override the
location with the `GAIA_CONFIG_DIR` / `GAIA_CONFIG_FILE` environment variables).
Use it to set a **default model** once instead of passing `--model` on every
command.

```bash theme={null}
gaia config show                                  # print current config + file path
gaia config get default_model                     # read one value
gaia config set default_model Qwen3.5-35B-A3B-GGUF # persist a default model
```

| Key              | Default   | Purpose                                                       |
| ---------------- | --------- | ------------------------------------------------------------- |
| `default_model`  | *(unset)* | Default model ID for `gaia chat` / `gaia llm` / `gaia prompt` |
| `default_device` | `gpu`     | Default inference device (`cpu` / `gpu` / `npu`)              |
| `profile`        | `chat`    | Last `gaia init` profile                                      |

### Default model precedence

For `gaia chat`, `gaia llm`, and `gaia prompt`, the model is resolved highest-wins:

1. An explicit `--model <id>` flag
2. `default_model` from `~/.gaia/config.json`
3. The command's built-in default (`DEFAULT_MODEL_NAME`)

So `gaia config set default_model <id>` lets you skip `--model` entirely, while
`--model` still overrides it for a single run. For `gaia chat`, passing an
explicit `--device` selects a device-specific model and takes precedence over
the config default.

<Note>
  A **missing** config file is fine — GAIA falls back to built-in defaults. A
  **corrupt** config file (invalid JSON) fails loudly with the file path and how
  to recover, rather than silently reverting to defaults.
</Note>

### Using a custom config file

Point GAIA at a config file anywhere on disk — handy for per-project configs or
keeping work and personal defaults separate. Two equivalent ways:

```bash theme={null}
# 1. The --config flag (on `gaia config`, `gaia chat`, `gaia llm`, `gaia prompt`)
gaia config set default_model Qwen3.5-35B-A3B-GGUF --config ./project.gaia.json
gaia llm "hello" --config ./project.gaia.json          # uses that file's default_model

# 2. The GAIA_CONFIG_FILE env var (or GAIA_CONFIG_DIR for just the directory)
GAIA_CONFIG_FILE=./project.gaia.json gaia config set default_model Qwen3.5-35B-A3B-GGUF
GAIA_CONFIG_FILE=./project.gaia.json gaia llm "hello"
```

When both are given, `--config` wins over `GAIA_CONFIG_FILE`, which wins over the
default `~/.gaia/config.json`.

***

## Model Management

### Download Command

Download all models required for GAIA agents with streaming progress.

```bash theme={null}
gaia download [OPTIONS]
```

**Options:**

| Option          | Type    | Default   | Description                                             |
| --------------- | ------- | --------- | ------------------------------------------------------- |
| `--agent`       | string  | all       | Agent to download models for                            |
| `--list`        | flag    | false     | List required models without downloading                |
| `--timeout`     | integer | 1800      | Timeout per model in seconds                            |
| `--host`        | string  | localhost | Lemonade server host                                    |
| `--port`        | integer | 13305     | Lemonade server port                                    |
| `--clear-cache` | flag    | false     | Delete all downloaded GAIA models to free up disk space |

**Available Agents:**
chat, code, talk, rag, blender, jira, docker, vlm, minimal, mcp

**Examples:**

List all models:

<CodeGroup>
  ```bash List All Models theme={null}
  gaia download --list
  ```
</CodeGroup>

List models for specific agent:

<CodeGroup>
  ```bash List Agent Models theme={null}
  gaia download --list --agent chat
  ```
</CodeGroup>

Download all models:

<CodeGroup>
  ```bash Download All theme={null}
  gaia download
  ```
</CodeGroup>

Download for specific agent:

<CodeGroup>
  ```bash Download Agent Models theme={null}
  gaia download --agent code
  ```
</CodeGroup>

**Example Output:**

```
📥 Downloading 3 model(s) for 'chat'...

📥 Qwen3.5-35B-A3B-GGUF
   ⏳ [1/31] Qwen3.5-35B-A3B-Q4_K_M.gguf: 3.5 GB/17.7 GB (20%)
   ...
   ✅ Download complete

✅ user.embeddinggemma-300m-GGUF (already downloaded)

==================================================
📊 Download Summary:
   ✅ Downloaded: 2
   ⏭️  Skipped (already available): 1
==================================================
```

***

### Pull Command

To download individual models, use the Lemonade Server CLI directly:

```bash theme={null}
lemonade-server pull MODEL_NAME [OPTIONS]
```

<Tip>
  Use `lemonade-server list` to see all available models and their download status.
</Tip>

***

## Evaluation Commands

<Card title="Evaluation Framework" icon="chart-bar" href="/docs/reference/eval">
  Systematic testing, benchmarking, and model comparison
</Card>

**Tools for:**

* Agent eval benchmark (scenario-based, end-to-end)
* Auto-fixing failures with Claude Code
* Report generation
* Performance-log visualization

**Quick Examples:**

Run the agent eval benchmark:

```bash theme={null}
gaia eval agent                                    # Run all scenarios
gaia eval agent --category mcp_reliability         # Run MCP reliability scenarios only
gaia eval agent --scenario mcp_simple_tool_call    # Run a single scenario
gaia eval agent --iterations 5                     # Run each scenario 5 times for reliability measurement
gaia eval agent --fix                              # Auto-fix failures with Claude Code
gaia eval agent --compare run1/scorecard.json run2/scorecard.json  # Compare runs
```

Generate a report:

```bash theme={null}
gaia report -d ./eval_results
```

Visualize llama.cpp performance logs:

```bash theme={null}
gaia perf-vis ./logs/llama-server.log
```

[→ Full Evaluation Guide](/docs/reference/eval)

***

### Agent Eval

<Card title="Agent Eval Benchmark" icon="microscope" href="/docs/guides/eval">
  Scenario-based end-to-end testing of the GAIA Agent UI
</Card>

Run automated multi-turn conversation tests against the live Agent UI. The eval agent (Claude Code) simulates user personas, drives conversations via MCP, and judges every response across 7 scoring dimensions.

```bash theme={null}
gaia eval agent [OPTIONS]
```

**Options:**

| Option                 | Type                | Default                 | Description                                                                          |
| ---------------------- | ------------------- | ----------------------- | ------------------------------------------------------------------------------------ |
| `--scenario`           | string              | all                     | Run a specific scenario by ID                                                        |
| `--category`           | string              | all                     | Run all scenarios in a category                                                      |
| `--backend`            | string              | `http://localhost:4200` | Agent UI backend URL                                                                 |
| `--agent-type`         | string              | backend default         | Agent registration ID to target (e.g. `gaia-lite`); scenarios run against this agent |
| `--model`              | string              | `claude-sonnet-4-6`     | Judge/simulator model                                                                |
| `--iterations`         | integer             | `1`                     | Run each scenario N times for reliability measurement                                |
| `--keep-sessions`      | flag                | false                   | Don't delete Agent UI sessions after eval — leave them for manual inspection         |
| `--device`             | `cpu`\|`gpu`\|`npu` | –                       | Inference device hint for the run                                                    |
| `--budget`             | string              | `2.00`                  | Maximum USD spend per scenario                                                       |
| `--timeout`            | integer             | `900`                   | Per-scenario timeout in seconds (auto-scaled for complex scenarios)                  |
| `--audit-only`         | flag                | false                   | Run architecture audit without LLM calls (free)                                      |
| `--generate-corpus`    | flag                | false                   | Regenerate corpus documents and validate `manifest.json`                             |
| `--fix`                | flag                | false                   | Auto-invoke Claude Code to diagnose and repair failures, then re-evaluate            |
| `--max-fix-iterations` | integer             | `3`                     | Maximum repair cycles in `--fix` mode                                                |
| `--target-pass-rate`   | float               | `0.90`                  | Stop fix iterations when judged pass rate reaches this threshold                     |
| `--compare`            | string(s)           | --                      | Compare two scorecard files, or one scorecard against saved baseline                 |
| `--save-baseline`      | flag                | false                   | Save this run's scorecard as `eval/results/baseline.json`                            |
| `--capture-session`    | string              | --                      | Convert an Agent UI session (by UUID) into a YAML scenario file                      |
| `--scenario-dir`       | string              | --                      | Additional scenario directory to scan (repeatable)                                   |
| `--corpus-dir`         | string              | --                      | Additional corpus directory to scan (repeatable)                                     |
| `--tag`                | string              | --                      | Run only scenarios with this tag (repeatable, OR logic)                              |
| `--output-format`      | choice              | --                      | Output format: `json`, `markdown`, or `junit`                                        |

**Examples:**

<CodeGroup>
  ```bash Single Scenario theme={null}
  gaia eval agent --scenario simple_factual_rag
  ```

  ```bash Run Category theme={null}
  gaia eval agent --category rag_quality
  ```

  ```bash Full Benchmark theme={null}
  gaia eval agent
  ```

  ```bash Architecture Audit (Free) theme={null}
  gaia eval agent --audit-only
  ```

  ```bash Auto-Fix Mode theme={null}
  gaia eval agent --fix --max-fix-iterations 5 --target-pass-rate 0.95
  ```

  ```bash Save Baseline theme={null}
  gaia eval agent --save-baseline
  ```

  ```bash Compare Against Baseline theme={null}
  gaia eval agent --compare eval/results/latest/scorecard.json
  ```

  ```bash Explicit Two-File Comparison theme={null}
  gaia eval agent --compare eval/results/run_A/scorecard.json eval/results/run_B/scorecard.json
  ```

  ```bash Capture Session to Scenario theme={null}
  gaia eval agent --capture-session 29c211c7-31b5-4084-bb3f-1825c0210942
  ```

  ```bash Budget and Timeout Control theme={null}
  gaia eval agent --category rag_quality --budget 1.00 --timeout 300
  ```

  ```bash Filter by Tags theme={null}
  gaia eval agent --tag healthcare --tag critical
  ```

  ```bash JUnit Output for CI theme={null}
  gaia eval agent --output-format junit
  ```

  ```bash Custom Scenario Directory theme={null}
  gaia eval agent --scenario-dir ~/my-project/eval-scenarios
  ```
</CodeGroup>

<Note>
  The eval agent requires Claude Code CLI (`claude` command), an Anthropic API key, and the Agent UI backend running. See the [Agent Eval Guide](/docs/guides/eval) for full setup instructions.
</Note>

[→ Full Agent Eval Guide](/docs/guides/eval) · [→ Scenario Authoring](/docs/guides/eval-scenarios) · [→ CI/CD Integration](/docs/guides/eval-ci)

***

### Email Throughput Benchmark

Measure end-to-end email-triage throughput (tokens/sec), time-to-first-token, and pipeline latency for an on-device model. Direct-drives the email agent over the committed synthetic corpus and harvests metrics from the agent's per-step stats. The committed bar is **≥10 tok/s** (snappy-UX stretch \~30 tok/s); the benchmark is **non-gating** — a miss is reported, not failed.

```bash theme={null}
gaia eval benchmark [OPTIONS]
```

**Options:**

| Option            | Type | Default               | Description                                                                                                                                                                                                                |
| ----------------- | ---- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--model`         | str  | `Gemma-4-E4B-it-GGUF` | Lemonade model id to benchmark                                                                                                                                                                                             |
| `--limit`         | int  | `50`                  | Target message count steered to the triage call (effective = min(limit, corpus size))                                                                                                                                      |
| `--experiments`   | int  | `1`                   | Repeat count per model; >1 prints a variance report                                                                                                                                                                        |
| `--mbox-path`     | str  | stub fixture          | MBOX corpus to triage                                                                                                                                                                                                      |
| `--ground-truth`  | str  | fixture's             | Ground-truth JSON for quality scoring                                                                                                                                                                                      |
| `--backend`       | str  | agent default         | Lemonade base URL                                                                                                                                                                                                          |
| `--output-dir`    | str  | —                     | Write `scorecard.json` / `summary.md` / `variance.json`                                                                                                                                                                    |
| `--compare`       | path | —                     | Compare throughput against a saved baseline (non-gating for throughput; a ctx-window mismatch vs the baseline is a hard error)                                                                                             |
| `--save-baseline` | flag | off                   | Save this run's scorecard as the throughput baseline                                                                                                                                                                       |
| `--ctx-size`      | int  | `16384`               | Exact ctx window to pin the model load to (#1892 envelope: 16384 target / 32768 max). Verified by readback and stamped into `scorecard.json` / `quality.json`; values above the envelope max are allowed but warned loudly |

<CodeGroup>
  ```bash Benchmark the primary model theme={null}
  gaia eval benchmark --model Gemma-4-E4B-it-GGUF --limit 50
  ```

  ```bash Repeat for variance + save a baseline theme={null}
  gaia eval benchmark --experiments 3 --save-baseline
  ```

  ```bash Compare against a saved baseline theme={null}
  gaia eval benchmark --compare eval/results/bench_baseline.json
  ```

  ```bash Measure a non-default ctx sweep point theme={null}
  gaia eval benchmark --ctx-size 4096 --experiments 1
  ```
</CodeGroup>

<Note>
  Runs from a GAIA repo checkout (it drives the synthetic corpus in `tests/fixtures/email/`) and needs Lemonade serving the target model. Run at most one `gaia eval` process at a time against a single Lemonade server.
</Note>

***

### Performance Visualization

Plot llama.cpp server performance metrics from one or more log files. Plots are saved as images; pass `--show` to also display them interactively.

```bash theme={null}
gaia perf-vis LOG_PATH [LOG_PATH ...] [--show]
```

**Options:**

| Option      | Type    | Default | Description                                              |
| ----------- | ------- | ------- | -------------------------------------------------------- |
| `log_paths` | path(s) | -       | One or more llama.cpp server log files to visualize      |
| `--show`    | flag    | false   | Display plots interactively in addition to saving images |

**Examples:**

<CodeGroup>
  ```bash Single log theme={null}
  gaia perf-vis ./logs/llama-server.log
  ```

  ```bash Multiple logs + show theme={null}
  gaia perf-vis ./logs/run1.log ./logs/run2.log --show
  ```
</CodeGroup>

***

## Memory

<Card title="Agent Memory Guide" icon="brain" href="/docs/guides/memory">
  Persistent second brain — remembers facts, preferences, and workflows across sessions
</Card>

Manage agent memory: run day-zero onboarding and view memory statistics.

### Commands

<Tabs>
  <Tab title="status">
    Show aggregate memory statistics.

    ```bash theme={null}
    gaia memory status
    ```

    **Output includes:**

    * Knowledge entries by category (fact, preference, error, skill) and context
    * Conversation count and session history
    * Tool call success rates and error counts
    * Upcoming and overdue time-sensitive items
    * Database size
  </Tab>

  <Tab title="bootstrap">
    Run day-zero onboarding to populate memory.

    ```bash theme={null}
    gaia memory bootstrap [OPTIONS]
    ```

    **Options:**

    | Option        | Description                                               |
    | ------------- | --------------------------------------------------------- |
    | `--chat-only` | Conversational questions only (skip system scan)          |
    | `--discover`  | System discovery scan only (skip questions)               |
    | `--reset`     | Delete all discovery-sourced items (preserves user edits) |

    **Examples:**

    Full onboarding (conversational + system scan):

    ```bash theme={null}
    gaia memory bootstrap
    ```

    Questions only:

    ```bash theme={null}
    gaia memory bootstrap --chat-only
    ```

    Re-run system discovery:

    ```bash theme={null}
    gaia memory bootstrap --discover
    ```

    Reset discovered items:

    ```bash theme={null}
    gaia memory bootstrap --reset
    ```
  </Tab>
</Tabs>

[→ Full Memory Guide](/docs/guides/memory) · [→ Memory SDK Reference](/docs/sdk/sdks/memory)

***

## Schedule

Run a prompt on a recurring cron schedule and route its output to a sink. Schedules are stored in `~/.gaia/schedules.toml` (hand-editable). The `daemon` action runs a long-lived scheduler that fires each enabled schedule when due.

```bash theme={null}
gaia schedule {add,list,show,remove,pause,resume,run,daemon} [OPTIONS]
```

### Subcommands

| Action          | Description                                                                                    |
| --------------- | ---------------------------------------------------------------------------------------------- |
| `add`           | Register a new schedule (requires `--name`, `--cron`, and exactly one of `--prompt`/`--skill`) |
| `list`          | List all schedules with their next fire time                                                   |
| `show <name>`   | Show one schedule's full configuration and next fire time                                      |
| `remove <name>` | Delete a schedule                                                                              |
| `pause <name>`  | Disable a schedule without deleting it                                                         |
| `resume <name>` | Re-enable a paused schedule                                                                    |
| `run <name>`    | Fire a schedule once now (for testing)                                                         |
| `daemon`        | Run the long-lived scheduler (blocks until interrupted)                                        |

### `add` Options

| Option     | Type   | Default    | Description                                                                  |
| ---------- | ------ | ---------- | ---------------------------------------------------------------------------- |
| `--name`   | string | *required* | Unique schedule name                                                         |
| `--cron`   | string | *required* | Cron expression, e.g. `"0 7 * * 1-5"`                                        |
| `--prompt` | string | -          | One-shot prompt to run on each fire (mutually exclusive with `--skill`)      |
| `--skill`  | string | -          | Skill to run (mutually exclusive with `--prompt`) — see note below           |
| `--sink`   | string | stdout     | Where output goes: `stdout` \| `file:<path>` \| `notification` \| `telegram` |
| `--to`     | string | -          | Recipient for the `telegram` sink (Telegram user/chat id)                    |

**Examples:**

<CodeGroup>
  ```bash Add a Weekday Morning Brief theme={null}
  gaia schedule add \
    --name morning-brief \
    --cron "0 7 * * 1-5" \
    --prompt "Give me a 3-bullet summary of today's priorities"
  ```

  ```bash List Schedules theme={null}
  gaia schedule list
  ```

  ```bash Fire Once (Test) theme={null}
  gaia schedule run morning-brief
  ```

  ```bash Pause and Resume theme={null}
  gaia schedule pause morning-brief
  gaia schedule resume morning-brief
  ```

  ```bash Run the Scheduler theme={null}
  gaia schedule daemon
  ```
</CodeGroup>

### Sinks

A sink decides where each scheduled run's output goes. Set it with `--sink` on `add` (default `stdout`):

| Sink           | Description                                                                                                                                     |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `stdout`       | Print output to the terminal (default)                                                                                                          |
| `file:<path>`  | Append output to the given file (created if missing)                                                                                            |
| `notification` | Desktop notification (macOS `osascript` / Linux `notify-send`)                                                                                  |
| `telegram`     | Send via a Telegram bot — needs a bot token (`GAIA_TELEGRAM_TOKEN` env var or `sink_args.token` in `schedules.toml`) and a recipient via `--to` |

**Telegram example:**

```bash theme={null}
export GAIA_TELEGRAM_TOKEN="<bot-token>"
gaia schedule add \
  --name daily-digest \
  --cron "0 18 * * *" \
  --prompt "Summarize what changed today" \
  --sink telegram \
  --to 123456789
```

<Note>
  `--skill` is not yet implemented — running a skill-backed schedule raises an error pending the skill format ([#888](https://github.com/amd/gaia/issues/888)). Use `--prompt` for now.
</Note>

***

## Utility Commands

### Stats Command

View performance statistics from the most recent model run.

```bash theme={null}
gaia stats [OPTIONS]
```

***

### Test Commands

Run various tests for development and troubleshooting.

```bash theme={null}
gaia test --test-type TYPE [OPTIONS]
```

<Tabs>
  <Tab title="TTS Tests">
    **Test Types:**

    * `tts-preprocessing` - Test TTS text preprocessing
    * `tts-streaming` - Test TTS streaming playback
    * `tts-audio-file` - Test TTS audio file generation

    **Options:**

    * `--test-text` - Text to use for TTS tests
    * `--output-audio-file` - Output file path (default: output.wav)

    **Examples:**

    Test preprocessing:

    ```bash theme={null}
    gaia test --test-type tts-preprocessing --test-text "Hello, world!"
    ```

    Test streaming:

    ```bash theme={null}
    gaia test --test-type tts-streaming --test-text "Testing streaming"
    ```

    Generate audio file:

    ```bash theme={null}
    gaia test --test-type tts-audio-file \
      --test-text "Save this as audio" \
      --output-audio-file speech.wav
    ```
  </Tab>

  <Tab title="ASR Tests">
    **Test Types:**

    * `asr-file-transcription` - Test ASR file transcription
    * `asr-microphone` - Test ASR microphone input
    * `asr-list-audio-devices` - List audio input devices

    **Options:**

    * `--input-audio-file` - Input audio file path
    * `--recording-duration` - Recording duration (default: 10s)
    * `--audio-device-index` - Audio input device index
    * `--whisper-model-size` - Whisper model size (default: base)

    **Examples:**

    Test file transcription:

    ```bash theme={null}
    gaia test --test-type asr-file-transcription \
      --input-audio-file ./data/audio/test.m4a
    ```

    Test microphone (30 seconds):

    ```bash theme={null}
    gaia test --test-type asr-microphone --recording-duration 30
    ```

    List audio devices:

    ```bash theme={null}
    gaia test --test-type asr-list-audio-devices
    ```
  </Tab>
</Tabs>

***

### YouTube Utilities

Download transcripts from YouTube videos.

```bash theme={null}
gaia youtube --download-transcript URL [--output-path PATH]
```

**Options:**

* `--download-transcript` - YouTube URL to download transcript from
* `--output-path` - Output file path (defaults to transcript\_{video_id}.txt)

**Example:**

```bash theme={null}
gaia youtube \
  --download-transcript "https://youtube.com/watch?v=..." \
  --output-path transcript.txt
```

***

### Daemon Command

Manage the headless custody daemon — the always-on, single-instance background
process that later Agent UI v2 phases (sidecar supervision, `/host/v1/*` custody,
the model-slot broker, the scheduler clock) mount into. This Phase-1 skeleton
provides single-instance identity, client-token auth, and lifecycle control.

Requires the daemon extras (`fastapi`/`uvicorn`/`psutil`) — install with
`pip install "amd-gaia[ui]"` (or `[api]`/`[dev]`). Running it on a base install
fails loudly with that instruction.

```bash theme={null}
gaia daemon start      # start the daemon, or attach if one is already running
gaia daemon status     # show pid, port, and uptime
gaia daemon stop       # graceful shutdown (tree-kills the instance)
gaia daemon restart    # stop then start
gaia daemon logs [--lines N] [--follow]   # tail the daemon log
```

| Action    | Options               | Description                                                               |
| --------- | --------------------- | ------------------------------------------------------------------------- |
| `start`   | —                     | Start the daemon or attach to the running one (two callers → one daemon). |
| `status`  | —                     | Print pid / port / uptime, or report if no daemon is running.             |
| `stop`    | —                     | Shut the daemon down and release `~/.gaia/host/instance.json`.            |
| `restart` | —                     | `stop` followed by `start`.                                               |
| `logs`    | `--lines`, `--follow` | Print (or stream) the daemon log tail.                                    |

***

### Cache Command

Inspect or clear GAIA's on-disk caches (document-Q7 metadata, chat history,
context7 library docs, etc.). Caches live under `~/.gaia/cache/` (Windows:
`%LOCALAPPDATA%/gaia/cache/`).

```bash theme={null}
gaia cache {status,clear} [OPTIONS]
```

**Actions:**

| Action   | Description                                     |
| -------- | ----------------------------------------------- |
| `status` | Print size and location of each cache directory |
| `clear`  | Remove cache contents (scoped by flags below)   |

**Flags for `clear`:**

| Flag         | Description                                                                   |
| ------------ | ----------------------------------------------------------------------------- |
| `--all`      | Remove every cache directory (safe: preserves models under `~/.gaia/models/`) |
| `--context7` | Clear only the Context7 MCP library-docs cache                                |

**Examples:**

<CodeGroup>
  ```bash Inspect caches theme={null}
  gaia cache status
  ```

  ```bash Clear just the Context7 library cache theme={null}
  gaia cache clear --context7
  ```

  ```bash Clear all caches theme={null}
  gaia cache clear --all
  ```
</CodeGroup>

***

### Knowledge Command

Web research via [Tavily](https://tavily.com), with SQLite result caching, a per-session
credit budget, and an automatic keyless DuckDuckGo fallback when the `mcp-tavily`
connector isn't configured. See the [Tavily connector](/docs/connectors/tavily).

```bash theme={null}
gaia knowledge {search,extract,usage} [OPTIONS]
```

**Actions:**

| Action    | Description                                                                    |
| --------- | ------------------------------------------------------------------------------ |
| `search`  | Web search for a query. Falls back to DuckDuckGo when Tavily isn't configured. |
| `extract` | Extract clean content from one or more URLs. Requires the Tavily connector.    |
| `usage`   | Print cached credit-usage totals (per operation + session total).              |

**Options:**

| Flag            | Type                  | Applies to          | Description                                              |
| --------------- | --------------------- | ------------------- | -------------------------------------------------------- |
| `--max-results` | integer               | `search`            | Maximum results to return (default: 5)                   |
| `--depth`       | `basic` \| `advanced` | `search`, `extract` | Depth; `advanced` costs more credits (default: `basic`)  |
| `--budget`      | integer               | `search`, `extract` | Credit cap for the session; omit for unlimited           |
| `--no-block`    | flag                  | `search`, `extract` | Warn instead of blocking when the budget cap is exceeded |

**Examples:**

<CodeGroup>
  ```bash Search the web theme={null}
  gaia knowledge search "AMD ROCm latest release" --max-results 5
  ```

  ```bash Extract page content theme={null}
  gaia knowledge extract https://example.com/post
  ```

  ```bash Show credit usage theme={null}
  gaia knowledge usage
  ```
</CodeGroup>

`search` automatically degrades to DuckDuckGo when the `mcp-tavily` connector isn't
configured; `extract` requires Tavily and raises an actionable error otherwise. Configure
the connector with `gaia connectors configure mcp-tavily --set TAVILY_API_KEY=tvly-...`.

***

### Kill Command

Terminate processes running on specific ports.

```bash theme={null}
gaia kill [OPTIONS]
```

**Options:**

| Option       | Type    | Description                       |
| ------------ | ------- | --------------------------------- |
| `--port`     | integer | Port number to kill process on    |
| `--lemonade` | flag    | Kill Lemonade server (port 13305) |

**Examples:**

<CodeGroup>
  ```bash Kill Lemonade Server theme={null}
  gaia kill --lemonade
  ```

  ```bash Kill by Port theme={null}
  gaia kill --port 13305
  ```
</CodeGroup>

This command will:

* Find the process ID (PID) bound to the specified port
* Forcefully terminate that process
* Provide feedback about success or failure

***

### Diagnostics Command

Bundle system info and logs into a tarball for bug reports.

```bash theme={null}
gaia diagnostics [OPTIONS]
```

**Options:**

| Option      | Type | Default                                     | Description                                    |
| ----------- | ---- | ------------------------------------------- | ---------------------------------------------- |
| `--output`  | path | `~/.gaia/diagnostics-<YYYYMMDD-HHMMSS>.tgz` | Destination path for the tarball               |
| `--no-logs` | flag | false                                       | Omit log files (useful for public bug reports) |

**Examples:**

<CodeGroup>
  ```bash Full Bundle theme={null}
  gaia diagnostics
  # → ~/.gaia/diagnostics-20260422-173000.tgz
  ```

  ```bash Without Logs theme={null}
  gaia diagnostics --no-logs
  ```

  ```bash Custom Output Path theme={null}
  gaia diagnostics --output /tmp/my-bundle.tgz
  ```
</CodeGroup>

The bundle includes:

* System info snapshot (`uname -a`, distro, relevant env vars, all TCP listeners via `ss -tlnp`)
* State files from `~/.gaia/` (config, session data — no chat content)
* Log files: `~/.gaia/gaia.log` and `~/.gaia/electron-main.log` (omitted with `--no-logs`)

***

## Global Options

All commands support these global options:

| Option            | Type   | Default | Description                                                |
| ----------------- | ------ | ------- | ---------------------------------------------------------- |
| `--logging-level` | string | INFO    | Logging verbosity \[DEBUG, INFO, WARNING, ERROR, CRITICAL] |
| `-v, --version`   | flag   | -       | Show program's version and exit                            |

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection Errors" icon="link-slash">
    If you get connection errors, ensure Lemonade server is running:

    ```bash theme={null}
    lemonade-server serve
    ```
  </Accordion>

  <Accordion title="Model Issues" icon="circle-exclamation">
    **Check available system memory** (16GB+ recommended)

    **Verify model compatibility:**

    ```bash theme={null}
    gaia download --list
    ```

    **Pre-download models:**

    ```bash theme={null}
    gaia download
    ```

    **Install additional models:** See [Features Guide](/docs/reference/features#installing-additional-models)
  </Accordion>

  <Accordion title="Audio Issues" icon="microphone-slash">
    **List available devices:**

    ```bash theme={null}
    gaia test --test-type asr-list-audio-devices
    ```

    **Verify microphone permissions** in Windows settings

    **Try different audio device indices** if default doesn't work
  </Accordion>

  <Accordion title="Performance" icon="gauge-high">
    **For optimal NPU performance:**

    * Disable discrete GPUs in Device Manager
    * Ensure NPU drivers are up to date
    * Monitor system resources during execution
  </Accordion>
</AccordionGroup>

For more help, see:

* [Development Guide](/docs/reference/dev#troubleshooting)
* [FAQ](/docs/reference/faq)

***

## See Also

<CardGroup cols={2}>
  <Card title="Code Agent" icon="code" href="/docs/guides/code">
    Python/TypeScript development
  </Card>

  <Card title="Blender Agent" icon="cube" href="/docs/guides/blender">
    3D scene creation
  </Card>

  <Card title="Voice Interaction" icon="microphone" href="/docs/guides/talk">
    Speech-to-speech conversation
  </Card>

  <Card title="API Server" icon="server" href="/docs/reference/api">
    OpenAI-compatible REST API
  </Card>

  <Card title="MCP Integration" icon="plug" href="/docs/integrations/mcp">
    Model Context Protocol
  </Card>

  <Card title="Evaluation Framework" icon="chart-bar" href="/docs/reference/eval">
    Testing and benchmarking
  </Card>

  <Card title="Agent Memory" icon="brain" href="/docs/guides/memory">
    Persistent memory across sessions
  </Card>
</CardGroup>

***

***

<small style="color: #666;">
  **License**

  Copyright(C) 2024-2026 Advanced Micro Devices, Inc. All rights reserved.

  SPDX-License-Identifier: MIT
</small>