ghaym CLI

The command-line interface for Ghaym — built agent-safe from day one.

Every command speaks --json, every mutation supports --dry-run, and the CLI never prompts when it detects a non-interactive session. AGENTS.md is the whole surface on one page, for loading into an agent's context.

Command layout

The root holds your Ghaym-wide session and the CLI's own settings — login, logout, whoami, config, help. Everything else is namespaced by product, so a second product can join later without colliding:

ghaym cloud <command>    # Ghaym Cloud — deploy and manage apps

Install

Published on npm as @ghaymjo/cli:

npm install -g @ghaymjo/cli

Or run from source:

nvm use && npm ci && npm run build
node dist/index.js --help

Agent-first usage

Authenticate with an API key. This path has zero interactive steps — the key is exchanged for a short-lived JWT and cached until it expires.

export GHAYM_TOKEN=ghk_...

The service URLs already default to production, so nothing else is needed. Override them to point at a local stack:

export GHAYM_API_URL=http://localhost:3400    # cloud control plane
export GHAYM_AUTH_URL=http://localhost:3100   # auth

Load the whole command surface in one call instead of walking --help:

ghaym help --all --json

Read something:

ghaym cloud projects list --json
ghaym cloud deployments list --service <id> --status running --json

Change something — always safe to rehearse first:

ghaym --dry-run cloud services create --project acme --type git --repo owner/name --json
ghaym --intent "ship the landing page" cloud services redeploy acme-site --json

Naming a project or a service

Anywhere a command takes <project> or <service>, pass either the uuid or the slug — ghaym cloud services list acme and ghaym cloud services list 0197f3c4-… are the same call. Slugs are unique per account, so a reference is never ambiguous, and both projects list and services list print the slug alongside the id.

A reference that matches nothing exits 4 and names the closest slugs:

$ ghaym cloud projects get acme-web
Error: Project Not Found
  Project with ID 'acme-web' was not found
  Did you mean: acme, acme-api?

Under --json the same names arrive as error.suggestions, so there is nothing to scrape.

Branch on the exit code, not on stderr:

ghaym cloud projects delete <id> --json
case $? in
  0) echo "deleted" ;;
  6) echo "needs approval" ;;   # poll it: ghaym cloud approvals wait <id>
  7) echo "over budget" ;;
esac

ghaym help exit-codes documents all eight.

Grouping a session

Export one uuidv7 so every call an agent makes is attributed to a single session and shows up together in ghaym cloud sessions and ghaym cloud audit list:

export GHAYM_SESSION=0197f3c4-8d2a-7c31-9f4e-2b8a1c5d6e70   # must be a uuidv7
export GHAYM_INTENT="migrate the staging database"

The CLI sets X-Ghaym-Agent automatically when it detects a harness (CLAUDECODE, Cursor), and omits it when the session looks plainly human, so human traffic is never misattributed. Override with GHAYM_AGENT=name/version.

Human usage

ghaym login         # paste an API key at a hidden prompt, or pipe it in
ghaym whoami
ghaym cloud init    # detect the framework, write ghaym.yaml, ask nothing
ghaym cloud deploy

ghaym cloud init writes ghaym.yaml with zero questions and every inferred value overridable by a flag.

ghaym login and GHAYM_TOKEN carry the same credential — a ghk_ API key created in the Cloud Console. Login stores it once (like gh auth login) so every later command and every agent on the machine inherits it; GHAYM_TOKEN overrides the stored key for CI or one-off runs. Either way the key is exchanged for a short-lived signed JWT under the hood; the CLI never accepts a raw JWT.

How deploys actually work

Ghaym builds what it pulls from a connected GitHub repository — pushes are the trigger, and there is no local-upload path. So ghaym cloud deploy creates the project and service described by ghaym.yaml, then prints the push instructions rather than pretending to upload your working tree.

Run ghaym cloud connect to get the URL that installs the Ghaym GitHub App.

Output contract

Success and failure share one envelope, validated against schemas/:

{ "ok": true,  "data": { /* command-specific */ } }
{ "ok": false, "exitCode": 4, "error": { /* the API's problem+json, verbatim */ } }

Errors are passed through untouched, so the type slug, docs link, and any extension members the API sends all survive.

Configuration

| Variable | Purpose | | ---------------- | -------------------------------------------------------- | | GHAYM_TOKEN | ghk_ API key. Wins over the stored credential. | | GHAYM_API_URL | Cloud API base URL. | | GHAYM_AUTH_URL | Auth API base URL. | | GHAYM_SESSION | uuidv7 reused across calls to group them. | | GHAYM_INTENT | Free text recorded in the audit trail. | | GHAYM_AGENT | Overrides harness detection, as name/version. |

Anything not set in the environment falls back to ghaym config set <key> <value>, then to the production defaults. Credentials live in ~/.config/ghaym/credentials.json, written 0600.

Development

npm test                 # 100% coverage enforced on all four metrics
npm run check            # Biome format + lint
npm run docs:agents      # regenerate AGENTS.md (a test asserts it is in sync)