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 with installer and desktop shortcuts

Linux

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

Quick Start

Windows
Linux

Follow the Getting Started Guide to install gaia CLI and lemonade LLM server
Double click the GAIA-CLI desktop icon to launch the command-line shell
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!"

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, chat, code, rag, 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, still checks version)

Available Profiles:

Profile	Models	Description	Approx Size
`minimal`	Qwen3-0.6B	Fast setup with lightweight model	~400 MB
`chat`	Qwen3-Coder-30B, nomic-embed, Qwen3-VL-4B	Interactive chat with RAG and vision	~25 GB
`code`	Qwen3-Coder-30B	Autonomous coding assistant	~18 GB
`rag`	Qwen3-Coder-30B, nomic-embed, Qwen3-VL-4B	Document Q&A with retrieval and vision	~25 GB
`all`	All models	All models for all agents	~26 GB

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

Examples:

gaia init

What It Does:

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

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

Uninstall GAIA components.

gaia uninstall [OPTIONS]

Options:

Option	Type	Description
`--lemonade`	flag	Uninstall Lemonade Server
`--models`	flag	Delete all downloaded models from HuggingFace cache
`--yes, -y`	flag	Skip confirmation prompts

Examples:

gaia uninstall --lemonade

The uninstall command automatically downloads the correct MSI version matching your installed Lemonade to ensure clean removal.

--models permanently deletes all models from ~/.cache/huggingface/hub/. Use with caution - you’ll need to re-download models after.

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.

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	Qwen3-Coder-30B-A3B-Instruct-GGUF	Model name to use
`--max-steps`	integer	10	Maximum conversation steps
`--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
`--stats`	flag	false	Show performance statistics
`--streaming`	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 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
`--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)
--background - Run in background
--debug - Enable debug logging

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

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
`agent`	Test MCP orchestrator agent
`docker`	Start Docker MCP server

→ 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

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-Coder-30B-A3B-Instruct-GGUF
   ⏳ [1/31] Qwen3-Coder-30B-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

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

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

​Initialization

​Init Command

​Install Command

​Uninstall Command

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

​Model Management

​Download Command

​Pull Command

​Evaluation Commands

Evaluation Framework

​Visualize Command

​Utility Commands

​Stats Command

​Test Commands

​YouTube Utilities

​Kill Command

​Global Options

​Troubleshooting

​See Also

Code Agent

Blender Agent

Voice Interaction

API Server

MCP Integration

Evaluation Framework

Platform Support

Quick Start

Initialization

Init Command

Install Command

Uninstall Command

Kill 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

Model Management

Download Command

Pull Command

Evaluation Commands

Visualize Command

Utility Commands

Stats Command

Test Commands

YouTube Utilities

Kill Command

Global Options

Troubleshooting

See Also