CLI Commands

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

Command	Description
`gaia init`	Full setup from scratch, clone repo, configure env, and initialize services
`gaia setup`	Configure an existing repository
`gaia start`	Start GAIA services in self-host mode
`gaia dev`	Run developer mode in Nx TUI (`mise dev`)
`gaia dev full`	Run developer mode + workers in Nx TUI (`mise dev:full`)
`gaia logs`	Stream logs for currently running services
`gaia stop`	Stop running GAIA services
`gaia status`	Check health and latency of GAIA services
`gaia --version`	Display the current CLI version
`gaia --help`	Show help and available commands

`gaia init`

Complete first-time setup.

gaia init

Options:

Flag	Description
`--branch <name>`	Clone a specific branch

gaia init --branch develop

The wizard walks through:

Prerequisites (Git and Docker; Mise only for developer mode)
Port conflict checks and alternatives
Repository setup
Environment setup (manual or Infisical)
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:

Flag	Description
`--build`	Rebuild Docker images before starting
`--pull`	Pull 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:

Flag	Description
`--force-ports`	Aggressively 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:

Detects the conflicting process
Suggests alternative ports
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

pnpm add -g @heygaia/cli

bun add -g @heygaia/cli

Uninstalling

Stop all services: gaia stop
Delete the repository directory
Remove CLI metadata: rm -rf ~/.gaia
Uninstall CLI:

npm uninstall -g @heygaia/cli

pnpm remove -g @heygaia/cli

bun remove -g @heygaia/cli

Troubleshooting

command not found: gaia

Reinstall globally and open a new terminal session:

npm install -g @heygaia/cli
gaia --help

pnpm add -g @heygaia/cli
gaia --help

bun add -g @heygaia/cli
gaia --help

Raw mode is not supported

The CLI requires an interactive terminal. Don’t run it in a non-TTY context.

Python 3 not found during setup

Install Python through Mise:

mise install python

Getting Started

Self-Hosting

CLI

Contributing

Bot Development

Conventions

Overview

All Commands

`gaia init`

`gaia setup`

`gaia start`

`gaia dev`

`gaia dev full`

`gaia logs`

`gaia stop`

`gaia status`

Port Conflict Handling

Upgrading

Updating GAIA

Updating the CLI

Uninstalling

Troubleshooting

​Overview

​All Commands

​gaia init

​gaia setup

​gaia start

​gaia dev

​gaia dev full

​gaia logs

​gaia stop

​gaia status

​Port Conflict Handling

​Upgrading

​Updating GAIA

​Updating the CLI

​Uninstalling

​Troubleshooting

Overview

All Commands

`gaia init`

`gaia setup`

`gaia start`

`gaia dev`

`gaia dev full`

`gaia logs`

`gaia stop`

`gaia status`

Port Conflict Handling

Upgrading

Updating GAIA

Updating the CLI

Uninstalling

Troubleshooting