Skip to main content
The CLI is a single npm package, @gainable.dev/cli. It provides the gaia command and is the engine behind both the Claude Code and Codex plugins — install it once and it works everywhere.

​
Requirements

​
Step 1 — Install

1

Install the package globally

npm i -g "@gainable.dev/cli"
Keep the quotes — on Windows PowerShell an unquoted @gainable.dev is parsed as the splatting operator and the command never reaches npm. In bash/zsh the quotes are harmless.
2

Verify it's on your PATH

gaia --version
If gaia isn’t found, make sure your global npm bin directory is on your PATH.
To upgrade later, run npm update -g "@gainable.dev/cli".

​
Step 2 — Get an API key

The CLI authenticates with an API key tied to your account.
1

Open your account settings

Go to build.gainable.dev and open Account → API keys.
2

Create a key

Mint a new key. It starts with gak_. Copy it — you’ll only see it once.

​
Step 3 — Log in

gaia login
# paste your gak_... key when prompted

gaia login --key gak_xxx_yyy

echo "$GAINABLE_API_KEY" | gaia login
Your credentials are stored at ~/.gainable/credentials (mode 0600). The default server is https://build.gainable.dev.
Environment variables override the stored file, which is handy in CI:
  • GAINABLE_API_KEY — your gak_ key
  • GAINABLE_API_BASE — the server URL (defaults to https://build.gainable.dev)

​
Step 4 — Confirm it works

gaia apps list
You should see your apps printed as JSON. That’s it — the CLI is ready.

​
Next: add a plugin

The CLI is useful on its own, but it really shines when your coding agent drives it. Pick your agent:

Claude Code

Install the Gainable plugin in Claude Code.

OpenAI Codex

Install the Gainable plugin in Codex.

​
Per-project setup

Inside a folder for a specific app, run: 
gaia init
This writes a small .gaia/project.json that links the folder to one of your Gainable projects, so commands like gaia chat and gaia code know which app they’re working on. You’ll pick a project from a list (or pass --project <id>). It also seeds .codex/rules/gaia.rules, so Codex runs gaia commands without approval prompts in that workspace.
You don’t have to run gaia init for a brand-new app — gaia build "your idea" in an empty folder auto-creates the project for you. See the command reference.