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:8000/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.

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, 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`	Qwen3-0.6B	Fast setup with lightweight model	~400 MB
`sd`	SD-Turbo	Image generation with Stable Diffusion	~8 GB
`chat`	Qwen3.5-35B, nomic-embed, Qwen3-VL-4B	Interactive chat with RAG and vision	~25 GB
`code`	Qwen3.5-35B	Autonomous coding assistant	~18 GB
`rag`	Qwen3.5-35B, nomic-embed, Qwen3-VL-4B	Document Q&A with retrieval and vision	~25 GB
`mcp`	Qwen3.5-35B, nomic-embed, Qwen3-VL-4B	Model Context Protocol bridge server with vision	~25 GB
`vlm`	Qwen3-VL-4B	Image understanding and analysis	~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 (Qwen3.5-35B family) — there is no dedicated profile for each. Run gaia init --profile chat (or all) to prepare their dependencies.

All profiles also include the lightweight Qwen3-0.6B model used by gaia llm for quick queries.

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:8000/api/v1). The environment variable auto-detects remote mode when the hostname is not localhost/127.0.0.1/::1.

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

Manage custom agents installed under ~/.gaia/agents/. Supports exporting every custom agent into a single .zip bundle and importing 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

Prompt Command

Send a single prompt to a GAIA agent.

gaia prompt "MESSAGE" [OPTIONS]

Options:

Option	Type	Default	Description
`--model`	string	Qwen3-0.6B-GGUF	Model to use for the 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

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

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

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	SD-Turbo	Model: SD-Turbo (fast, default), SDXL-Turbo, SDXL-Base-1.0 (photorealistic), 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	Qwen3-0.6B-GGUF	Model to use
`--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

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.
--background - Run in background
--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

Background with debug:

gaia api start --background --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

`gaia mcp add`

Add an MCP server to configuration.

gaia mcp add <server-name> "<command>" [--config PATH]

Arguments:

<server-name> - Unique identifier for the server (e.g., “time”, “memory”)
"<command>" - Shell command to start the MCP server (must be quoted)

Options:

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

Examples:

# Add to user config (default)
gaia mcp add time "uvx mcp-server-time"
gaia mcp add memory "npx -y @modelcontextprotocol/server-memory"

# Add to project config (can be committed to git)
gaia mcp add time "uvx mcp-server-time" --config ./mcp_servers.json

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

Remove an MCP server from configuration.

gaia mcp remove <server-name> [--config PATH]

Arguments:

<server-name> - Name of the server to remove

Options:

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

Example:

# Remove from user config
gaia mcp remove time

# Remove from project config
gaia mcp remove memory --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

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

Ground Truth Generation
Automated Evaluation
Batch Experimentation
Performance Analysis
Transcript Testing

Quick Examples: Generate evaluation data:

gaia groundtruth -f ./data/document.html

Create sample experiment configuration:

gaia batch-experiment --create-sample-config experiments.json

Run systematic experiments:

gaia batch-experiment -c experiments.json -i ./data -o ./results

Evaluate results:

gaia eval -f ./results/experiment.json

Generate report:

gaia report -d ./eval_results

Launch visualizer:

gaia visualize

→ Full Evaluation Guide

Visualize Command

Launch interactive web-based visualizer for comparing evaluation results.

gaia visualize [OPTIONS]

Options:

Option	Type	Default	Description
`--port`	integer	3000	Visualizer server port
`--experiments-dir`	path	./output/experiments	Experiments directory
`--evaluations-dir`	path	./output/evaluations	Evaluations directory
`--workspace`	path	current directory	Base workspace directory
`--no-browser`	flag	false	Don’t auto-open browser
`--host`	string	localhost	Host address

Examples:

gaia visualize

Features:

Interactive Comparison (side-by-side)
Key Metrics Dashboard
Quality Analysis
Real-time Updates
Responsive Design

Node.js must be installed. Dependencies are automatically installed on first run.

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

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

Command Line

API & Development

Help

​Platform Support

Windows 11

Linux

​Quick Start

​Top-Level Flags

​Initialization

​Init Command

​Install Command

​Uninstall Command

​Kill Command

​Agent Command

​Core Commands

​LLM Direct Query

​Chat Command

​Prompt Command

​Specialized Agents

​Code Agent

Code Development

​Blender Agent

3D Scene Creation

​SD Command

Image Generation

​Talk Command

Voice Interaction

​API Server

API Server

​Quick Start

​Commands

​MCP Client

MCP Client

​Commands

​gaia mcp add

​gaia mcp list

​gaia mcp remove

​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

​Model Management

​Download Command

​Pull Command

​Evaluation Commands

Evaluation Framework

​Visualize Command

​Utility Commands

​Stats Command

​Test Commands

​YouTube Utilities

​Cache Command

​Kill Command

​Diagnostics Command

​Global Options

​Troubleshooting

​See Also

Code Agent

Blender Agent

Voice Interaction

API Server

MCP Integration

Evaluation Framework

Platform Support

Quick Start

Top-Level Flags

Initialization

Init Command

Install Command

Uninstall Command

Kill Command

Agent Command

Core Commands

LLM Direct Query

Chat Command

Prompt Command

Specialized Agents

Code Agent

Blender Agent

SD Command

Talk Command

API Server

Quick Start

Commands

MCP Client

Commands

`gaia mcp add`

`gaia mcp list`

`gaia mcp remove`

`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

Model Management

Download Command

Pull Command

Evaluation Commands

Visualize Command

Utility Commands

Stats Command

Test Commands

YouTube Utilities

Cache Command

Kill Command

Diagnostics Command

Global Options

Troubleshooting

See Also