CLI Reference - GAIA SDK

Source Code: src/gaia/cli.py

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

Windows 11

Full GUI and CLI support

Linux

Full GUI and CLI support via source installation (Ubuntu/Debian)

Quick Start

Windows
Linux

Follow the Quickstart to install GAIA
Open PowerShell and run gaia to launch the Agent UI, or gaia --cli for terminal chat
GAIA automatically starts Lemonade Server when needed, or start manually:

lemonade-server serve

Install from source: Follow Linux Installation
Install Lemonade Server from lemonade-server.ai
Start the server:

lemonade-server serve

Verify installation:

gaia -v
gaia llm "Hello, world!"

Top-Level Flags

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

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:

gaia

gaia --ui-port 8080

gaia --cli

gaia --ui --base-url https://your-server:13305/api/v1

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.

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.

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

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

Confirming dangerous tools

Shell commands, file writes, and an agent’s own destructive tools (email send / forward / permanent delete, calendar RSVP) prompt before they run:

⚠️  Confirm: send_now
{
  "subject": "Q3 budget",
  "to": "[email protected]"
}
Allow this? [y]es / [N]o / [a]lways for this tool:

The default is no — a bare Enter, Ctrl-C, or EOF denies. a remembers that one tool until the command exits (not offered for run_shell_command / run_cli_command). When GAIA is not attached to a terminal — output piped or redirected, a CI job, a host process — there is nobody to ask, so gated tools are denied with an actionable error rather than run silently. For an unattended run you trust, set GAIA_AUTO_APPROVE_TOOLS=1 in the launching environment:

# CI / batch use only — the model can then send mail and run shell commands
# without asking. Every approval is logged with the tool name.
GAIA_AUTO_APPROVE_TOOLS=1 gaia analyze data.csv --json > report.json

A .env file cannot set this variable; it must come from the real process environment, so a project directory can never switch off your prompts.

Initialization

Init Command

New users start here! The gaia init command is the easiest way to get GAIA running.

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

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

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.

gaia llm quick queries use the global default model (Gemma-4-E4B-it-GGUF).

Examples:

gaia init

gaia init --minimal

gaia init --profile code

gaia init --profile vlm

gaia init --profile chat --yes

gaia init --remote

LEMONADE_BASE_URL=http://192.168.1.100:13305/api/v1 gaia init

gaia init --force-reinstall

gaia init --force-models

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

Local Mode
Remote Mode

Checks Lemonade Server - Detects if installed and verifies version compatibility
Installs/Upgrades Lemonade - Downloads and installs from GitHub releases (Windows/Linux only). Automatically uninstalls old version if version mismatch detected.
Starts Server - Ensures Lemonade server is running, prompts to start if not
Downloads Models - Pulls required models for the selected profile
Verifies Setup - Tests each model with inference to detect corrupted downloads

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

Checks Remote Server — Verifies remote Lemonade server version via API
Checks Connectivity — Verifies remote server is reachable
Downloads Models — Downloads models on the remote server via REST API
Verifies Setup — Tests each model with inference to detect corrupted downloads

Platform Support: Automatic installation supports Windows (MSI), Linux (ppa:lemonade-team/stable, Ubuntu 24.04+), and macOS on Apple Silicon (.pkg, requires admin rights). Intel Macs and other architectures have no upstream Lemonade build — install manually from lemonade-server.ai.

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.

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.

Install Command

Install individual GAIA components.

gaia install [OPTIONS]

Options:

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

Examples:

gaia install --lemonade

gaia install --lemonade --yes

If a different version of Lemonade is already installed, you’ll be prompted to uninstall first.

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.

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:

gaia uninstall --dry-run

gaia uninstall --venv

gaia uninstall --purge

gaia uninstall --purge --purge-models

gaia uninstall --purge --purge-lemonade --yes

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

Kill Command

Stop running GAIA services.

gaia kill [OPTIONS]

Options:

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

Examples:

gaia kill --lemonade

gaia kill --port 8080

On Windows, --lemonade also kills orphaned llama-server.exe and lemonade-tray.exe processes.

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/summarize/python/).

gaia agent init <name> [--language python|cpp] [--output DIR] [--layout flat|hub] [--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)
`--layout`	choice	`flat` (default) creates `<output>/<id>/`; `hub` creates `<output>/<id>/<language>/` to match the hub tree
`--force`	flag	Overwrite an existing package directory

Use --layout hub when authoring a package for this repo’s hub/agents/ tree, which nests the implementation under a language directory (hub/agents/<id>/python/). Standalone packages outside the repo want the default flat layout. 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:

gaia agent init my-agent
cd my-agent
gaia agent test --lint

gaia agent init my-agent -o hub/agents/ --layout hub
cd hub/agents/my-agent/python
gaia agent test --lint

gaia agent version patch    # 0.1.0 -> 0.1.1

gaia agent test --live --timeout 90

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.

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:

gaia agent configure chat --model Qwen3.5-35B-A3B-GGUF

gaia agent health chat
gaia agent status            # every discovered agent

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

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:

pip install "amd-gaia[publish]"

Examples:

gaia agent pack hub/agents/summarize/python/

gaia agent login --hub --pypi          # prompts for each token
gaia agent publish hub/agents/summarize/python/

gaia agent publish --skip-r2

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:

From PyPI (pip)

pip install gaia-agent-summarize          # one agent
pip install "amd-gaia[agents]"            # every AMD production agent

PyPI publishing for gaia-agent-* wheels is currently paused (tracked by #2240), so the commands above don’t resolve yet. Until publishing lands, install an agent straight from this repo:

From source (works today)

uv pip install "gaia-agent-summarize @ git+https://github.com/amd/gaia.git#subdirectory=hub/agents/summarize/python"

The Hub (R2) path downloads the published, SHA-verified artifact into ~/.gaia/agents/<id>/ (backed by gaia.hub.installer). Use the Agent UI’s discover/install panel when browsing the Hub, or install headlessly with:

gaia agent list                            # installed + available hub agents
gaia agent install <id>                    # latest published version
gaia agent install <id> --version 0.5.0    # a specific version
gaia agent install <id> --trust            # required for non-verified agents

gaia agent list shows what the hub offers (with an [installed] marker) so you know which id to pass. This is the supported way to provision a sidecar agent (e.g. email) on a machine with no UI.

gaia agent install installs in-process. gaia hub install performs the same install through the daemon, which additionally stops that agent’s running sidecar first and keeps it stopped for the whole download — the install directory is the sidecar’s own binary cache. Reach for gaia hub when the daemon supervises the agent, and gaia agent when it does not (or when the daemon extras are not installed). Both enforce the same --trust gate and the same SHA-256 verification.

Running the agent (e.g. gaia email -q "...") starts its sidecar automatically on first use; gaia daemon start-agent <id> is an optional pre-flight to launch and health-check it early.

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 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. Export every custom agent installed under ~/.gaia/agents/ into a single .zip bundle, and import a bundle produced on another machine.

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:

gaia agent export

gaia agent export --output ./my-agents.zip

gaia agent import ./my-agents.zip

gaia agent import ./my-agents.zip --yes

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.

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.

Core Commands

LLM Direct Query

The fastest way to interact with AI models - no server management required.

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)
`--max-tokens`	integer	512	Maximum tokens to generate
`--no-stream`	flag	false	Disable streaming response

Examples:

gaia llm "What is machine learning?"

gaia llm "Explain quantum computing" \
  --model Gemma-4-E4B-it-GGUF \
  --max-tokens 200

gaia llm "Write a short poem about AI" --no-stream

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

Chat Command

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

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

gaia chat

gaia chat --query "What is machine learning?"

gaia chat --index manual.pdf

gaia chat --index doc1.pdf doc2.pdf doc3.pdf

gaia chat --index report.pdf --query "Summarize the report"

# Auto-index every PDF in a folder, and any new ones dropped in later
gaia chat --watch ./docs

gaia chat \
  --model Qwen3.5-35B-A3B-GGUF \
  --stream \
  --show-stats

gaia --ui

gaia --ui --ui-port 8080

gaia chat --ui

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.

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:

gaia browse --query "Search the web for AMD GAIA documentation"

gaia analyze --query 'Create a transactions table with date TEXT and amount REAL'

gaia browse --list-tools
gaia analyze --list-tools

Prompt Command

Send a single prompt to a GAIA agent.

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

gaia prompt "What is the weather like today?"

gaia prompt "Create a poem about AI" \
  --model Gemma-4-E4B-it-GGUF \
  --stats

gaia prompt "Write a story" \
  --model Gemma-4-E4B-it-GGUF \
  --max-tokens 1000

Specialized Agents

Code Agent

Code Development

AI-powered code generation, analysis, and linting for Python/TypeScript

The Code Agent requires extended context. Start Lemonade with:

lemonade-server serve --ctx-size 32768

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:

gaia-code "Create a REST API with Express and SQLite for managing products"

Routing detects “Django” and uses Python:

gaia-code "Create a Django REST API with authentication"

Routing detects “React” and uses TypeScript frontend:

gaia-code "Create a React dashboard with user management"

gaia-code --interactive

gaia-code "Create a REST API" --use-claude

→ Full Code Agent Documentation

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.

# 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

Blender Agent

3D Scene Creation

Natural language 3D modeling and scene manipulation

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:

gaia blender --interactive

Create specific objects:

gaia blender --query "Create a red cube and blue sphere arranged in a line"

Run built-in examples:

gaia blender --example 2

→ Full Blender Agent Documentation

Email Command

Email Triage

Read, organize, and reply to Gmail with all email content processed locally on your machine.

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

`gaia email autonomy` — autonomy control

A thin client over the sidecar’s /v1/email/agent/autonomy* REST routes, relayed through the daemon like every other gaia email command (same auth path — no sidecar bearer ever reaches the CLI).

gaia email autonomy status                    # current level + trust summary
gaia email autonomy trust                     # earned-trust ledger
gaia email autonomy set-level earn_trust       # set the level explicitly
gaia email autonomy pause                      # stop autonomous activity
gaia email autonomy resume --level earn_trust  # resume (default: earn_trust)
gaia email autonomy kill                       # kill switch — level -> off
gaia email autonomy run --max-messages 25      # trigger one cycle now

All subcommands share one persistent --session-id (default cli) — autonomy state lives on that session’s in-memory agent, not on disk, so a level you set stays set across invocations that use the same session. run refuses with an actionable error while the level is off (#2528) instead of silently reporting that nothing happened.

SD Command

Image Generation

Generate images using Stable Diffusion on Ryzen AI

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):

gaia sd "a sunset over mountains"

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

gaia sd "cyberpunk city at night" --sd-model SD-Turbo

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

gaia sd "portrait, photorealistic, detailed" --sd-model SDXL-Base-1.0

For automation (no prompts):

gaia sd "test image" --no-open

Interactive mode:

gaia sd -i

→ Full Image Generation Documentation

Talk Command

Voice Interaction

Speech-to-speech conversation with optional document Q&A

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:

gaia talk

gaia talk --index manual.pdf

gaia talk -i guide.pdf --no-tts

→ Full Voice Interaction Guide

Jira Command

Jira / Atlassian

Natural-language interface for Jira, Confluence, and Compass using your Atlassian credentials (REST API).

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

Docker Command

Docker

Natural-language interface for Docker containerization.

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

Summarize Command

Summarize meeting transcripts, emails, and PDFs.

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

Telegram Adapter

Bridge a Telegram bot to GAIA so you can chat with your agents from Telegram.

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

API Server

OpenAI-compatible REST API for VSCode and IDE integrations

Quick Start

Start Lemonade with extended context:

lemonade-server serve --ctx-size 32768

Start GAIA API server:

gaia api start

Test the server:

curl http://localhost:8080/health

Commands

Start
Status
Stop

gaia api start [OPTIONS]

Options:

--host - Server host (default: localhost)
--port - Server port (default: 8080).
The gaia mcp docker bridge defaults to the same port — run them on different ports if you need both.
--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:

gaia api start

With debug logging:

gaia api start --debug

Custom host/port:

gaia api start --host 0.0.0.0 --port 8888

Streaming mode with prompt logging:

gaia api start --streaming --show-prompts

gaia api status

Queries the server’s /health endpoint and reports whether the GAIA API server is running, plus its endpoints. Exits non-zero when the server is not running or the port is held by a different process. Use --host / --port to check a non-default address.

gaia api stop

Stops the running API server gracefully.

→ Full API Server Documentation

MCP Client

Connect GAIA agents to external MCP servers

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

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.

`gaia mcp list`

List all configured MCP servers.

gaia mcp list [--config PATH]

Options:

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

Example:

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

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:

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

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:

gaia mcp test-client time

→ Full MCP Client Guide

MCP Bridge

Expose GAIA agents as MCP servers

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

Quick Start

Install MCP support:

uv pip install -e ".[mcp]"

Start MCP bridge:

gaia mcp start

Test basic functionality:

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)
`tui`	Start the TUI control MCP server (drives a running `gaia tui --control`)

`gaia mcp start` options

Option	Default	Description
`--host`	`localhost`	Bind address
`--port`	`8765`	Port for the MCP bridge
`--auth-token`	`$GAIA_MCP_AUTH_TOKEN`	Require `Authorization: Bearer <token>` on every request except `/health`
`--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

Authentication

The bridge is unauthenticated by default. Anything that can reach the port can enumerate and invoke its tools, which is why --host defaults to localhost. Pass --auth-token before exposing it anywhere else:

export GAIA_MCP_AUTH_TOKEN=$(python -c "import secrets; print(secrets.token_urlsafe(32))")
gaia mcp start --host 0.0.0.0 --port 8765

Prefer the environment variable over --auth-token <token>: on Linux and macOS command-line arguments are visible to any local user via ps. Clients then send the token on every call:

curl -H "Authorization: Bearer $GAIA_MCP_AUTH_TOKEN" http://localhost:8765/status

Request	Response
Valid `Bearer` token	Normal response
Missing or malformed `Authorization` header	`401`
Well-formed header, wrong token	`403`

GET /health stays public so container and orchestrator liveness probes keep working; it reports only liveness plus agent/tool counts. Every other endpoint — /status, /tools, /chat, /llm, /jira, /summarize, and the JSON-RPC endpoint — requires the token. gaia mcp status, gaia mcp test, and gaia mcp agent accept --auth-token (also defaulting to $GAIA_MCP_AUTH_TOKEN) so they can reach a protected bridge.

The bridge speaks plain HTTP. A bearer token stops anonymous callers but does not encrypt traffic — put it behind a TLS-terminating reverse proxy, or keep it on loopback, before sending a token across an untrusted network.

`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
`--auth-token`	`$GAIA_MCP_AUTH_TOKEN`	Bearer token, if the bridge requires one

`gaia mcp agent`

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.

This is the same default as gaia api start — run them on different ports if you need both alive at once.

`gaia mcp tui` options

Wraps the TUI control API as MCP tools, so an assistant can navigate and type in the TUI session you are watching. The TUI must already be running with gaia tui --control; the server finds it through ~/.gaia/tui/control.json rather than a fixed port.

Option	Default	Description
`--stdio`	off	Use stdio transport (what Claude Code expects)
`--host`	`localhost`	HTTP MCP bind address
`--port`	`8767`	HTTP MCP port

→ Full TUI Control MCP Guide → Full MCP Integration Guide

Connectors

OAuth providers, MCP-server connectors, and per-agent scope grants

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.

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:

gaia connectors connect google

# Outlook.com / Hotmail / Live. Supply a pre-registered public client id;
# GAIA prints a code + URL.
export GAIA_MICROSOFT_CLIENT_ID=<application-client-id>
gaia connectors connect microsoft --device

# Microsoft 365 / Entra ID — a SEPARATE connector from personal Microsoft,
# connectable at the same time. Its own client id env var.
export GAIA_MICROSOFT_WORK_CLIENT_ID=<application-client-id>
gaia connectors connect microsoft_work --device

gaia connectors configure github --set GITHUB_TOKEN=ghp_xxx

gaia connectors grants grant google builtin:chat --scopes gmail.readonly

The --device flag on connect uses the RFC 8628 device-code flow instead of the browser redirect — required for Microsoft zero-setup sign-in (no Azure app registration or loopback redirect URI). Which authority a Microsoft connector signs in against is fixed by the connector itself (microsoft → consumers, microsoft_work → organizations) — to restrict microsoft_work to one Entra tenant, set its optional Directory (tenant) ID setup field instead of an environment variable; see the Microsoft connector guide. → Connectors Guide · → Connectors SDK

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.

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:

An explicit --model <id> flag
default_model from ~/.gaia/config.json
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.

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.

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:

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

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:

gaia download --list

List models for specific agent:

gaia download --list --agent chat

Download all models:

gaia download

Download for specific agent:

gaia download --agent code

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:

lemonade-server pull MODEL_NAME [OPTIONS]

Use lemonade-server list to see all available models and their download status.

Evaluation Commands

Evaluation Framework

Systematic testing, benchmarking, and model comparison

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:

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:

gaia report -d ./eval_results

Visualize llama.cpp performance logs:

gaia perf-vis ./logs/llama-server.log

→ Full Evaluation Guide

Agent Eval

Agent Eval Benchmark

Scenario-based end-to-end testing of the GAIA Agent UI

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.

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-opus-5`	Driver and judge — it runs each scenario as well as scoring it, so it must match the baseline you compare against
`--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:

gaia eval agent --scenario simple_factual_rag

gaia eval agent --category rag_quality

gaia eval agent

gaia eval agent --audit-only

gaia eval agent --fix --max-fix-iterations 5 --target-pass-rate 0.95

gaia eval agent --save-baseline

gaia eval agent --compare eval/results/latest/scorecard.json

gaia eval agent --compare eval/results/run_A/scorecard.json eval/results/run_B/scorecard.json

gaia eval agent --capture-session 29c211c7-31b5-4084-bb3f-1825c0210942

gaia eval agent --category rag_quality --budget 1.00 --timeout 300

gaia eval agent --tag healthcare --tag critical

gaia eval agent --output-format junit

gaia eval agent --scenario-dir ~/my-project/eval-scenarios

The eval agent requires Claude Code CLI (claude command), an Anthropic API key, and the Agent UI backend running. See the Agent Eval Guide for full setup instructions.

→ Full Agent Eval Guide · → Scenario Authoring · → CI/CD Integration

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.

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

gaia eval benchmark --model Gemma-4-E4B-it-GGUF --limit 50

gaia eval benchmark --experiments 3 --save-baseline

gaia eval benchmark --compare eval/results/bench_baseline.json

gaia eval benchmark --ctx-size 4096 --experiments 1

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.

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.

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:

gaia perf-vis ./logs/llama-server.log

gaia perf-vis ./logs/run1.log ./logs/run2.log --show

Memory

Agent Memory Guide

Persistent second brain — remembers facts, preferences, and workflows across sessions

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

Commands

status
bootstrap

Show aggregate memory statistics.

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

Run day-zero onboarding to populate memory.

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):

gaia memory bootstrap

Questions only:

gaia memory bootstrap --chat-only

The questions adapt to your answers (a student is asked about coursework, an engineer about their deployment workflow), and everything they produce is shown for approval ([Y/n/q]) before it is stored. --chat-only needs no LLM and no Lemonade Server — it writes plain rows, which are embedded the next time an agent starts.Re-run system discovery:

gaia memory bootstrap --discover

Reset discovered items:

gaia memory bootstrap --reset

→ Full Memory Guide · → Memory SDK Reference

Skills

Agent Skills Spec

Portable SKILL.md capabilities — instructions, optional typed tools, and resources an agent loads only when relevant

Author and manage agent skills. A skill is a directory whose only required file is SKILL.md; GAIA implements the Agent Skills open standard, so a Claude Code skill loads unchanged.

gaia skill {list,info,create,import,export,migrate} [OPTIONS]     # author locally
gaia skill audit <dir> [OPTIONS]                                  # pre-publish gate
gaia skill {search,install,remove,publish,keygen,trust} [OPTIONS] # marketplace

Skills are discovered from three roots, highest precedence first:

Root label	Location	Writable?
`agent-bundled`	An agent package’s own `skills/` directory	No
`user`	`~/.gaia/skills/` (honors `GAIA_CONFIG_DIR`)	Yes — where `create` and `import` install
`claude-import`	`./.claude/skills/` then `~/.claude/skills/`	No — read-only Claude Code import

Subcommands

Action	Description
`list`	List every discovered skill with its version, tier, root, and provided tools
`info <name>`	Show one skill’s manifest in detail
`create <name>`	Scaffold a new skill directory
`import <source>`	Copy a skill folder, `.zip`, or URL into `~/.gaia/skills/`
`export <name>`	Export a skill to a `.zip` bundle
`migrate <source>`	Convert an OpenClaw or Hermes skill to GAIA format
`search [query]`	Search the Agent Hub’s skills lane
`install <name[@range]>`	Install a published skill into `~/.gaia/skills/`
`remove <name>`	Delete an installed skill and drop its lock entry
`publish <dir>`	Validate, audit, sign, and publish a skill to the hub
`keygen`	Generate an Ed25519 publisher key for signing
`trust {list,add,remove}`	Manage the public keys whose signatures this machine trusts

gaia skill list [--json] [--root ROOT]

Option	Description
`--json`	Emit JSON instead of a table (includes roots, shadowed copies, and parse errors)
`--root`	Only show skills from one root: `agent-bundled` \| `user` \| `claude-import`

NAME                         VERSION    TIER          ROOT           TOOLS
demo-skill                   0.1.0      experimental  user           example_tool
gaia-testing                 -          experimental  claude-import  -

A skill shadowed by a higher-precedence copy of the same name is reported on stderr rather than hidden. A skill directory that fails to parse is listed with its error and the command exits 4.

gaia skill info <name> [--json] [--body]

Option	Description
`--json`	Emit JSON (including the full frontmatter) instead of text
`--body`	Also print the Markdown instructions

Shows path, root, license, security tier, declared permissions, the tools the skill provides (namespaced <skill>/<tool>), the registry tools it consumes (tools_required), and any lower-precedence copies it shadows.

gaia skill create <name> [OPTIONS]

Option	Description
`--dir`	Parent directory for the new skill (default: `~/.gaia/skills`)
`--description`	Description / trigger signal — the text the model reads to decide relevance
`--with-tools`	Also scaffold `tools.py` with an example `@tool` function
`--force`	Overwrite an existing skill directory

Names must be lowercase-with-hyphens and match the directory name. The scaffold is validated through the real parser before it is written, so create can never emit a SKILL.md that info rejects.

gaia skill import <folder|zip|https-url> [OPTIONS]

Option	Description
`--name`	Install under this name instead of the source’s
`--force`	Overwrite an existing installed skill

Copies into ~/.gaia/skills/. Imported skills re-earn trust: the security tier is reset to experimental regardless of what the source claims, and the reset is reported. .zip bundles are checked for path traversal before extraction.

gaia skill export <name> [--output FILE.zip]

Option	Description
`--output`	Destination `.zip` (default: `./<name>.zip`)

Bundles the whole skill directory. Import it elsewhere with gaia skill import <file>.zip.

gaia skill audit <dir> [OPTIONS]

Option	Description
`--json`	Emit the machine-readable report on stdout — the payload the hub publish path attaches as its `audit` part
`--output FILE`	Also write the JSON report to `FILE`
`--sarif FILE`	Write SARIF 2.1.0 for upload to GitHub code scanning
`--path-prefix DIR`	Repo-relative prefix for SARIF paths (default: the audited path)
`--tier TIER`	Audit against `experimental`/`community`/`verified` instead of the tier the skill declares
`--fail-on SEVERITY`	Exit non-zero when any finding reaches this severity, even if the tier would allow it
`--show-snippets`	Include the offending source text (withheld by default)

Runs the pre-publish security audit (#2468) over a skill’s code and its instruction body, printing an ALLOW / REVIEW / BLOCK verdict with file:line findings and the fix for each. This is the same engine that gates both contribution paths — the Skill Audit PR check, and gaia skill publish, which runs it before upload — so a clean local audit is what either one requires: BLOCK fails, REVIEW holds for maintainer sign-off, ALLOW passes.Exit codes: 0 allow · 5 review · 6 block · 4 the skill could not be parsed. REVIEW and BLOCK are distinct so CI can hold a skill without reporting it as rejected.Use --tier community to check a claim before making it — a skill cannot be stamped a tier whose gate it did not clear, so this is the difference between finding out locally and finding out as a publish rejection.Nothing is imported, executed, or fetched, so auditing an untrusted skill is itself safe.

gaia skill migrate <source> [--from openclaw|hermes|auto] [OPTIONS]

Option	Description
`--from`	Source format: `openclaw` \| `hermes` \| `auto` (default — detect from `metadata.<vendor>`)
`--out`	Write migrated skills here instead of installing into `~/.gaia/skills/`
`--name`	Migrate under this name (single-skill sources only)
`--force`	Replace an existing skill of the same name (refused when the target resolves to the source’s own directory — replacing it there would delete the source)
`--dry-run`	Report what would be migrated without writing anything
`--json`	Emit the migration report as JSON

<source> is one skill directory, its SKILL.md, or a directory of skill directories — so a whole ClawHub checkout migrates in one command.The foreign metadata.<vendor> namespace becomes a metadata.gaia block. Fields GAIA models fully are consumed; anything partially or un-modeled stays under metadata.<vendor> and is listed in the report, so nothing is dropped silently. Every migrated skill lands at the experimental tier, whatever the source claimed — the same trust reset import applies.

A source needing a local capability is refused, not downgraded. requires.bins maps to shell:execute:<bin> and requires.config to filesystem:read:<path>; both need the deferred permission sandbox (#1019), so the skill is reported unmigratable with the reason rather than quietly stripped of the permission. Other skills in the same batch still migrate — exit code is 4 when any were refused.

gaia skill search [query] [--json] [--hub-url URL]

Matches the query against each published skill’s name, description, and the tools it provides. Omit the query to list the whole skills lane.

NAME                         VERSION    TIER          TOOLS  DESCRIPTION
web-research                 1.2.0      community     1      Search the web and summarize results
incident-review              0.3.1      experimental  0      Structure a postmortem from an incident log

gaia skill install <name[@version-range]> [OPTIONS]

Option	Description
`--allow-experimental`	Required when the skill’s effective tier is `experimental`
`--force`	Replace an already-installed copy
`--yes`	Grant dangerous permissions without prompting (CI)
`--hub-url`	Hub origin override
`--json`	Emit JSON instead of text

The version is a SemVer range — web-research@^1.2, @>=1.0.0, <2.0.0, @1.4.7, or omitted for the latest. The highest published version satisfying it wins, the same rule agent dependencies: use.Install verifies the artifact’s SHA-256 against the hub manifest, verifies the bundle’s SIGNATURE.json over every file, then installs at min(claimed tier, tier the signature earned). Nothing is written until every gate passes.

gaia skill publish <directory> [OPTIONS]

Option	Description
`--hub-url`	Hub origin override (default: `GAIA_HUB_URL`)
`--key-name`	Signing key to use (default: `publisher`)
`--publisher`	Publisher identity recorded in the signature
`--unsigned`	Publish without a signature — only valid for `experimental`
`--audit-report`	Use this audit report JSON instead of running the audit engine
`--dry-run`	Run every gate and build the upload, but do not send it

Requires a hub token in GAIA_HUB_TOKEN (or stored by gaia agent login), and a SemVer version: in SKILL.md — the catalog is versioned and each version is immutable.

Publishing is gated on the pre-publish security audit (#2468). If the audit engine is not installed and no --audit-report is supplied, publish fails — it never proceeds un-audited.

gaia skill keygen [--key-name NAME] [--force]
gaia skill trust list
gaia skill trust add <public-key|file.pub> [--publisher NAME] [--role publisher|amd]
gaia skill trust remove <key-id>

keygen writes an Ed25519 keypair to ~/.gaia/skills/keys/ (private key owner-only). Share the .pub half with anyone who should trust your skills.A key’s role decides the highest tier its signatures can attest:

Role	Attests	Meaning
`publisher`	`community`	A publisher you trust
`amd`	`verified`	The AMD signing root

The trust store ships empty — no AMD key is bundled. Until an operator adds one, every skill installs at experimental, which is the honest floor rather than a placeholder that would make verified look anchored when it is not.

Security tiers at install

Three tiers set the install-time permission ceiling. A skill’s front matter states the tier it wants; its signature decides the tier it gets.

Tier	Signature required	Ceiling	At install
`verified`	AMD-role trust-store key	Every declared permission	Auto-grant, no prompt
`community`	Any trusted publisher key	`network:read`, `network:write`, `mcp:connect`	Dangerous grants prompt
`experimental`	None	`network:read` only	Needs `--allow-experimental`

The effective tier is min(claimed, attested), so no unsigned skill installs as verified — the claim is collapsed rather than trusted. Imported skills (gaia skill import) always land experimental.

v1 skills are instruction + connector-bridged only. A skill declaring a local-capability permission (filesystem, shell, database, desktop, env) is refused at every tier, including verified — the sandbox that would contain it is deferred (#1019). A verified stamp is a provenance claim, not a runtime sandbox.

`skill-lock.json`

Hub installs are tracked in ~/.gaia/skills/skill-lock.json. Discovery answers what is on disk; the lock answers what was requested, what resolved, what the artifact hashed to, who signed it, and which tier it was installed at after the ceiling was applied:

{
  "schema_version": 1,
  "generated_at": "2026-07-30T12:00:00+00:00",
  "skills": {
    "web-research": {
      "name": "web-research",
      "version": "1.2.0",
      "requested": "^1.0",
      "source": "hub",
      "hub_url": "https://hub.amd-gaia.ai",
      "artifact_sha256": "9f2c…",
      "artifact_filename": "web-research-1.2.0.zip",
      "claimed_tier": "community",
      "attested_tier": "community",
      "installed_tier": "community",
      "signature": {
        "signed": true,
        "key_id": "a7630e70…",
        "publisher": "acme",
        "role": "publisher"
      },
      "permissions": ["network:read:*.brave.com"],
      "installed_at": "2026-07-30T12:00:00+00:00",
      "path": "/Users/me/.gaia/skills/web-research"
    }
  }
}

Only hub installs are tracked — a skill from create or import has no hub provenance to record. Examples:

gaia skill create web-research --with-tools \
  --description "Search the web. Use when the user asks about current events."
gaia skill info web-research --body

gaia skill list
gaia skill list --root user            # only your own skills
gaia skill list --json | jq '.roots'   # where GAIA looked

gaia skill list --root claude-import   # what's already visible read-only
gaia skill import ~/.claude/skills/my-skill    # take ownership, resets to experimental

gaia skill export web-research --output ./web-research.zip
gaia skill import ./web-research.zip --name web-research-copy

gaia skill migrate ./my-openclaw-skill --from openclaw
gaia skill migrate ~/clawhub-skills --dry-run     # whole collection, no writes
gaia skill migrate ~/clawhub-skills --json | jq '.skills[] | select(.migrated == false)'

gaia skill search "web search"
gaia skill install web-research@^1.2
gaia skill info web-research               # tier the signature actually earned
gaia skill install some-skill --allow-experimental
gaia skill remove web-research

gaia skill keygen                          # once, per machine
export GAIA_HUB_TOKEN=...
gaia skill publish ./my-skill/ --dry-run   # run every gate, upload nothing
gaia skill publish ./my-skill/ --publisher acme

gaia skill trust add ./acme.pub --publisher acme --role publisher
gaia skill trust list

Exit codes: 0 success · 2 missing/unknown subcommand · 3 skill not found · 4 invalid skill (bad manifest, name collision without --force, or a discovery root containing a malformed skill).

Loading a skill into an agent

Skills are never globally active — an agent loads one explicitly, and its tools register under a <skill-name>/<tool> namespace:

class WebAgent(Agent):
    SKILL_DIRS = ["<package>/skills"]     # optional: bundle your own skills

    def _register_tools(self):
        self.load_skill("web-research")   # tools land under 'web-research/'

Or declare them in the agent’s gaia-agent.yaml and write no Python at all:

id: web
name: Web Research
version: 0.1.0
language: python

skills:
  - name: web-research
    version: ">=1.0.0"
    required: true
  - name: incident-review
    version: ">=0.1.0"
    required: false      # optional enhancement; the agent runs without it

Every Agent subclass resolves this block at construction, so a custom agent under ~/.gaia/agents/<id>/ consumes an installed hub skill by dropping a gaia-agent.yaml beside its agent.py — no code change, no registration call. Resolution mirrors agent dependencies:: highest installed version satisfying the range, tool providers ordered before their consumers, and fail-loud on a conflict or a dependency cycle. A missing required: true skill raises with the gaia skill install command that fixes it; a missing optional one is logged and skipped. Set AUTOLOAD_DECLARED_SKILLS = False on the class to opt out and call load_declared_skills() yourself.

A skill declaring a local-capability permission is refused, not sandboxed. network and mcp permissions bridge to the connector grant model and load fine. filesystem, shell, database, desktop, and env need the permission sandbox, which is deferred (#1019) — until then load_skill fails with an actionable error rather than loading the skill unenforced.

search / install / remove / publish shipped with the marketplace (#2467); gaia skill migrate (OpenClaw / Hermes import) shipped with #692; skill_sets: is #2466.

→ Agent Skills Spec · → Skill Format Reference

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.

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 — not supported yet, rejected at add time; 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:

gaia schedule add \
  --name morning-brief \
  --cron "0 7 * * 1-5" \
  --prompt "Give me a 3-bullet summary of today's priorities"

gaia schedule list

gaia schedule run morning-brief

gaia schedule pause morning-brief
gaia schedule resume morning-brief

gaia schedule daemon

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:

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

--skill is not yet implemented — gaia schedule add --skill is rejected with an error at add time. The skills runtime has shipped (#888), but the scheduler is not wired to it yet. Use --prompt for now.

Utility Commands

Stats Command

View performance statistics from the most recent model run.

gaia stats [OPTIONS]

Test Commands

Run various tests for development and troubleshooting.

gaia test --test-type TYPE [OPTIONS]

TTS Tests
ASR 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:

gaia test --test-type tts-preprocessing --test-text "Hello, world!"

Test streaming:

gaia test --test-type tts-streaming --test-text "Testing streaming"

Generate audio file:

gaia test --test-type tts-audio-file \
  --test-text "Save this as audio" \
  --output-audio-file speech.wav

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:

gaia test --test-type asr-file-transcription \
  --input-audio-file ./data/audio/test.m4a

Test microphone (30 seconds):

gaia test --test-type asr-microphone --recording-duration 30

List audio devices:

gaia test --test-type asr-list-audio-devices

YouTube Utilities

Download transcripts from YouTube videos.

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_.txt)

Example:

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 supervises agent sidecars (spawn, health, tree-kill; email is the first) and that later Agent UI v2 phases (/host/v1/* custody, the model-slot broker, the scheduler clock) mount into. The Agent UI backend is a daemon client: it asks the daemon to ensure a sidecar and talks to the sidecar directly, so closing the UI leaves the sidecar running — stopping is a daemon command. The daemon also serves a streaming data plane: ANY /v1/<agent>/* (e.g. POST /v1/email/query) is reverse-proxied to that agent’s running sidecar, SSE relayed unbuffered, with cancel propagated on client disconnect and a synthetic terminal error event if the sidecar crashes mid-stream. Clients authenticate every route — control plane and data plane alike — with the daemon client token from ~/.gaia/host/instance.json; the per-sidecar bearer is injected by the daemon and never leaves it for relayed traffic. 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.

Model-slot serialization

Lemonade is single-tenant per model slot: a second process loading a different model evicts the first. The daemon therefore runs a model-slot broker that hands out one lease at a time, so model loads queue instead of racing. When a daemon is running, gaia commands and the Agent UI backend attach to it automatically and take a lease around each model load — you may see a brief ⏳ switching model… while another process finishes. Interactive chat turns take priority over background work (embedder warm-ups, autonomous briefs). With no daemon running, nothing changes: there are no sidecars, nothing else holds the slot, and loads proceed directly. Attaching never starts a daemon. If the daemon is running but unreachable, a model load fails loudly rather than doing a direct load that would evict another process’s model — check gaia daemon status. A daemon left running at an incompatible version is reported as a warning and loads proceed unbrokered; gaia daemon restart restores serialization.

gaia daemon start      # start the daemon, or attach if one is already running
gaia daemon status     # pid, port, uptime + the supervised sidecar list
gaia daemon stop       # graceful shutdown (tree-kills daemon + every sidecar)
gaia daemon restart    # stop then start
gaia daemon logs [--lines N] [--follow]   # tail the daemon log
gaia daemon agents                        # list supervised sidecar agents
gaia daemon start-agent email [--mode user|dev] [--dev-src-dir <path>]  # start/attach one sidecar
gaia daemon stop-agent email              # stop one sidecar, daemon stays up

Action	Options	Description
`start`	—	Start the daemon or attach to the running one (two callers → one daemon).
`status`	—	Print pid / port / uptime and the supervised sidecar list, or report if no daemon is running.
`stop`	—	Shut the daemon down (tree-killing every sidecar) and release `~/.gaia/host/instance.json`.
`restart`	—	`stop` followed by `start`.
`logs`	`--lines`, `--follow`	Print (or stream) the daemon log tail.
`agents`	—	List every registered sidecar agent: id, state, and (when running) mode, pid, port, contract version — never the bearer token. Dev-mode entries also show their source dir; user-mode and stopped entries always report `dev_src_dir: null`.
`start-agent <id>`	`--mode user\|dev`, `--dev-src-dir <path>`	Start (or attach to) one agent’s sidecar, auto-starting the daemon if needed. Requesting a mode different from the running sidecar’s is a loud conflict — stop it first. For `--mode dev`, this shell’s own checkout is resolved (via `git rev-parse --show-toplevel`, or the explicit `--dev-src-dir` escape hatch) and compared — never executed — against the checkout the daemon is already anchored to; a mismatch is refused loudly, naming both checkouts and the fix (restart the daemon from a Python environment/editable install rooted at your checkout — a per-user daemon otherwise silently serves whichever checkout launched it, regardless of where you run the CLI from).
`stop-agent <id>`	—	Tree-kill one agent’s sidecar; the daemon keeps running. Attach-only: no daemon running → clear error, exit 1. A sidecar surviving the kill is a loud failure, never silent.

Daemon HTTP surface (the daemon serves no OpenAPI schema, so this is the contract; every route needs Authorization: Bearer <token> from ~/.gaia/host/instance.json):

Route	Purpose
`GET /daemon/v1/status`	pid / port / uptime / API version
`POST /daemon/v1/shutdown`	graceful drain + exit
`GET /daemon/v1/agents`	registered sidecars — never the bearer token
`POST /daemon/v1/agents/{id}/ensure`	spawn-or-attach; the body carries the sidecar token
`POST /daemon/v1/agents/{id}/stop`	tree-kill + verify the pid is gone
`GET /daemon/v1/catalog`	Agent Hub catalog merged with local install state (`?refresh` / `?installed_only` / `?include_unsupervised`)
`POST /daemon/v1/agents/{id}/install`	202, queue an install (`{"version": "...", "trusted": true}`, both optional; `trusted` defaults to false → 403 for a non-verified agent)
`GET /daemon/v1/agents/{id}/install-status`	poll `queued\|running\|completed\|failed` + `error`
`DELETE /daemon/v1/agents/{id}`	stop the sidecar, verify, then remove the install dir
`ANY /v1/<agent>/*`	relay to that agent’s sidecar (SSE streamed unbuffered)

Hub Command

Browse, install and uninstall agents from the GAIA Agent Hub. gaia hub is a thin client over the daemon’s install routes, so the CLI, the Agent UI and the TUI share one installer, one SHA-256 check and one install lock — installing from two places at once is a clean 409, never a corrupt download. The daemon is started automatically if it is not already running. Agents install into ~/.gaia/agents/<id>/ (binary + gaia-agent.yaml + .installed sentinel). Every artifact is verified against the SHA-256 in the hub manifest before it is written; a mismatch fails the install and leaves nothing behind — there is no “use it anyway” path.

gaia hub list                      # catalog + which agents are installed
gaia hub list --installed          # only what is installed (works offline)
gaia hub list --refresh            # bypass the 5-minute catalog cache
gaia hub install email --trust     # required: email is a non-verified agent
gaia hub install email --version 0.5.0 --trust
gaia hub uninstall email           # stops the sidecar first, then removes the dir

Action	Options	Description
`list`	`--installed`, `--refresh`	Print id, latest version, installed version (`↑` when an update is available), download size and name. Warns when the hub was unreachable and the cached catalog was used. `--installed` is answered from the local `.installed` sentinels and needs no network.
`install <id>`	`--version`, `--trust`	Download + verify + install, printing each phase. Exit 1 on any failure, with the reason. `--trust` is required for any agent outside the `verified` security tier.
`uninstall <id>`	—	Stop the agent’s sidecar, verify its pid is gone, then remove `~/.gaia/agents/<id>/`.

Notes

Install and uninstall both stop a running sidecar first — the install directory is the sidecar’s binary cache — and keep it stopped for the whole operation, so nothing can respawn it mid-download. If the process survives the tree-kill, the command aborts loudly and nothing is mutated.
Install and uninstall of the same agent are serialized: the second caller gets a clean “already in progress” error instead of racing the first.
The catalog only lists agents this GAIA build can actually supervise; anything else is reported as hidden rather than silently dropped.
Reserved built-in agents (e.g. builder) ship with the wheel and are refused by both install and uninstall.
Trust gate. Any agent outside the verified security tier runs third-party code on your machine, so it is refused (HTTP 403) until you pass --trust, with the remedy named in the error. A manifest that omits security_tier counts as experimental and is gated the same way. Nothing infers the opt-in for you, and there is no bypass — a client (TUI, UI) renders this as a “Trust & Install” confirmation and retries with trusted: true.
Requires the daemon extras (pip install "amd-gaia[ui]"), same as gaia daemon.

gaia agent install <id> does the same install in-process; gaia hub install <id> routes it through the daemon, which additionally stops the agent’s running sidecar first and holds it stopped for the download. Prefer gaia hub when the daemon supervises that agent (today: email); gaia agent is the right call on a machine with no daemon extras installed. See the note under Agent Command.

Terminal hub (`gaia tui`)

gaia tui is the Go/Bubble Tea terminal hub: browse agents, install them, and chat with them without leaving the terminal. Building from source the binary is tui/bin/gaia (cd tui && make build).

The binary accepts a leading tui word and drops it, so gaia tui install email and gaia install email are the same command. Running the source build directly, both ./tui/bin/gaia tui list and ./tui/bin/gaia list work.

gaia tui                                  # open the hub
gaia tui list                             # what the Agent Hub offers + what you have
gaia tui list --installed                 # local only, no network call
gaia tui install email --trust            # download and install
gaia tui uninstall email                  # stop the agent and remove it
gaia tui run email                        # interactive chat
gaia tui run email --query "triage my inbox"   # one-shot: answer on stdout, exit 0/1/3
gaia tui status                           # background service + what is installed

Command	Description
`gaia tui`	Open the Agent Hub.
`gaia tui list [--installed]`	List agents with version, install state, download size, and security tier. `--installed` reads the local `~/.gaia/agents/*/.installed` sentinels and never touches the network.
`gaia tui install <id> [--version X] [--trust]`	Install an agent and wait for it to finish.
`gaia tui uninstall <id>`	Stop the agent’s sidecar, verify it is gone, remove its install directory.
`gaia tui run <id> [--query "…"] [--model M] [--timeout D]`	Run an agent. `--query` is a genuine one-shot, checked and bounded (`--timeout`, default 15m). It exits 0 when the agent answered and nothing reported a failure, 1 on an error or a tool failure nothing recovered, and 3 when a confirmation gate held back a destructive action the run cannot approve — nothing broke, and nothing was done.
`gaia tui status`	Whether the background service is running, which sidecars it knows, and what is installed.
`gaia tui chat --agent <id>` \| `--subprocess <cmd>`	Chat with an agent by catalog id, or with a binary you spawn directly. With `--agent --query` it is the same one-shot `gaia tui run --query` is, `--timeout` included.
`gaia tui hub`	The hub screen explicitly (same as bare `gaia tui`).

Install and uninstall are served by the GAIA daemon (POST /daemon/v1/agents/{id}/install, DELETE /daemon/v1/agents/{id}), so the TUI, gaia hub, and the Agent UI share one integrity check and one install lock. The daemon is started automatically for these commands; gaia tui status only ever attaches, so it reports what is running rather than starting something.

`--trust`: installing a non-verified agent

An agent outside the verified security tier runs third-party code on your machine. The daemon refuses to install one with HTTP 403 until the caller passes an explicit opt-in — there is no bypass, and nothing retries on your behalf. From the CLI, that opt-in is --trust. Without it the command prints exactly what you would be agreeing to and exits non-zero:

$ gaia tui install email

Refusing to install "email" without --trust.

  Agent       email
  Version     0.5.0
  Publisher   AMD
  Security    experimental (not verified by AMD)
  Download    31.1 MB
  Access      none declared

If you trust the publisher, re-run:
  gaia tui install email --trust

In the hub screen the same refusal opens a Trust & Install confirmation showing the same facts. It defaults to Cancel, and only an explicit yes re-sends the request with the opt-in.

`run --query` is a real one-shot

--query does not open the alt screen. The answer goes to stdout, progress to stderr, and the exit code is 0 on a terminal answer / 1 on an error — so gaia tui run email --query "…" > answer.txt captures exactly the answer:

gaia tui run email --query "how many unread?" > answer.txt 2> progress.log
echo $?   # 0

It never waits on something that is not there. Before the query is sent, a one-shot over the daemon transport (the agents the background service supervises) runs the same readiness check the hub’s launch gate runs — background service, sidecar, local model server, model, and for email the mailbox — and if one of them is not ready it prints that row and its remedy to stderr and exits non-zero. Against an unreachable dependency that is about a second; the ceiling is the time it takes to start the sidecar. Nothing is sent to the agent, and the gate screen is never rendered: a script has nobody to press a key. An agent that runs as a local subprocess has no readiness route to probe, so it is launched directly.

$ gaia tui run email --query "triage my inbox"   # with the model server down
❌ Email is not ready — Local AI: not running at http://localhost:8000/api/v1
   GAIA needs a local model server. It runs on your machine; no message text ever leaves it.
…
        run: lemonade-server serve
$ echo $?   # 1, after about a second

The turn itself is bounded — 15 minutes by default, --timeout 90s / --timeout 2h to change it — so an agent that accepts the query and then stops answering is reported with what to read next instead of hanging a CI job until the job’s own timeout kills it. There is no “wait forever”: --timeout 0 is refused. Interactive gaia tui run <id> is unaffected — a person can read what arrives and press ctrl+c.

Hub keys

Key	Action
`enter`	Run the selected agent
`i`	Install it (or update it, when a newer version exists)
`d`	Uninstall it (asks first)
`r`	Refresh the agent list from the Agent Hub
`/`	Search
`tab` / `shift+tab`	Next / previous category
`v`	Vote for a coming-soon agent
`?`	Help
`q`, `ctrl+c`	Quit

backspace is deliberately unbound. It used to share the uninstall binding with d and delete, which made “go back” a destructive action.

Waiting on a consequential readiness problem

Most readiness rows that cannot be verified are named on screen and the launch continues — the sidecar itself does not treat them as fatal (an unadvertised Lemonade version, for instance). A handful are consequential enough to hold instead: right now, a model loaded into a smaller context window than this machine’s profile expects, since a document-sized request against it comes back context_length_exceeded rather than an answer. When that happens the screen waits for enter instead of proceeding on its own, and the notice lists every such row at once if more than one applies.

Theme (light vs dark terminals)

The hub asks the terminal for its background colour on startup and picks a light or dark palette to match, so text stays readable either way. Over SSH, inside tmux, or in a CI log where the terminal never answers that query, force a mode instead of guessing:

GAIA_TUI_THEME=light gaia tui    # or: dark

GAIA_TUI_THEME also accepts auto (the default) to re-enable detection.

TUI Control API

The terminal hub (gaia tui, the Go/Bubble Tea binary) can expose a loopback HTTP API that drives the session you are looking at — not a headless copy. An assistant navigates, types, and launches agents while the frames render in your terminal in real time. It is how the TUI gets tested without a human at the keyboard. Off by default. Bound to 127.0.0.1 only, and every request needs a bearer token.

gaia tui --control                 # auto-assign a port
gaia tui --control-port 8770       # explicit port (implies --control)
gaia tui --control --debug         # log every injected key, state change, and wait

These are persistent flags on the TUI binary’s root command, so they apply to the hub, hub, and chat alike. Building from source, that binary is tui/bin/gaia (cd tui && make build).

Flag	Type	Default	Description
`--control`	flag	off	Start the control API on an auto-assigned loopback port.
`--control-port`	integer	`0`	Bind a specific port. Implies `--control`. `0` auto-assigns. Port `4001` is reserved and rejected.
`--debug`	flag	off	Log every injected key, state transition, and wait resolution/timeout to stderr.

On start the TUI writes ~/.gaia/tui/control.json (mode 0600) holding the pid, port, and token, and removes it on exit. Clients find the TUI by reading that file — the token is never printed to the terminal. A client must verify both that the recorded pid is alive and that /control/v1/status answers with a matching pid before trusting the port: after a crash the file can point at a port some unrelated process now owns.

Anything that can read ~/.gaia/tui/control.json can drive your TUI — the same trust boundary as ~/.gaia/host/instance.json for the daemon. Leave --control off unless you want a session driven.

Endpoints (all under /control/v1, all requiring Authorization: Bearer <token>):

Endpoint	Purpose
`GET /status`	`running` plus the active view, active agent, streaming, hub tab, selection, terminal size, and `can_return_to_hub`.
`GET /screen`	The current rendered frame. `?format=plain` (default, ANSI stripped) or `?format=ansi`.
`POST /keys`	Inject named keys — `{"keys": ["tab","down","enter"]}`.
`POST /text`	Type a string as runes — `{"text": "triage my inbox"}`.
`POST /wait`	Block until the screen or state matches, or time out. A timeout reports what the screen actually contained.
`GET /frames`	Recent rendered frames (`?since=N`), for debugging what happened.
`POST /resize`	Re-lay-out at a given size — `{"cols":120,"rows":40}`.

Errors come back as {"error": {"code", "message", "hint"}}; a /wait timeout is HTTP 408 and carries the screen it saw. Two response details matter when driving this:

settled on /keys, /text, and /resize. The call returns only once every injected key has been consumed and redrawn, so reading /screen straight after is race-free. settled: false means the model was still busy — the input is queued, so re-read rather than assume it was ignored. It does not promise the consequences are done: pressing enter to launch an agent is consumed immediately, while the view switch it kicks off lands later. Use /wait for anything asynchronous.
HTTP 503 not_running when the TUI’s event loop is not consuming input — it is still starting, or the user has quit. Bubble Tea silently drops messages in that window, so the API refuses instead of reporting a success for keys that went nowhere. Reads (/status, /screen, /frames) keep working.

can_return_to_hub exists because esc is not universally “go back”: in a chat opened from the hub it returns there, but in a standalone gaia chat --subprocess session it quits the program. A driver that guesses wrong kills the session it was asked to drive, so the state says which. Most callers should not speak this API directly — the TUI MCP server wraps it as MCP tools.

Hub Command

gaia hub list                      # catalog + which agents are installed
gaia hub list --installed          # only what is installed (works offline)
gaia hub list --refresh            # bypass the 5-minute catalog cache
gaia hub install email --trust     # required: email is a non-verified agent
gaia hub install email --version 0.5.0 --trust
gaia hub uninstall email           # stops the sidecar first, then removes the dir

Action	Options	Description
`list`	`--installed`, `--refresh`	Print id, latest version, installed version (`↑` when an update is available), download size and name. Warns when the hub was unreachable and the cached catalog was used. `--installed` is answered from the local `.installed` sentinels and needs no network.
`install <id>`	`--version`, `--trust`	Download + verify + install, printing each phase. Exit 1 on any failure, with the reason. `--trust` is required for any agent outside the `verified` security tier.
`uninstall <id>`	—	Stop the agent’s sidecar, verify its pid is gone, then remove `~/.gaia/agents/<id>/`.

Notes

Install and uninstall both stop a running sidecar first — the install directory is the sidecar’s binary cache — and keep it stopped for the whole operation, so nothing can respawn it mid-download. If the process survives the tree-kill, the command aborts loudly and nothing is mutated.
Install and uninstall of the same agent are serialized: the second caller gets a clean “already in progress” error instead of racing the first.
The catalog only lists agents this GAIA build can actually supervise; anything else is reported as hidden rather than silently dropped.
Reserved built-in agents (e.g. builder) ship with the wheel and are refused by both install and uninstall.
Trust gate. Any agent outside the verified security tier runs third-party code on your machine, so it is refused (HTTP 403) until you pass --trust, with the remedy named in the error. A manifest that omits security_tier counts as experimental and is gated the same way. Nothing infers the opt-in for you, and there is no bypass — a client (TUI, UI) renders this as a “Trust & Install” confirmation and retries with trusted: true.
Requires the daemon extras (pip install "amd-gaia[ui]"), same as gaia daemon.

Terminal hub (`gaia tui`)

gaia tui is the Go/Bubble Tea terminal hub: browse agents, install them, and chat with them without leaving the terminal. Building from source the binary is tui/bin/gaia (cd tui && make build).

gaia tui                                  # open the hub
gaia tui list                             # what the Agent Hub offers + what you have
gaia tui list --installed                 # local only, no network call
gaia tui install email --trust            # download and install
gaia tui uninstall email                  # stop the agent and remove it
gaia tui run email                        # interactive chat
gaia tui run email --query "triage my inbox"   # one-shot: answer on stdout, exit 0/1
gaia tui status                           # background service + what is installed

Command	Description
`gaia tui`	Open the Agent Hub.
`gaia tui list [--installed]`	List agents with version, install state, download size, and security tier. `--installed` reads the local `~/.gaia/agents/*/.installed` sentinels and never touches the network.
`gaia tui install <id> [--version X] [--trust]`	Install an agent and wait for it to finish.
`gaia tui uninstall <id>`	Stop the agent’s sidecar, verify it is gone, remove its install directory.
`gaia tui run <id> [--query "…"] [--model M] [--timeout D]`	Run an agent. `--query` is a genuine one-shot, checked and bounded (`--timeout`, default 15m).
`gaia tui status`	Whether the background service is running, which sidecars it knows, and what is installed.
`gaia tui chat --agent <id>` \| `--subprocess <cmd>`	Chat with an agent by catalog id, or with a binary you spawn directly. With `--agent --query` it is the same one-shot `gaia tui run --query` is, `--timeout` included.
`gaia tui hub`	The hub screen explicitly (same as bare `gaia tui`).

`--trust`: installing a non-verified agent

$ gaia tui install email

Refusing to install "email" without --trust.

  Agent       email
  Version     0.5.0
  Publisher   AMD
  Security    experimental (not verified by AMD)
  Download    31.1 MB
  Access      none declared

If you trust the publisher, re-run:
  gaia tui install email --trust

In the hub screen the same refusal opens a Trust & Install confirmation showing the same facts. It defaults to Cancel, and only an explicit yes re-sends the request with the opt-in.

`run --query` is a real one-shot

gaia tui run email --query "how many unread?" > answer.txt 2> progress.log
echo $?   # 0

$ gaia tui run email --query "triage my inbox"   # with the model server down
❌ Email is not ready — Local AI: not running at http://localhost:8000/api/v1
   GAIA needs a local model server. It runs on your machine; no message text ever leaves it.
…
        run: lemonade-server serve
$ echo $?   # 1, after about a second

Hub keys

Key	Action
`enter`	Run the selected agent
`i`	Install it (or update it, when a newer version exists)
`d`	Uninstall it (asks first)
`r`	Refresh the agent list from the Agent Hub
`/`	Search
`tab` / `shift+tab`	Next / previous category
`v`	Vote for a coming-soon agent
`?`	Help
`q`, `ctrl+c`	Quit

backspace is deliberately unbound. It used to share the uninstall binding with d and delete, which made “go back” a destructive action.

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

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:

gaia cache status

gaia cache clear --context7

gaia cache clear --all

Knowledge Command

Web research via Tavily, 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.

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:

gaia knowledge search "AMD ROCm latest release" --max-results 5

gaia knowledge extract https://example.com/post

gaia knowledge usage

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.

gaia kill [OPTIONS]

Options:

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

Examples:

gaia kill --lemonade

gaia kill --port 13305

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.

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:

gaia diagnostics
# → ~/.gaia/diagnostics-20260422-173000.tgz

gaia diagnostics --no-logs

gaia diagnostics --output /tmp/my-bundle.tgz

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

Connection Errors

If you get connection errors, ensure Lemonade server is running:

lemonade-server serve

Model Issues

Check available system memory (16GB+ recommended)Verify model compatibility:

gaia download --list

Pre-download models:

gaia download

Install additional models: See Features Guide

Audio Issues

List available devices:

gaia test --test-type asr-list-audio-devices

Verify microphone permissions in Windows settingsTry different audio device indices if default doesn’t work

Performance

For optimal NPU performance:

Disable discrete GPUs in Device Manager
Ensure NPU drivers are up to date
Monitor system resources during execution

For more help, see:

Code Agent

Python/TypeScript development

Blender Agent

3D scene creation

Voice Interaction

Speech-to-speech conversation

API Server

OpenAI-compatible REST API

MCP Integration

Model Context Protocol

Evaluation Framework

Testing and benchmarking

Agent Memory

Persistent memory across sessions

Agent Skills

Portable SKILL.md capabilities

​Platform Support

Windows 11

Linux

​Quick Start

​Top-Level Flags

​Agent step limit

​Per-tool execution timeout

​Confirming dangerous tools

​Initialization

​Init Command

​Install Command

​Uninstall Command

​Kill Command

​Agent Command

​Developer workflow: init, version, test

​Lifecycle: configure, health, status

​Distribution: pack, publish, login

Installing a published agent

Automated PyPI publishing (CI)

​Sharing: export, import

​Core Commands

​LLM Direct Query

​Chat Command

​Specialized Agent Commands

​Prompt Command

​Specialized Agents

​Code Agent

Code Development

​Code Index

​Blender Agent

3D Scene Creation

​Email Command

Email Triage

​gaia email autonomy — autonomy control

​SD Command

Image Generation

​Talk Command

Voice Interaction

​Jira Command

Jira / Atlassian

​Docker Command

Docker

​Summarize Command

​Telegram Command

Telegram Adapter

​API Server

API Server

​Quick Start

​Commands

​MCP Client

MCP Client

​Commands

​Managing MCP servers (add / remove)

​gaia mcp list

​gaia mcp tools

​gaia mcp test-client

​MCP Bridge

MCP Bridge

​Quick Start

​Commands

​gaia mcp start options

Authentication

​gaia mcp test options

​gaia mcp agent

​gaia mcp docker options

​gaia mcp tui options

​Connectors

Connectors

​Configuration

​Default model precedence

​Using a custom config file

​Model Management

​Download Command

​Pull Command

​Evaluation Commands

Evaluation Framework

​Agent Eval

Agent Eval Benchmark

​Email Throughput Benchmark

​Performance Visualization

Platform Support

Quick Start

Top-Level Flags

Agent step limit

Per-tool execution timeout

Confirming dangerous tools

Initialization

Init Command

Install Command

Uninstall Command

Kill Command

Agent Command

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

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

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

Sharing: `export`, `import`

Core Commands

LLM Direct Query

Chat Command

Specialized Agent Commands

Prompt Command

Specialized Agents

Code Agent

Code Index

Blender Agent

Email Command

`gaia email autonomy` — autonomy control

SD Command

Talk Command

Jira Command

Docker Command

Summarize Command

Telegram Command

API Server

Quick Start

Commands

MCP Client

Commands

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

`gaia mcp list`

`gaia mcp tools`

`gaia mcp test-client`

MCP Bridge

Quick Start

Commands

`gaia mcp start` options

`gaia mcp test` options

`gaia mcp agent`

`gaia mcp docker` options

`gaia mcp tui` options

Connectors

Configuration

Default model precedence

Using a custom config file

Model Management

Download Command

Pull Command

Evaluation Commands

Agent Eval

Email Throughput Benchmark

Performance Visualization

Memory

Commands

Skills

Subcommands

Security tiers at install

`skill-lock.json`

Loading a skill into an agent

Schedule

Subcommands

`add` Options

Sinks

Utility Commands

Stats Command

Test Commands

YouTube Utilities

Daemon Command

Model-slot serialization

Hub Command

Terminal hub (`gaia tui`)