Skip to main content

​
CLI-Based Setup

The GAIA CLI is the primary way to set up GAIA. It handles repository setup, environment configuration, and service management through an interactive wizard.
For installation instructions, see CLI Installation. For the full command reference, see CLI Commands.

​
Quick Start

npm install -g @heygaia/cli

# Run the setup wizard
gaia init

# Clone a specific branch
gaia init --branch develop

​
What the Wizard Does

The gaia init command walks you through:
1

Prerequisites Check

Verifies Git and Docker are installed, then checks for port conflicts and suggests alternatives. Mise is only checked for developer mode.
2

Repository Setup

Clones the GAIA repository to your chosen directory with progress tracking.
3

Tool Installation (Developer Mode)

Installs required development tools (Node.js, Python, uv, Nx) via Mise.
4

Environment Configuration

Choose between Self-Host (Docker) or Developer Mode (Local), then configure environment variables either: - Manually: Interactive prompts for each variable with descriptions and defaults - Via Infisical: Enter your Infisical credentials for secret management
5

Project Setup

  • Self-Host mode: Builds/pulls and starts Docker services
  • Developer mode: Runs mise setup to install dependencies and initialize services

​
Already Have the Repo?

If you’ve already cloned GAIA and just need to configure it, use gaia setup instead: 
cd /path/to/gaia
gaia setup
This skips cloning and goes straight to environment configuration and project setup.

​
Running GAIA After Setup

# Self-host mode
gaia start

# Developer mode (Nx TUI)
gaia dev
gaia dev full

# Utilities
gaia logs
gaia status
gaia stop
gaia setup

​
Monitoring Logs

Use gaia logs to stream logs for currently running services. In developer mode, gaia dev runs in the foreground and shows Nx TUI output in the same terminal. Keep that terminal open, and use another terminal for gaia logs when needed.

​
Port Conflict Handling

If required ports are already in use, the CLI detects the conflict, shows which process is using the port, and suggests an alternative port. Infrastructure URLs in your .env files are automatically updated to use the alternative ports. Port overrides are saved to infra/docker/.env inside your GAIA repo and persist across restarts. To change port assignments after setup, edit infra/docker/.env directly:
VariableServiceDefault
API_HOST_PORTAPI8000
WEB_HOST_PORTWeb3000
POSTGRES_HOST_PORTPostgreSQL5432
REDIS_HOST_PORTRedis6379
MONGO_HOST_PORTMongoDB27017
RABBITMQ_HOST_PORTRabbitMQ5672
CHROMADB_HOST_PORTChromaDB8080
Restart services after editing: gaia stop && gaia start