Skip to main content

​
Overview

The GAIA CLI provides commands for managing your GAIA instance. All commands are interactive and run in your terminal.
Make sure you’ve installed the CLI globally so you can use the gaia command.

​
Quick Reference

gaia init          # Full setup from scratch
gaia setup         # Configure existing repo
gaia start         # Start all services
gaia stop          # Stop all services
gaia status        # Check service health
gaia --version     # Show CLI version
gaia --help        # Show all commands

​
All Commands

CommandDescription
gaia initFull setup from scratch — clone repo, install tools, configure env
gaia setupConfigure an existing repository
gaia startStart all services (auto-detects mode)
gaia stopStop all services gracefully
gaia statusCheck health and latency of all services
gaia --versionDisplay the current CLI version
gaia --helpShow help and available commands

​
gaia init

Complete first-time setup. Clones the repository, installs tools, configures environment variables, and optionally starts services. 
gaia init
Options:
FlagDescription
--branch <name>Clone a specific branch instead of the default
gaia init --branch develop
The interactive wizard walks through:
  1. Prerequisites - Checks Git, Docker, Mise (auto-installs Mise if missing)
  2. Port check - Detects conflicts and suggests alternatives
  3. Repository clone - Clones GAIA to your chosen directory
  4. Tool installation - Installs Node.js, Python, uv, Nx via Mise
  5. Environment setup - Choose setup mode and configure variables
  6. Project setup - Runs mise setup for dependencies and database seeding
  7. Service startup - Optionally starts services (skipped if already running)
Use gaia init on a fresh machine. If you’ve already cloned the repo, use gaia setup instead.

​
gaia setup

Configure an existing GAIA repository. Use when you need to set up or reconfigure environment variables and dependencies. 
cd /path/to/gaia
gaia setup
The setup flow:
  1. Detect repo - Finds the GAIA repository root automatically
  2. Prerequisites - Checks Git, Docker, Mise
  3. Port check - Detects conflicts
  4. Environment setup - Interactive env var configuration
  5. Project setup - Installs dependencies via mise setup
  6. Service startup - Optionally starts services (skipped if already running)
The setup command handles environment configuration automatically. For manual environment setup, see Environment Variables.

​
Setup Modes

During environment setup, you choose a mode:
Everything runs in Docker containers. Best for deployment and non-developers.
  • Backend, worker, and all databases run as Docker services
  • Web frontend is built and served via Next.js standalone
  • Uses container hostnames for service communication
Database services run in Docker, API and web run locally. Best for contributing.
  • Docker handles PostgreSQL, Redis, MongoDB, RabbitMQ, ChromaDB
  • API server runs with hot reload on port 8000
  • Web frontend runs with Turbopack on port 3000

​
Environment Variable Methods

Interactive prompts for each variable with descriptions, docs links, and defaults. Variables are auto-discovered from the codebase — no CLI updates needed when new variables are added.
Enter your Infisical credentials (token, project ID, machine identity) for centralized secret management.

​
gaia start

Start all GAIA services. Automatically detects selfhost vs developer mode from your .env configuration. 
gaia start
Options:
FlagDescription
--buildRebuild Docker images before starting
--pullPull latest base images before starting
Flags can be combined: gaia start --build --pull Self-Host mode:
  • Runs docker compose --profile all up -d for the full backend stack
  • Builds and starts the web frontend
  • Everything runs in Docker containers (background)
Developer mode:
  • Runs mise dev to start API and web in development mode
    • Logs are written to dev-start.log in the repo root — monitor with tail -f dev-start.log
  • Databases run in Docker
  • API and web run locally with hot reload
After starting, access GAIA at:

​
gaia stop

Stop all running GAIA services gracefully. 
gaia stop
What it stops:
  • All Docker containers in the GAIA compose stack
  • Local processes on ports 8000 (API) and 3000 (Web)
  • Background workers and services
Your data is preserved — stopping services doesn’t delete databases or configurations.

​
gaia status

Check the health and latency of all GAIA services in real-time. 
gaia status
Services checked:
ServicePortCheck
API8000HTTP GET /health
Web3000HTTP GET /
PostgreSQL5432TCP connection
Redis6379TCP connection
MongoDB27017TCP connection
RabbitMQ5672TCP connection
ChromaDB8080TCP connection
Interactive controls:
  • Press r to refresh status manually
  • Status indicators: ✓ (healthy), ✗ (down), - (checking)
  • Shows response time in milliseconds for each service

​
Port Conflict Handling

If required ports are in use, the CLI:
  1. Detects which process is using the port
  2. Suggests an alternative port
  3. Automatically updates your .env files with the alternative
Port overrides are saved to infra/docker/.env inside your GAIA repo and persist across gaia start/gaia stop cycles — no need to re-run setup. gaia status automatically uses the same overridden ports for health checks. To change port assignments after setup, edit infra/docker/.env directly:
VariableService
API_HOST_PORTAPI (default 8000)
WEB_HOST_PORTWeb (default 3000)
POSTGRES_HOST_PORTPostgreSQL (default 5432)
REDIS_HOST_PORTRedis (default 6379)
MONGO_HOST_PORTMongoDB (default 27017)
RABBITMQ_HOST_PORTRabbitMQ (default 5672)
CHROMA_HOST_PORTChromaDB (default 8080)
Restart services after editing: gaia stop && gaia start

​
Environment Variable Auto-Discovery

The CLI discovers environment variables directly from the codebase at runtime:
  • API variables - Extracted from apps/api/app/config/settings.py and settings_validator.py using Python AST parsing
  • Web variables - Parsed from apps/web/.env
When a developer adds a new variable to either location, the CLI picks it up automatically.

​
Upgrading

​
Updating GAIA

Pull the latest code in your GAIA repo directory: 
cd /path/to/gaia
git pull
If dependencies changed, re-run setup: 
gaia setup

​
Updating the CLI

Reinstall globally using your package manager: 
# npm
npm install -g @heygaia/cli

# pnpm
pnpm add -g @heygaia/cli

# bun
bun add -g @heygaia/cli

​
Uninstalling

To fully remove GAIA from your machine:
  1. Stop all services: gaia stop
  2. Delete the GAIA repository directory
  3. Remove CLI metadata: rm -rf ~/.gaia
  4. Uninstall the CLI:
# npm
npm uninstall -g @heygaia/cli

# pnpm
pnpm remove -g @heygaia/cli

# bun
bun remove -g @heygaia/cli

​
Troubleshooting

The gaia command requires global installation. Ensure the global bin directory is in your PATH:
# For npm installations
export PATH="$(npm config get prefix)/bin:$PATH"

# For bun installations
export PATH="$HOME/.bun/bin:$PATH"
Add this to your shell config file (~/.bashrc, ~/.zshrc, etc.) to make it permanent.
After adding to PATH, restart your terminal or run source ~/.zshrc (or ~/.bashrc).
The CLI requires an interactive terminal. Don’t run it in the background, in a pipe, or in a non-TTY context.
Port detection uses lsof which is available on macOS and most Linux distributions. Windows support requires WSL2.
Verify these files exist in your repository:
  • apps/api/app/config/settings_validator.py
  • apps/web/.env
The CLI requires Python 3 to discover API environment variables. Install it via Mise:
mise install python
Or ensure python3 is available on your PATH.
Check dev-start.log in your GAIA repo root for error output:
tail -f dev-start.log