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

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, vlm, 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, nomic-embed-text-v2-moe-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, nomic-embed-text-v2-moe-GGUF	Document Q&A with retrieval	~4 GB
`vlm`	Gemma-4-E4B-it-GGUF	Vision pipeline for document and image extraction	~3 GB
`npu`	gemma4-it-e2b-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

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) and Linux (DEB) only. macOS users should install Lemonade Server 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

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

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

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

gaia agent init <name> [--language python|cpp] [--output DIR] [--force]
gaia agent version <patch|minor|major> [--path DIR]
gaia agent test [--lint | --live] [--path DIR] [--timeout SECONDS]

init scaffolds a package directory named after <name>:

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

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

version bumps the SemVer in gaia-agent.yaml and keeps pyproject.toml / __init__.py in sync. test runs quality gates in two modes:

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

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

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

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

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

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

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

Automated PyPI publishing (CI)

.github/workflows/publish_agents.yml builds every production agent wheel and publishes it to PyPI on a version tag (v*). Its matrix is derived from the agents extra in setup.py (via util/list_agent_packages.py), so adding an agent there is all it takes to start publishing it. The workflow uploads with pypa/gh-action-pypi-publish 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

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

Examples:

gaia llm "What is machine learning?"

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

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"

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)
`--max-tokens`	integer	512	Maximum tokens to generate
`--stats`	flag	false	Show performance statistics

Examples:

gaia prompt "What is the weather like today?"

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

→ 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	5	Maximum number of steps per query
`--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).

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

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 generation with default (SD-Turbo, ~13s):

gaia sd "a sunset over mountains"

Better quality with SDXL-Turbo (~17s):

gaia sd "cyberpunk city at night" --sd-model SDXL-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

→ 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

Shows whether the API server is running and displays connection information.

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)

`gaia mcp start` options

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

`gaia mcp test` options

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

`gaia mcp agent`

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.

→ 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

→ Connectors Guide · → Connectors SDK

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	Remove cached download progress/metadata before running

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

✅ nomic-embed-text-v2-moe-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
`--model`	string	`claude-sonnet-4-6`	Judge/simulator model
`--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

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)
`--save-baseline`	flag	off	Save this run’s scorecard as the throughput baseline

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

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

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

Re-run system discovery:

gaia memory bootstrap --discover

Reset discovered items:

gaia memory bootstrap --reset

→ Full Memory Guide · → Memory SDK Reference

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

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

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

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

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

​Platform Support

Windows 11

Linux

​Quick Start

​Top-Level Flags

​Agent step limit

​Per-tool execution timeout

​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

​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

​gaia mcp test options

​gaia mcp agent

​gaia mcp docker options

​Connectors

Connectors

​Model Management

​Download Command

​Pull Command

​Evaluation Commands

Evaluation Framework

​Agent Eval

Agent Eval Benchmark

​Email Throughput Benchmark

​Performance Visualization

​Memory

Agent Memory Guide

​Commands

​Utility Commands

​Stats Command

​Test Commands

​YouTube Utilities

Platform Support

Quick Start

Top-Level Flags

Agent step limit

Per-tool execution timeout

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

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

Connectors

Model Management

Download Command

Pull Command

Evaluation Commands

Agent Eval

Email Throughput Benchmark

Performance Visualization

Memory

Commands

Utility Commands

Stats Command

Test Commands

YouTube Utilities

Cache Command

Kill Command

Diagnostics Command

Global Options

Troubleshooting

See Also