GAIA

Appearance

Install the CLI ​

You'll learn how to get the gaia command onto your machine, what it installs, and how to upgrade it later.

gaia is the command-line client for GAIA. It ships on the public npm registry, so installing it takes one command and needs nothing but Node.js.

Prerequisites ​

  • Node.js ≥ 20.19 — check with node --version. Get it from nodejs.org or your version manager of choice.
  • npm, which ships with Node.

You do not need to clone anything, and you do not need pnpm or a TypeScript build. Those are for building from source.

Install ​

sh
npm install -g @gaia-ai/gaia

The unscoped name gaia was already taken on npm, so the package is scoped @gaia-ai/gaia. The executable it installs is plain gaia — every command in these docs is just gaia ….

What that installs ​

@gaia-ai/gaia is a meta package: it contains the CLI host and declares the rest of the CLI as ordinary dependencies. npm resolves and installs all of them for you:

PackageRole
@gaia-ai/gaiathe gaia executable and command host
@gaia-ai/corethe kernel: config resolution, registries, utilities
@gaia-ai/conductorthe run engine and the conductor command
@gaia-ai/uithe ui cockpit app
@gaia-ai/addon-*the pluggable parts: auth-basic, claude, codex, deployment, dropsh, essentials, gaia-ui, gaia-ui-artifacts, grok, herdr, kimi, opencode, pi, remote-drupal, workspace-git

Addons are real, separately published packages rather than code bundled inside one binary. That is what lets a config name the pieces it wants — addons: ['@gaia-ai/addon-remote-drupal', …] — and lets you publish your own addon against the same interfaces.

Verify ​

sh
gaia --help      # lists the commands
gaia version     # prints the installed version

gaia --help should list the four command plugins — conductor, ui, dropsh, deployment — alongside version and upgrade. If the command is not found at all, your npm global bin directory is probably not on $PATH; npm prefix -g tells you where npm put it.

The four commands ​

CommandWhat it is for
gaia conductorthe node agent: register this machine, claim tickets, run agents on them, and scaffold a project's config with gaia conductor init
gaia uithe interactive terminal cockpit — dashboard, projects, tickets, runs
gaia dropsha JSON:API shell against your control plane, for reading and writing entities directly
gaia deploymentrelease helpers — gaia deployment tickets lists the tickets a release carries

The host itself owns two more: gaia version and gaia upgrade.

TIP

Commands are mounted lazily — gaia --help lists all four but loads none of them, so start-up stays fast no matter how many addons you have installed.

The persistent executor gaia conductor uses by default is herdr, installed separately. You only need it once you actually run agents, not to install or explore the CLI.

Upgrading ​

Upgrading is two steps, in this order: update the code, then migrate the config.

sh
gaia update                   # 1. install the latest @gaia-ai/gaia from npm
gaia upgrade                  # 2. migrate your config to the shape it expects

gaia update is a convenience over npm — npm install -g @gaia-ai/gaia@latest does the same job if you want to be explicit about the version you land on. The conductor checks for a newer version once a day and prints a notice when one exists; gaia conductor start --no-update-check skips that check.

gaia upgrade is idempotent: run it any time, as often as you like. It brings your .gaia/ configuration files (both the project's and your home one) onto the current schema, backing up any file it rewrites. Preview it first if you want to see the plan without touching anything:

sh
gaia upgrade --dry-run

A config newer than your CLI

A repository's committed .gaia/gaia.config.js may name an addon your installed CLI does not know yet. Every gaia command then fails with no connection config could be loaded. The fix is the upgrade above — see Troubleshooting.

Next ​