Skip to main content

​
Overview

The GAIA CLI provides commands for setup, running, logs, health checks, and shutdown. 
gaia init          # Full setup from scratch
gaia setup         # Configure existing repo
gaia start         # Start self-host services
gaia dev           # Developer mode (Nx TUI)
gaia dev full      # Developer mode + workers (Nx TUI)
gaia logs          # Stream logs
gaia stop          # Stop 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, configure env, and initialize services
gaia setupConfigure an existing repository
gaia startStart GAIA services in self-host mode
gaia devRun developer mode in Nx TUI (mise dev)
gaia dev fullRun developer mode + workers in Nx TUI (mise dev:full)
gaia logsStream logs for currently running services
gaia stopStop running GAIA services
gaia statusCheck health and latency of GAIA services
gaia --versionDisplay the current CLI version
gaia --helpShow help and available commands

​
gaia init

Complete first-time setup. 
gaia init
Options:
FlagDescription
--branch <name>Clone a specific branch
gaia init --branch develop
The wizard walks through:
  1. Prerequisites (Git and Docker; Mise only for developer mode)
  2. Port conflict checks and alternatives
  3. Repository setup
  4. Environment setup (manual or Infisical)
  5. Project setup

​
gaia setup

Configure an existing GAIA repository. 
cd /path/to/gaia
gaia setup
Use this when you need to reconfigure environment variables, change setup mode, or refresh setup.

​
gaia start

Start GAIA services in self-host mode. 
gaia start
Options:
FlagDescription
--buildRebuild Docker images before starting
--pullPull latest base images before starting
gaia start --build --pull
In developer mode, use gaia dev or gaia dev full instead of gaia start.

​
gaia dev

Run developer mode in Nx TUI (foreground). 
gaia dev
Equivalent underlying command: mise dev

​
gaia dev full

Run developer mode + workers in Nx TUI (foreground). 
gaia dev full
Equivalent underlying command: mise dev:full

​
gaia logs

Stream logs for currently running services. 
gaia logs
  • Self-host mode: streams Docker service logs.
  • Developer mode: streams Docker logs and, when available, app logs.

​
gaia stop

Stop running GAIA services. 
gaia stop
Options:
FlagDescription
--force-portsAggressively stop listeners on API/Web ports (may affect non-GAIA processes)
gaia stop --force-ports
By default, gaia stop runs in safe mode and only targets GAIA-managed processes.

​
gaia status

Check health and latency of GAIA services. 
gaia status

​
Port Conflict Handling

If required ports are in use, the CLI:
  1. Detects the conflicting process
  2. Suggests alternative ports
  3. Writes overrides to infra/docker/.env
Overrides persist across restarts and are reused by gaia start, gaia logs, and gaia status.

​
Upgrading

​
Updating GAIA

cd /path/to/gaia
git pull
gaia setup

​
Updating the CLI

npm install -g @heygaia/cli

​
Uninstalling

  1. Stop all services: gaia stop
  2. Delete the repository directory
  3. Remove CLI metadata: rm -rf ~/.gaia
  4. Uninstall CLI:
npm uninstall -g @heygaia/cli

​
Troubleshooting

Reinstall globally and open a new terminal session:
npm install -g @heygaia/cli
gaia --help
The CLI requires an interactive terminal. Don’t run it in a non-TTY context.
Install Python through Mise:
mise install python