> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heygaia.io/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Setup

> Set up GAIA using the interactive CLI wizard, which handles repository cloning, environment configuration, and service management.

## 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.

<Info>
  For installation instructions, see [CLI Installation](/cli/installation). For
  the full command reference, see [CLI Commands](/cli/commands).
</Info>

## Quick Start

<Snippet file="cli-install.mdx" />

```bash theme={null}
# 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:

<Steps>
  <Step title="Prerequisites Check">
    Verifies Git and Docker are installed, then checks for port conflicts and suggests alternatives. Mise is only checked for developer mode.
  </Step>

  <Step title="Repository Setup">
    Clones the GAIA repository to your chosen directory with progress tracking.
  </Step>

  <Step title="Tool Installation (Developer Mode)">
    Installs required development tools (Node.js, Python, uv, Nx) via Mise.
  </Step>

  <Step title="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
  </Step>

  <Step title="Project Setup">
    * Self-Host mode: Builds/pulls and starts Docker services
    * Developer mode: Runs `mise setup` to install dependencies and initialize services
  </Step>
</Steps>

## Already Have the Repo?

If you've already cloned GAIA and just need to configure it, use `gaia setup` instead:

```bash theme={null}
cd /path/to/gaia
gaia setup
```

This skips cloning and goes straight to environment configuration and project setup.

## Running GAIA After Setup

```bash theme={null}
# 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:

| Variable             | Service    | Default |
| -------------------- | ---------- | ------- |
| `API_HOST_PORT`      | API        | 8000    |
| `WEB_HOST_PORT`      | Web        | 3000    |
| `POSTGRES_HOST_PORT` | PostgreSQL | 5432    |
| `REDIS_HOST_PORT`    | Redis      | 6379    |
| `MONGO_HOST_PORT`    | MongoDB    | 27017   |
| `RABBITMQ_HOST_PORT` | RabbitMQ   | 5672    |
| `CHROMADB_HOST_PORT` | ChromaDB   | 8080    |

<Info>Restart services after editing: `gaia stop && gaia start`</Info>