Gainable CLI & plugins

The command-line control plane for the Gainable harness — build, refine, and publish AI-built apps from your terminal, or let your coding agent drive it.

This repo ships three things from one source of truth:

| | What | Where | |---|---|---| | gaia CLI | A thin HTTP client for the Gainable harness (@gainable.dev/cli) | bin/, src/ | | Claude Code plugin | gaia / gaia-code skills + /gainable:* commands | gainable/ | | Codex plugin | gaia / gaia-code skills, installed via marketplace | codex/ |

Full docs: https://docs.gainable.dev (CLI & plugins section).

Install the CLI

Requires Node.js 18+.

npm i -g "@gainable.dev/cli"
gaia --version

Authenticate with an API key from Account → API keys at build.gainable.dev:

gaia login --key gak_xxx_yyy
gaia apps list

Credentials are stored at ~/.gainable/credentials (0600). The GAINABLE_API_KEY and GAINABLE_API_BASE environment variables override the file.

Install a plugin

The CLI works on its own, but it shines when your coding agent drives it. The agent learns when to run gaia and forwards any questions back to you.

Claude Code

/plugin marketplace add gainable-inc/cli
/plugin install gainable@gainable

OpenAI Codex

codex plugin marketplace add gainable-inc/cli
# then, inside a codex session:
codex /plugins        # install "gainable"

Both plugins rely on the globally installed gaia from npm — they don't bundle a binary. See gainable/README.md and codex/README.md for the details and per-agent differences.

Commands

| Command | What it does | |---|---| | gaia login / gaia logout | Manage credentials | | gaia init | Link the current folder to a project | | gaia apps list / create | List or create apps | | gaia build "<idea>" | Drive the new-app build journey | | gaia chat "<change>" | Refine an already-built app | | gaia code pull / validate / push | Author app code locally with the same validators the harness uses | | gaia import upload <file> | Turn a spreadsheet into an app's data | | gaia publish | Publish a built app to <slug>.gainable.app |

Run gaia --help or gaia <command> --help for the full reference. Every command prints JSON to stdout (machine-readable) and human status to stderr.

Repo layout

.
├── bin/gaia.js                  CLI entry point
├── src/                         CLI source (commander; zero deps but commander)
├── package.json                 npm package: @gainable.dev/cli
├── gainable/                    Claude Code plugin
│   └── .claude-plugin/, skills/, commands/, hooks/, settings.json
├── codex/                       Codex plugin
│   └── .codex-plugin/, skills/, hooks/
├── .claude-plugin/marketplace.json   Claude Code marketplace entry → ./gainable
└── .agents/plugins/marketplace.json  Codex marketplace entry → ./codex

Development

git clone https://github.com/gainable-inc/cli.git && cd cli
bun install      # or: npm install
bun link         # puts `gaia` on your PATH from source

• CLI changes (src/) ship via npm: bump package.json, then npm publish --access public.
• Plugin/skill changes (gainable/, codex/) ship via git — push to main, then /plugin update gainable (Claude Code) or codex plugin marketplace upgrade (Codex).

License

Proprietary © Gainable, Inc. — source-available, governed by the Gainable Terms of Service. See LICENSE.