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

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	Qwen2.5-0.5B-Instruct-CPU	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

Talk Command

Voice Interaction

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

gaia talk [OPTIONS]

Options:

Option	Type	Default	Description
`--model`	string	Qwen2.5-0.5B-Instruct-CPU	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 Bridge

MCP Integration

Model Context Protocol for external integrations

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

Download/install a specific model from the Lemonade Server registry.

gaia pull MODEL_NAME [OPTIONS]

Options:

Option	Type	Description
`--checkpoint`	string	HuggingFace checkpoint (e.g., unsloth/Model-GGUF:Q4_K_M)
`--recipe`	string	Lemonade recipe (e.g., llamacpp, oga-cpu)
`--reasoning`	flag	Mark as reasoning model (like DeepSeek)
`--vision`	flag	Mark as having vision capabilities
`--embedding`	flag	Mark as embedding model
`--reranking`	flag	Mark as reranking model
`--mmproj`	string	Multimodal projector file for vision models
`--timeout`	integer	Timeout in seconds (default: 1200)
`--host`	string	Lemonade server host (default: localhost)
`--port`	integer	Lemonade server port (default: 8000)

Examples:

gaia pull Qwen3-0.6B-GGUF

Use the user. prefix for custom models not in the official registry. Custom models require both --checkpoint and --recipe parameters.

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

Example: Kill process on port 8000:

gaia kill --port 8000

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

​Core Commands

​LLM Direct Query

​Chat Command

​Prompt Command

​Specialized Agents

​Code Agent

Code Development

​Blender Agent

3D Scene Creation

​Talk Command

Voice Interaction

​API Server

API Server

​Quick Start

​Commands

​MCP Bridge

MCP Integration

​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

Core Commands

LLM Direct Query

Chat Command

Prompt Command

Specialized Agents

Code Agent

Blender Agent

Talk Command

API Server

Quick Start

Commands

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