CLI

The Gheima CLI runs your account from the terminal: deploy, tail logs, and manage services, databases, and storage. It authenticates with an API key.

Install and sign in#

npm install -g @gheima/cli
gheima login

gheima login opens your browser so you can approve the sign-in, then saves a new API key to the profile. On a machine without a browser, add --no-browser and open the printed URL yourself. From a script or a coding agent, where nothing can wait on a prompt, run gheima login --no-wait --json: it prints the code and the URL to hand to the person and exits, and gheima login --resume then waits for the approval and saves the key (add --timeout <seconds> to come back later; it exits 7 while the sign-in is still pending). To use a key you already have, run gheima login --with-key and paste it (it starts with gh_). Keys are stored per profile in ~/.config/gheima/config.json with mode 600. To skip login, set the GHEIMA_API_KEY environment variable.

Global options#

-k, --key <key>

API key for this call (overrides the env var and stored profile).

-u, --url <url>

API base URL (defaults to https://gheima.ma).

-p, --profile <name>

Which stored profile to use.

--json

Print machine-readable JSON instead of a table.

-v, --version

Print the CLI version.

Account commands#

gheima login

Sign in through the browser, or with an existing API key, and store the key in a profile.

gheima logout

Remove a stored profile.

gheima whoami

Show the account for the active key (name, slug, plan, type).

gheima status

Show the account, plan, and service and database counts.

gheima open [resource]

Open the dashboard (or a path) in your browser.

gheima completion [shell]

Print a completion script for bash, zsh, or fish.

Service commands#

Commands that take a <service> accept its id, name, or slug. Destructive commands ask you to confirm unless you pass -y or --yes. In a non-interactive shell, they refuse to run without it.

gheima services

List services. Same as services list. Aliases: service, svc.

gheima services get <id>

Show one service in detail.

gheima services create --name <name> [--project <id>] [--type WEB|WORKER|STATIC] [--repo <url>]

Create a service. The type defaults to WEB. Leave out --project to keep the service outside any project.

gheima services delete <id> [-y]

Delete a service.

gheima github wait [--repo <url>] [--timeout <minutes>]

Print the link to install the Gheima GitHub App on this repository's owner, and wait until it is installed. A private GitHub repository needs it to build; exit 7 if --timeout (10 minutes) passes first.

gheima link <service>

Link this directory to a service. Commands run inside it, or any subdirectory, then default to that service.

gheima agents [--write]

Print a short section for AGENTS.md telling coding agents how this project deploys. --write adds it to the file, replacing an earlier copy.

gheima deploy [service] [--yes] [--upload] [--name <name>] [--type WEB|WORKER|STATIC] [--no-wait] [--timeout <minutes>]

Deploy this folder, stream the build, and print the live URL. Exits 0 when live, 8 when it fails. Uses the linked service if you leave it out. In a folder with no service yet it creates one and links it (confirm with --yes when there is no terminal): built from the git remote when there is one, otherwise from the folder's files, uploaded with .env files and node_modules left out. --upload uploads the files even when there is a remote.

gheima logs <service> [-f] [-b] [-s <text>]

Show or tail logs. -f follows, -b shows build logs, -s filters by text.

gheima run <service> [--timeout <seconds>] [--no-wait] -- <command>

Run a one-off command, such as a migration, in a fresh container from the service’s live image and environment. Prints its log and exits with the command’s exit code, or 9 if it never reported one. Admins only. The words are joined and run by the remote shell, so quote the whole command when an argument holds spaces: gheima run web -- 'psql -c "select 1"'.

gheima env ls [service]

List env var keys with masked values.

gheima env pull [service] [--file <path>] [-f] [--stdout]

Write the service’s env var values in plaintext to .env.local (mode 0600). Secret variables can’t be read back and are left out.

gheima env push [service] [--file <path>] [--replace] [-y]

Upload a .env file to the service. Merges by default; --replace discards variables not in the file.

gheima env set <service> KEY=value

Set an environment variable.

gheima env rm <service> <key> [-y]

Remove an environment variable.

gheima domains <service>

List custom domains for a service.

Resource commands#

gheima db

List databases. Alias: databases.

gheima storage buckets

List object-storage buckets.

gheima storage ls <bucket> [prefix]

List objects in a bucket.

gheima storage cp <file> <bucket> [key]

Upload a local file via a presigned URL.

gheima storage get <bucket> <key> [dest]

Download an object.

gheima storage rm <bucket> <key> [-y]

Delete an object.

gheima cron

List cron jobs.

gheima webhooks

List webhooks.

gheima services create --name web --type WEB --repo https://github.com/me/app
gheima deploy web
gheima logs web -f -s error
gheima env set web NODE_ENV=production
gheima storage cp ./photo.png my-bucket images/photo.png
gheima services --json | jq '.[].url'