╻
  ╭─╯ ╰─╮   GroundZero
  │     │   Deploy UIs & APIs from your terminal or an AI agent.
  ╰─────╯   gzer0.app

GroundZero CLI

Deploy UIs and APIs, manage env vars, domains, and billing, straight from your terminal or an AI agent.

Built on @gzero/sdk. Everything the dashboard does, scriptable, with a device-code login and a config that plays nicely with CI.

Install

Requires Node.js 20+.

npm install -g gzero-cli
# or run without installing
npx gzero-cli --help

Works on Linux, macOS, and Windows.

Quick start

Push your code to GitHub, then go from zero to live in two commands:

gzero login            # device-code sign in via your browser
gzero init             # pick a repo, auto-detect the build, create + deploy

gzero init walks you through it: choose a GitHub repo, pick web app or API, attach it to a product (existing or new), and it scans the repo to detect the framework, build command, and output folder for you. At the end it offers to deploy.

Already have projects? Day-to-day it's just:

gzero deploy           # deploy a project and watch it go live
gzero status           # check readiness, URL, and env vars

gzero deploy on a brand-new account with no projects drops straight into the init flow, then deploys. Run gzero with no arguments (or gzero --help) to see the full command list.

Note GroundZero builds and deploys from GitHub, so your code needs to be pushed to a GitHub repo first (the same as the dashboard). The CLI does not upload local files.

Sign in

gzero login

This runs a device-code login (OAuth 2.0 device authorization):

1. The CLI prints a short code and opens your browser to /activate.
2. Sign in with GitHub (if you aren't already) and confirm the code.
3. The CLI receives a long-lived API token and saves it locally.

The token is minted only after you approve in the browser, and it is never shown in the browser itself.

Where the token is stored

| OS | Path | | ------- | -------------------------------------------------------------------- | | Linux | $XDG_CONFIG_HOME/gzero/config.json or ~/.config/gzero/config.json | | macOS | ~/.config/gzero/config.json | | Windows | %APPDATA%\gzero\config.json |

gzero login prints the exact path after saving. The file is written with 0600 permissions on Unix.

Commands

| Command | Description | | ------- | ----------- | | gzero login | Device-code sign in; saves an API token | | gzero logout | Revoke the current token and clear local config | | gzero whoami | Show the signed-in account | | gzero init [repo] | Create a project from a GitHub repo (interactive), then optionally deploy | | gzero projects (alias ls) | List your projects | | gzero deploy [project] | Trigger a deploy and follow it to completion (bootstraps init on an empty account) | | gzero status [project] | Active deploy, readiness, and env status | | gzero logs [project] | Print the latest deploy's build log | | gzero open [project] | Open the project's live URL in your browser | | gzero rollback [project] | Roll back to a previous successful deploy | | gzero promote [project] | Promote a deploy to production | | gzero env list [project] | List env var keys | | gzero env set <project> <key> <value> | Set an env var | | gzero env rm <project> <key> | Delete an env var | | gzero env import <project> <file> | Bulk-import vars from a .env file | | gzero domains list [project] | List custom domains | | gzero domains add <project> <host> | Attach a custom domain | | gzero domains verify <project> <host> | Re-check DNS and verify a domain | | gzero domains remove <project> <host> | Remove a custom domain | | gzero billing | Show plan, usage, and available add-ons | | gzero billing upgrade | Open Stripe checkout (subscribe) | | gzero billing addon <id> | Open Stripe checkout for an add-on | | gzero billing portal | Open the Stripe billing portal | | gzero mcp | Print config to connect an AI agent to the hosted MCP |

deploy flags: -b, --branch <branch>, -e, --env <environment>, -y, --yes (acknowledge readiness warnings), --no-follow (return immediately).

[project] accepts a project id, slug, or name. If omitted, the CLI uses your only project or prompts you to pick one.

Payments open a Stripe-hosted URL in your browser; card details are never handled by the CLI.

Configuration

Precedence: command-line flags, then environment variables, then the saved config.

| Setting | Flag | Env var | | ------------ | ---------------- | ---------------- | | API base URL | --api-url <url> | GZERO_API_URL | | API token | --token <token> | GZERO_TOKEN |

The default API URL is https://api.gzer0.app. For local development against a dev server, point it at your local API:

GZERO_API_URL=http://localhost:3000 gzero login

GZERO_TOKEN is handy for CI and other headless callers.

Note Output is colorized when writing to a terminal. Set NO_COLOR=1 to disable colors, or FORCE_COLOR=1 to keep them when piping.

Connect an AI agent (MCP)

The MCP server is hosted by GroundZero, so there is nothing extra to install:

gzero mcp

It prints a ready-to-paste client config pointing at https://mcp.gzer0.app/mcp. Add it to your AI client (for example Cursor's ~/.cursor/mcp.json); on first use the client opens a browser to sign in with GitHub. See @gzero/mcp for details.

Examples

# Create a project from a specific repo and deploy it
gzero init acme/my-app

# Deploy a specific branch to production and wait for it to go live
gzero deploy my-app --branch main --env production

# Import a whole .env file, then redeploy
gzero env import my-app .env.production
gzero deploy my-app

# Attach and verify a custom domain
gzero domains add my-app app.example.com
gzero domains verify my-app app.example.com

# Roll back the last bad deploy
gzero rollback my-app

# Queue a deploy in CI without streaming logs
GZERO_TOKEN=$CI_TOKEN gzero deploy my-app --yes --no-follow