CLI reference
Look up any ghaym command: its arguments, flags, exit codes and the JSON it prints.
All pages
For ghaym 0.0.21. To check your version or update it, see Install the CLI and sign in.
| Group | What it's for |
|---|---|
ghaym config | read and write CLI configuration |
ghaym cloud workspaces | manage workspaces |
ghaym cloud projects | manage projects |
ghaym cloud environments | manage environments |
ghaym cloud services | manage services |
ghaym cloud deployments | inspect deployments |
ghaym cloud changes | staged changes to an environment, published together |
ghaym cloud topology | every replica of every service |
ghaym cloud rollouts | rolling deployments |
ghaym cloud residency | where each service, database and bucket runs, and the DPA for each country |
ghaym cloud regions | regions and the sizes they sell |
ghaym cloud engines | what a database or cache can run |
ghaym cloud vars | manage environment variables |
ghaym cloud domains | manage custom domains |
ghaym cloud access | who can reach a web service, per environment |
ghaym cloud buckets | manage object storage buckets |
ghaym cloud billing | inspect billing |
ghaym cloud audit | inspect the audit trail |
ghaym cloud approvals | manage approval gates |
ghaym cloud sessions | inspect agent sessions |
ghaym cloud git | the GitHub App connection |
ghaym help | extended help topics |
With the CLI, get every command and flag in one call:
Terminal
ghaym help all --jsonSign this machine in, in the browser or with a piped API key.
Usage
ghaym loginSign this machine out and revoke its browser sign-in.
Usage
ghaym logoutShow the identity behind the active credential.
Usage
ghaym whoamiDetect the framework and write ghaym.yaml.
Usage
ghaym cloud init [flags]| Flag | What 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 |
--force | overwrite an existing ghaym.yaml |
Create what ghaym.yaml describes, then explain how to ship.
Usage
ghaym cloud deploy [flags]| Flag | What 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 |
Open a tunnel from a port on this machine to a database.
Usage
ghaym cloud connect [database] [flags]| Argument | Required |
|---|---|
[database] | No |
| Flag | What 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 |
--reader | connect to a read-only copy |
--port <port> | local port; the engine's own port, or the next free one, when omitted |
--wake | wake the database first when it is asleep, and wait until it answers |
Show metered usage and cost for the current month.
Usage
ghaym cloud usage| Flag | What it does |
|---|---|
-V, --version | output the version number |
--json | emit a stable JSON document on stdout |
--dry-run | show 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 |
| Variable | What it does |
|---|---|
GHAYM_TOKEN | A ghk_ API key. Always wins over stored credentials. |
GHAYM_API_URL, GHAYM_AUTH_URL | Service base URLs. |
GHAYM_SESSION | A uuidv7 reused across calls to group them into one agent session. Setting it marks the caller as an agent. |
GHAYM_INTENT | Free text recorded in the audit trail. |
GHAYM_AGENT | Overrides the detected harness, as name/version. |
GHAYM_WORKSPACE | Workspace id to act in. --workspace wins over it, and it wins over the config file. Set but empty, it names none. |
| Code | Name | Meaning | From HTTP |
|---|---|---|---|
0 | ok | The command succeeded. | – |
1 | generic | Unclassified failure (network, server, bug). | any other status, or no answer |
2 | usage | Bad invocation: unknown flag, missing argument, or a prompt was required in a non-interactive session. | – |
3 | auth | Not authenticated, token expired, or insufficient permissions. | 401, 403 |
4 | not-found | The referenced resource does not exist. | 404 |
5 | conflict | Validation failed, or the request conflicts with current state. | 400, 409, 422 |
6 | needs-approval | The action is gated: an approval was created and is pending. Poll it with ghaym cloud approvals wait <id>. | 202 with approval-required |
7 | quota | Blocked by quota, budget, or billing state. | 402, 429 |
With --json, a command prints one JSON document on stdout.
| Member | What it holds |
|---|---|
ok | true when the command succeeded, false when it failed. |
data | The result, on success. Most lists hold items and pagination (limit, offset, total). |
data with --dry-run | dryRun, 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. |
exitCode | The exit code, on failure. |
error | The API's error document, as is. Its type names its page under API errors. The CLI adds suggestions when a reference matches nothing. |
- It asks a question only on a terminal. In CI, without a terminal, or under Claude Code, it stops with exit
2and names the flag to pass. - Every command that changes something takes
--dry-run, and then changes nothing. - Every change sends an
Idempotency-Keyit makes itself.--idempotency-keysets your own. - An action that needs approval exits
6with an approval id. Wait for it withghaym cloud approvals wait. - A
<project>or<service>takes the id or the slug. Slugs are unique per account. - A reference that matches nothing exits
4and names the nearest slugs, also undererror.suggestionswith--json. --envtakes 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--projectwhen you give a name.- Scale, settings, variables, access and bucket connections are staged. Nothing moves until
ghaym cloud changes apply, or--applyon the same call. vars setandvars unsetstage on one service with--service. Without it the variable is shared and reaches every service in the environment.- A plan limit exits
7withplanKey,limitandlimitValue.ghaym cloud billing planslists each plan's limits. ghaym cloud connectholds the tunnel until Ctrl-C and reconnects on the same port. Under--jsonit prints one line when the tunnel is ready and one more if the server closes it. An asleep database exits5;--wakewakes it first.