Skip to main content
The gaia command lives in packages/cli and is published to npm as @heygaia/cli. Self-hosters use it to install and run GAIA. Its commands are documented in the CLI reference. This page is for people changing the CLI itself.

​
The developer commands (optional)

The CLI also has an interactive wizard for setting up a source checkout. It runs the same steps as Set up GAIA for development, so use one or the other. gaia dev only works in a checkout that gaia init or gaia setup configured in developer mode. Otherwise it stops with Developer mode is not enabled for this repo. It has no --agent flag, so to skip sign-in, run mise dev --agent directly.

​
Try CLI changes on a fresh machine

mise run cli:try lets you test an unreleased CLI on a clean virtual machine, without CI and without publishing anything:
It builds and packs the CLI from your branch, builds the self-host bundle (the compose files and configuration gaia up downloads) with scripts/ci/release.sh selfhost-bundle, and serves both, plus packages/cli/install.sh, over HTTP on port CLI_TRY_PORT (default 8790). It then prints the command to paste in the VM:
host.orb.internal is how an OrbStack VM reaches your Mac. The script also prints the same command with your LAN address, for another machine on your network.
  • GAIA_CLI_TARBALL makes install.sh install that .tgz (an http(s) URL or an absolute path) instead of the npm package.
  • GAIA_BUNDLE_BASE_URL tells the CLI where to download the bundle and its .sha256 checksum.
  • GAIA_VERSION picks which published release’s Docker images to run. It defaults to the newest cli-v* tag, so nothing is built.
The installer and the CLI print a line for each of these overrides when set, so you can tell a test install from a real one.

​
How a CLI release ships

CLI versions are managed by release-please, a bot that keeps an open pull request bumping the version and changelog from the conventional commits merged since the last release. Releasing means merging that pull request for packages/cli. Automation does the rest, in order:
  1. build.yml publishes the gaia and gaia-web Docker images of the release commit, tagged with its commit SHA.
  2. publish-cli.yml checks out the cli-v<version> tag, then attaches the self-host bundle (gaia-selfhost-<version>.tar.gz and its .sha256) and the gaia-connect binaries to the GitHub Release. gaia up and gaia update download that bundle.
  3. It waits up to 30 minutes for the SHA-tagged images, then tags them v<version>, the version gaia update pins.
  4. Only then does it publish @heygaia/cli to npm.
If a step fails, fix the cause and re-run publish-cli.yml with the same inputs. Re-running it for a version already on npm still attaches the binaries and tags the images.
cli-v0.6.0 was released before images were tagged with their commit SHA, so backfilling it takes a one-time alias of that commit’s API image, then a re-run: