CLI reference

Look up any ghaym command: its arguments, flags, exit codes and the JSON it prints.

For ghaym 0.0.21. To check your version or update it, see Install the CLI and sign in.

Command groups

GroupWhat it's for
ghaym configread and write CLI configuration
ghaym cloud workspacesmanage workspaces
ghaym cloud projectsmanage projects
ghaym cloud environmentsmanage environments
ghaym cloud servicesmanage services
ghaym cloud deploymentsinspect deployments
ghaym cloud changesstaged changes to an environment, published together
ghaym cloud topologyevery replica of every service
ghaym cloud rolloutsrolling deployments
ghaym cloud residencywhere each service, database and bucket runs, and the DPA for each country
ghaym cloud regionsregions and the sizes they sell
ghaym cloud engineswhat a database or cache can run
ghaym cloud varsmanage environment variables
ghaym cloud domainsmanage custom domains
ghaym cloud accesswho can reach a web service, per environment
ghaym cloud bucketsmanage object storage buckets
ghaym cloud billinginspect billing
ghaym cloud auditinspect the audit trail
ghaym cloud approvalsmanage approval gates
ghaym cloud sessionsinspect agent sessions
ghaym cloud gitthe GitHub App connection
ghaym helpextended help topics

With the CLI, get every command and flag in one call:

Terminal
ghaym help all --json

ghaym login

Sign this machine in, in the browser or with a piped API key.

Usage
ghaym login

ghaym logout

Sign this machine out and revoke its browser sign-in.

Usage
ghaym logout

ghaym whoami

Show the identity behind the active credential.

Usage
ghaym whoami

ghaym cloud init

Detect the framework and write ghaym.yaml.

Usage
ghaym cloud init [flags]
FlagWhat it does
--name <name>project name; defaults to the directory name
--port <port>port the service listens on
--framework <framework>override framework detection
--repo <owner/name>GitHub repo this project deploys from
--replicas <n>copies of the web service to run
--size <slug>instance size slug; micro when omitted
--forceoverwrite an existing ghaym.yaml

ghaym cloud deploy

Create what ghaym.yaml describes, then explain how to ship.

Usage
ghaym cloud deploy [flags]
FlagWhat it does
--repo <owner/name>GitHub repo to deploy from
--size <slug>instance size slug; overrides size in ghaym.yaml
--site <slug>site to launch in; overrides site in ghaym.yaml
--env <env>environment to launch into, by name or id; production when omitted

ghaym cloud connect

Open a tunnel from a port on this machine to a database.

Usage
ghaym cloud connect [database] [flags]
ArgumentRequired
[database]No
FlagWhat it does
--project <project>project the database is in, when its name is in several
--env <env>environment, by name or id; production when omitted
--readerconnect to a read-only copy
--port <port>local port; the engine's own port, or the next free one, when omitted
--wakewake the database first when it is asleep, and wait until it answers

ghaym cloud usage

Show metered usage and cost for the current month.

Usage
ghaym cloud usage

Global flags

FlagWhat it does
-V, --versionoutput the version number
--jsonemit a stable JSON document on stdout
--dry-runshow what would happen without changing anything
--intent <text>why this command is being run; recorded in the audit trail
--idempotency-key <key>reuse a key so a retried mutation applies once
--workspace <id>workspace to act in; overrides GHAYM_WORKSPACE and the config file

Environment variables

VariableWhat it does
GHAYM_TOKENA ghk_ API key. Always wins over stored credentials.
GHAYM_API_URL, GHAYM_AUTH_URLService base URLs.
GHAYM_SESSIONA uuidv7 reused across calls to group them into one agent session. Setting it marks the caller as an agent.
GHAYM_INTENTFree text recorded in the audit trail.
GHAYM_AGENTOverrides the detected harness, as name/version.
GHAYM_WORKSPACEWorkspace id to act in. --workspace wins over it, and it wins over the config file. Set but empty, it names none.

Exit codes

CodeNameMeaningFrom HTTP
0okThe command succeeded.–
1genericUnclassified failure (network, server, bug).any other status, or no answer
2usageBad invocation: unknown flag, missing argument, or a prompt was required in a non-interactive session.–
3authNot authenticated, token expired, or insufficient permissions.401, 403
4not-foundThe referenced resource does not exist.404
5conflictValidation failed, or the request conflicts with current state.400, 409, 422
6needs-approvalThe action is gated: an approval was created and is pending. Poll it with ghaym cloud approvals wait <id>.202 with approval-required
7quotaBlocked by quota, budget, or billing state.402, 429

JSON output

With --json, a command prints one JSON document on stdout.

MemberWhat it holds
oktrue when the command succeeded, false when it failed.
dataThe result, on success. Most lists hold items and pagination (limit, offset, total).
data with --dry-rundryRun, then one of two plans. ghaym cloud services create, ghaym cloud domains add and ghaym cloud sessions rollback ask the API, which answers with its costed plan: operation, summary, resources, estimatedMonthlyJod and warnings. Every other change sends nothing: simulated, reason, and the request it would send, with Authorization hidden. Nothing changes.
exitCodeThe exit code, on failure.
errorThe API's error document, as is. Its type names its page under API errors. The CLI adds suggestions when a reference matches nothing.

How every command behaves

  • It asks a question only on a terminal. In CI, without a terminal, or under Claude Code, it stops with exit 2 and names the flag to pass.
  • Every command that changes something takes --dry-run, and then changes nothing.
  • Every change sends an Idempotency-Key it makes itself. --idempotency-key sets your own.
  • An action that needs approval exits 6 with an approval id. Wait for it with ghaym cloud approvals wait.
  • A <project> or <service> takes the id or the slug. Slugs are unique per account.
  • A reference that matches nothing exits 4 and names the nearest slugs, also under error.suggestions with --json.
  • --env takes a name or an id. On a service, a command acts on production when it's left out. A command that takes an environment id needs --project when you give a name.
  • Scale, settings, variables, access and bucket connections are staged. Nothing moves until ghaym cloud changes apply, or --apply on the same call.
  • vars set and vars unset stage on one service with --service. Without it the variable is shared and reaches every service in the environment.
  • A plan limit exits 7 with planKey, limit and limitValue. ghaym cloud billing plans lists each plan's limits.
  • ghaym cloud connect holds the tunnel until Ctrl-C and reconnects on the same port. Under --json it prints one line when the tunnel is ready and one more if the server closes it. An asleep database exits 5; --wake wakes it first.