Skip to main content
The CLI follows a few consistent conventions:
  • stdout is structured JSON for every command — designed to be piped into other tools or read by your agent.
  • stderr carries human-readable status (progress, “saved to…”).
  • Exit codes signal the outcome:
CodeMeaning
0Success
1Transport error (network unreachable, bad response)
2Pending input (a question is waiting for a reply)
3Auth / validation / business error
Run gaia --help or gaia <command> --help at any time.

​
Commands at a glance

CommandWhat it does
gaia login / gaia logoutManage credentials
gaia initLink the current folder to a project
gaia appsList or create apps
gaia buildDrive the new-app build journey
gaia chatRefine an already-built app
gaia codeAuthor app code locally with validators
gaia importTurn a spreadsheet into an app’s data
gaia publishPublish a built app to a public URL

​
Credentials

gaia login                      # prompts for the key
gaia login --key gak_xxx_yyy    # non-interactive
gaia logout                     # delete stored credentials
FlagDescription
--key <key>Your gak_ API key (skips the prompt)
--api-base <url>Server URL (defaults to https://build.gainable.dev)
Credentials are stored at ~/.gainable/credentials. The GAINABLE_API_KEY and GAINABLE_API_BASE environment variables override the file.

​
init

Scaffold .gaia/ in the current folder so commands know which app they target. 
gaia init                  # pick a project interactively
gaia init --project <id>   # link a specific project
FlagDescription
--project <id>Use this project ID (skip the picker)
--forceOverwrite an existing .gaia/project.json

​
apps

gaia apps list             # list your apps (JSON)
gaia apps list -q sales    # filter by text
gaia apps create "My CRM"  # create an empty project

​
build

One command drives the whole new-app journey — a short contract conversation, then the deterministic build pipeline. What you pass decides the step. 
gaia build "I want a CRM for tracking SaaS deals"   # describe an idea
gaia build --reply "Classic"                        # answer a pending question
gaia build                                          # run the build pipeline
FlagDescription
--reply <label>Answer a pending question (repeatable; pairs in order)
--name <name>Name a newly auto-created project
--project <id>Target a specific project
--silentSend a silent kickoff message (used after an import)
In an empty folder, gaia build "your idea" auto-creates the project and writes .gaia/project.json — no prior gaia init needed. With no arguments, gaia build kicks off the build pipeline once the app’s spec is ready, streaming each stage as it completes.

​
chat

Refine an already-built app. The planner and Build Agent edit your views and routes and stream progress back. 
gaia chat "add a probability column to the deals table"
gaia chat --page deals "rename the Stage column to Pipeline Stage"
FlagDescription
--page <slug>Hint which page the change applies to
--project <id>Target a specific project
If the planner needs clarification it exits with a pending-input signal and a question; reply by running gaia chat "<your answer>" again.

​
Code mode (gaia code)

For when you want your agent (or you) to write the app code directly, with the same validator suite the Build Agent runs. Everything happens under a local app/ mirror; pushes are validated atomically. 
gaia code pull                     # download conventions + app mirror
gaia code status                   # show what changed locally
gaia code validate views/deals.ejs # run validators on a file
gaia code push --summary "Added a KPI strip to the deals view"
SubcommandWhat it does
gaia code pullBootstrap/refresh the local mirror, conventions, and read-only preflight
gaia code statusShow created/modified files vs. the server
gaia code validate [file]Run the full validator suite (≈100 rules)
gaia code push --summary "<recap>"Validate, write files to the server, register routes, and commit
gaia code push rejects the batch if validators fail or if the app changed on the server since you pulled. Fix the errors or gaia code pull and re-apply — don’t force past a validator.

​
import

Turn an Excel/CSV file into an app’s data, then build on top of it. 
gaia import upload ./data.xlsx     # start the import survey
gaia import state                  # peek at the current state
gaia import answer '{"choice":"keep"}'
gaia import finalize               # validate the proposed data plan
gaia import attach                 # create the dataset and attach it
gaia import cancel                 # drop the session
After gaia import attach, continue with the normal gaia build flow to design the app around your imported data.

​
publish

Publish a built app to its public https://<slug>.gainable.app URL — the same as the Publish button in the web app. 
gaia publish            # publish (or republish) and print the URL
gaia publish --status   # check publish state without deploying

​
Next steps

Claude Code plugin

Let Claude run these commands for you.

Codex plugin

Let Codex run these commands for you.