CLI

zb is a single Rust binary that talks to the public API. It is published on GitHub Releases for Linux (x86_64, arm64), macOS (Apple silicon, Intel) and Windows (x86_64), with a Homebrew formula and a Scoop manifest.

install

brew install zerobase-io/tap/zb          # macOS / Linux
scoop bucket add zerobase https://github.com/zerobase-io/scoop-bucket
scoop install zerobase/zb                # Windows
# or download zb-<version>-<target>.tar.gz / .zip from GitHub Releases and put `zb` on PATH

Shell completion: zb completion bash|zsh|fish|powershell|elvish prints a script, for example zb completion zsh > "${fpath[1]}/_zb" or zb completion powershell | Out-String | Invoke-Expression.

Authentication

shell

zb login                          # prompts for an API key (create one in the portal or with `zb api-keys create`)
zb login --key zb_live_...        # non-interactive; or set ZB_API_KEY (CI)
zb orgs list ; zb orgs use org_01J8...
zb projects use prj_01J8...       # default for `instances create` and `migrate --create`
zb logout

zb login verifies the key against GET /v1/orgs and saves it, with the API URL and the default org and project, in config.json under the OS config directory (%APPDATA%\zerobase on Windows, ~/.config/zerobase on Linux, ~/Library/Application Support/zerobase on macOS; override with ZB_CONFIG_PATH). On Linux and macOS the file is created with mode 0600. Precedence is flag, then environment (ZB_API_KEY, ZB_API_URL, ZB_ORG, ZB_PROJECT), then the saved file.

Connecting

zb connect <instance> asks the API for a one-time reveal URL (POST .../credentials/reveal, which needs the credentials:reveal team permission, and a completed second factor if you turned on two-factor authentication or your organization requires it; it is rate limited and audited), fetches the credential directly from your instance’s cell and starts the matching shell with TLS verification on:

Engine wire	Client	TLS	Where the password goes
Postgres (postgres, timescaledb, questdb)	psql	sslmode=verify-full, sslrootcert=system (libpq 16+, else pass --ca)	PGPASSWORD in the child environment
MySQL (mysql, mariadb)	mysql / mariadb	--ssl-mode=VERIFY_IDENTITY --tls-sni-servername=<host> / --ssl-verify-server-cert	MYSQL_PWD in the child environment
RESP (valkey, redis)	valkey-cli / redis-cli	--tls	REDISCLI_AUTH in the child environment
MongoDB (ferretdb, mongodb)	mongosh	tls=true	command-line argument (mongosh has no variable; zb warns)

The credential is never written to disk and never appears in what you typed, so it does not reach your shell history. HTTP engines have no shell: zb connect <id> --print prints the endpoint, and zb instances credentials reveal <id> prints the token once. --print never reveals anything; it prints the URI with the password masked. Arguments after -- go to the client (zb connect inst_1 -- -c "select 1").

Events and logs

The API does not expose engine logs yet. zb logs <instance> -f streams the instance’s events (status changes, pauses, backups, migrations) from the server-sent events endpoint GET /v1/orgs/{org}/instances/{id}/events and says so on stderr; --json prints one event envelope per line.

Exit codes

0 ok · 1 error · 2 usage error, or the API rejected the request as invalid (400, 409, 422) · 3 zb migrate verification found mismatches · 4 cancelled at a confirmation prompt · 5 the API was unreachable · 6 a local prerequisite of zb migrate is missing (dump tool, docker, wrangler, a running container).

In CI

.github/workflows/preview-db.yaml

- name: install zb
  run: |
    curl -fsSL -o zb.tgz \
      https://github.com/zerobase-io/zerobase/releases/download/zb-v0.1.0/zb-0.1.0-x86_64-unknown-linux-gnu.tar.gz
    tar -xzf zb.tgz && sudo install zb /usr/local/bin/zb
- run: zb instances create --engine postgres --size s1 --region us-east --name "pg-pr-${{ github.event.number }}" --wait --json > inst.json
  env: { ZB_API_KEY: ${{ secrets.ZB_API_KEY }} }

--json prints the raw API response for every command, so jq works on all output.

Command reference

Generated from zb dev.

Global flags

Accepted by every command.

Argument	Description
--api-url <API_URL>	API base URL (default: the one saved by zb login, else https://api.databasezy.com). Env ZB_API_URL.
--org <ORG>	Organization id (default: zb orgs use, else your first org). Env ZB_ORG.
--project <PROJECT>	Project id (default: zb projects use, else the org’s first project). Env ZB_PROJECT.
--json	Print raw JSON API responses instead of tables.
-y, --yes	Skip confirmation prompts (never skips typing the name for erase / in-place restore).
-v, --verbose	Log each request (method, URL, status, request id) to stderr.

Commands

Command	What it does
zb api	Raw call to the REST API with your credentials
zb api-keys	Control-plane API keys
zb approvals	Approval requests for instances that exceed a team’s policy
zb apps	Apps: run a container image next to your databases, with releases, rollback, scaling, env, domains and jobs
zb backups	Backups, restores and point-in-time recovery
zb completion	Print a shell completion script
zb connect	Open the engine’s shell (psql, mysql, valkey-cli, mongosh) with TLS and a one-time credential. The credential is passed through the child’s environment where the client supports it and is never written to disk or shell history
zb cost-report	Monthly cost allocation per team and cost centre
zb db	Declarative schemas: pull, diff and push schema-as-code migrations (PostgreSQL)
zb docs	Generate the CLI reference (Markdown or a man page) from this binary
zb functions	Edge functions: deploy, list, invoke, logs, versions, triggers (Deno / TypeScript, Supabase compatible)
zb gen	Generate code from a project (types)
zb instances	Manage database instances
zb login	Save an API key (and API URL) in the OS config directory
zb logout	Remove the saved API key
zb logs	Stream an instance’s events (status changes, backups, migrations)
zb members	Org members and invites
zb migrate	Move a database into Databasezy
zb orgs	Organizations you belong to; use sets the default
zb projects	Projects in the org; use sets the default
zb realtime	Project realtime: broadcast, presence and database changes over WebSockets, database webhooks
zb sandbox	Sandboxes: short-lived isolated containers to run code in (exec, files, snapshots)
zb secrets	Function secrets of the project (names only are ever shown)
zb ssh-key	SSH public keys on your account (workspace SSH through the bastion)
zb storage	Project storage: buckets, files (ss:///bucket/path), signed transfers and S3 credentials
zb teams	Teams, their members and budgets
zb usage	Usage and list-price cost for the current month (or —from/—to), grouped
zb ws	Cloud dev workspaces: create, start, stop, and connect over SSH (VS Code / Cursor Remote-SSH)

zb api

Raw call to the REST API with your credentials.

zb api [OPTIONS] <METHOD> <PATH>

Argument	Description
<METHOD>	HTTP method (GET, POST, PATCH, PUT, DELETE).
<PATH>	Path starting with /v1/...; {org} is replaced by the current org id.
-d, --data <DATA>	JSON body, @file or - for stdin.

zb api-keys

Control-plane API keys.

Subcommand	What it does
zb api-keys create	Create a key; the secret is printed once
zb api-keys list	List API keys (the secret is never shown again)
zb api-keys revoke	Revoke a key

zb api-keys create

Create a key; the secret is printed once.

zb api-keys create [OPTIONS] --name <NAME>

Argument	Description
--expires <EXPIRES>	Expiry (RFC 3339).
--name <NAME>	Required.
--role <ROLE>	Org role for the key (default: member).
--scope <SCOPE>	Restrict to these permissions (comma separated).

zb api-keys list

List API keys (the secret is never shown again).

zb api-keys list [OPTIONS]

zb api-keys revoke

Revoke a key.

zb api-keys revoke [OPTIONS] <ID>

Argument	Description
<ID>	Resource id.

zb approvals

Approval requests for instances that exceed a team’s policy.

Subcommand	What it does
zb approvals approve	Approve (creates the instance)
zb approvals deny	Deny with a reason
zb approvals get	Show one approval request
zb approvals list	List approval requests

zb approvals approve

Approve (creates the instance).

zb approvals approve [OPTIONS] <ID>

Argument	Description
<ID>	Resource id.
--reason <REASON>

zb approvals deny

Deny with a reason.

zb approvals deny [OPTIONS] --reason <REASON> <ID>

Argument	Description
<ID>	Resource id.
--reason <REASON>	Required.

zb approvals get

Show one approval request.

zb approvals get [OPTIONS] <ID>

Argument	Description
<ID>	Resource id.

zb approvals list

List approval requests.

zb approvals list [OPTIONS]

Argument	Description
--mine	Only requests you made.
--status <STATUS>	pending, approved, denied, expired.
--team <TEAM>

zb apps

Apps: run a container image next to your databases, with releases, rollback, scaling, env, domains and jobs.

Subcommand	What it does
zb apps builds	Git builds of an app: list, get, create, cancel and logs
zb apps create	Create an app from a container image (—image; the tag is pinned to its digest) or a GitHub repository (—repo: built in the cell and redeployed on every push); prints its URL, or the approval request when a team policy needs one
zb apps delete	Delete an app with its releases, environment, domains and jobs. Irreversible; asks first unless —yes
zb apps deploy	Deploy a new release: a new image, or the current reference again (a moved tag is resolved to its new digest); replicas roll one at a time
zb apps domains	Custom domains of an app: add one, create its two CNAME records, verify
zb apps env	An app’s environment: plain values, project secrets and instance credentials (resolved in the cell)
zb apps get	Show one app: status, URL, current release, scaling, port and health check
zb apps jobs	Jobs: one-off and cron commands in the app’s image with its environment
zb apps list	List the project’s apps (the global —project, else the default project)
zb apps logs	Print an app’s container logs, each line prefixed with its replica (-f follows them; —job-run shows a job run’s); —json prints the single-use stream URL instead
zb apps metrics	Show an app’s replicas, restarts, limits and recent CPU / memory samples
zb apps releases	List an app’s releases, newest first (* marks the release the app runs)
zb apps restart	Restart every replica with a rolling restart (recorded as a release)
zb apps rollback	Roll back to an earlier release (default: the one before the current), pinned to that release’s digest
zb apps scale	Change an app’s scaling: size, min/max replicas, CPU target and scale to zero
zb apps start	Start a stopped app: its current release runs again
zb apps stop	Stop an app: replicas go to zero and compute stops billing; releases, env, domains and jobs are kept
zb apps update	Change an app’s settings: scaling, port, protocol, health check, command, args or registry secret (rolls the running release)

zb apps builds

Git builds of an app: list, get, create, cancel and logs.

Subcommand	What it does
zb apps builds cancel	Cancel a queued or running build
zb apps builds create	Build the app now: its branch (or —ref / —commit), deployed when it succeeds unless —no-deploy
zb apps builds get	Show one build: status, commit, image digest, release and duration
zb apps builds list	List an app’s builds, newest first
zb apps builds logs	Print a build’s log (secrets are masked by the cell); -f follows a running build

zb apps builds cancel

Cancel a queued or running build.

zb apps builds cancel [OPTIONS] <APP> <BUILD>

Argument	Description
<APP>	App name or id (app_…).
<BUILD>	Build id (bld_…).

zb apps builds create

Build the app now: its branch (or —ref / —commit), deployed when it succeeds unless —no-deploy.

zb apps builds create [OPTIONS] <APP>

Argument	Description
<APP>	App name or id (app_…).
--commit <SHA>	Commit to build (40 hex characters).
--no-deploy	Build the image without releasing it.
--ref <BRANCH>	Branch to build (default: the app’s branch).
--timeout <TIMEOUT>	Give up waiting after this many seconds (with —wait). Default 1800.
--wait	Wait until the build ends (or failed).

zb apps builds get

Show one build: status, commit, image digest, release and duration.

zb apps builds get [OPTIONS] <APP> <BUILD>

Argument	Description
<APP>	App name or id (app_…).
<BUILD>	Build id (bld_…).

zb apps builds list

List an app’s builds, newest first.

zb apps builds list [OPTIONS] <APP>

Argument	Description
<APP>	App name or id (app_…).

zb apps builds logs

Print a build’s log (secrets are masked by the cell); -f follows a running build.

zb apps builds logs [OPTIONS] <APP> <BUILD>

Argument	Description
<APP>	App name or id (app_…).
<BUILD>	Build id (bld_…).
-f, --follow	Keep streaming while the build runs.

zb apps create

Create an app from a container image (—image; the tag is pinned to its digest) or a GitHub repository (—repo: built in the cell and redeployed on every push); prints its URL, or the approval request when a team policy needs one.

zb apps create [OPTIONS] <NAME>

Argument	Description
<NAME>	App name: 1-30 lower-case letters, digits and -, starting with a letter; unique in the project.
--arg <ARG>	Override the image arguments, one per flag (repeat it).
--branch <BRANCH>	Branch to build and follow (with —repo; default main).
--builder <BUILDER>	dockerfile (default: BuildKit) or buildpacks (no Dockerfile needed). One of dockerfile, buildpacks.
--command <ARG>	Override the image entrypoint, one argument per flag (repeat it).
--context <DIR>	Build context directory in the repository (default the root).
--cpu-target <PERCENT>	Average CPU percent the autoscaler keeps replicas at (default 70).
--dedicated-nodes	Run on the org’s own nodes.
--dockerfile <PATH>	Dockerfile path in the repository (default Dockerfile).
--env <KEY=VALUE>	Plain environment variable KEY=VALUE (repeat it).
--env-instance <KEY=INSTANCE[:ROLE[:FIELD]]>	Variable from a project instance’s credential KEY=INSTANCE[:ROLE[:FIELD]] (role default app; field uri, host, port, username, password or database; default uri).
--env-secret <KEY=SECRET>	Variable from a project secret KEY=SECRET, resolved in the cell (repeat it).
--health-path <PATH>	HTTP readiness and liveness path, e.g. /healthz (default: a TCP check).
--idle-minutes <MINUTES>	Idle minutes before scaling to zero (default 15).
--image <IMAGE>	Container image (ghcr.io/org/web:1, nginx@sha256:…); a tag is resolved to its digest now.
--max <N>	Maximum replicas; above —min the app autoscales on CPU (default 1).
--min <N>	Minimum replicas (default 1).
--no-auto-deploy	Do not build and deploy on every push to the branch.
--placement <PLACEMENT>	shared (default) or secure (the hipaa cell; needs a signed BAA).
--port <PORT>	Container port the app listens on (default 8080).
--protocol <PROTOCOL>	http (default), tcp (TLS with SNI on the app host) or none (no ingress). One of http, tcp, none.
--region <REGION>	Region (default: the org’s default region).
--registry-secret <SECRET>	Project secret with the registry credentials, for a private image (docker config JSON or user:token).
--repo <OWNER/NAME>	Build from this GitHub repository (owner/name) of the org’s GitHub App installation instead of —image.
--scale-to-zero	Scale to zero replicas when idle; the next request wakes it (paid plans).
--size <SIZE>	Size of each replica: c0 (default), c1, c2, c3 (zb api GET /v1/sizes lists them).
--timeout <TIMEOUT>	Give up waiting after this many seconds (with —wait). Default 600.
--wait	Wait until the app is running (or failed).

zb apps delete

Delete an app with its releases, environment, domains and jobs. Irreversible; asks first unless —yes.

zb apps delete [OPTIONS] <APP>

Argument	Description
<APP>	App name or id (app_…).

zb apps deploy

Deploy a new release: a new image, or the current reference again (a moved tag is resolved to its new digest); replicas roll one at a time.

zb apps deploy [OPTIONS] <APP>

Argument	Description
<APP>	App name or id (app_…).
--image <IMAGE>	New image reference (default: the app’s current reference).
--registry-secret <SECRET>	Change the registry secret with this deploy.
--timeout <TIMEOUT>	Give up waiting after this many seconds (with —wait). Default 600.
--wait	Wait until the release serves (or failed).

zb apps domains

Custom domains of an app: add one, create its two CNAME records, verify.

Subcommand	What it does
zb apps domains add	Add a custom domain and print the two CNAME records to create before verify
zb apps domains list	List an app’s custom domains and the DNS records each one needs
zb apps domains remove	Remove a custom domain from an app (asks first unless —yes)
zb apps domains verify	Check a domain’s DNS records now; once verified the cell issues its certificate

zb apps domains add

Add a custom domain and print the two CNAME records to create before verify.

zb apps domains add [OPTIONS] <APP> <HOSTNAME>

Argument	Description
<APP>	App name or id (app_…).
<HOSTNAME>	Hostname, e.g. www.example.com.

zb apps domains list

List an app’s custom domains and the DNS records each one needs.

zb apps domains list [OPTIONS] <APP>

Argument	Description
<APP>	App name or id (app_…).

zb apps domains remove

Remove a custom domain from an app (asks first unless —yes).

zb apps domains remove [OPTIONS] <APP> <DOMAIN>

Argument	Description
<APP>	App name or id (app_…).
<DOMAIN>	Domain hostname or id (adom_…).

zb apps domains verify

Check a domain’s DNS records now; once verified the cell issues its certificate.

zb apps domains verify [OPTIONS] <APP> <DOMAIN>

Argument	Description
<APP>	App name or id (app_…).
<DOMAIN>	Domain hostname or id (adom_…).

zb apps env

An app’s environment: plain values, project secrets and instance credentials (resolved in the cell).

Subcommand	What it does
zb apps env list	List an app’s variables (secrets and credentials show their reference, never a value)
zb apps env set	Set variables (KEY=VALUE, —secret, —instance); the others are kept
zb apps env unset	Remove variables (repeat the key: zb apps env unset web FOO BAR)

zb apps env list

List an app’s variables (secrets and credentials show their reference, never a value).

zb apps env list [OPTIONS] <APP>

Argument	Description
<APP>	App name or id (app_…).

zb apps env set

Set variables (KEY=VALUE, —secret, —instance); the others are kept.

zb apps env set [OPTIONS] <APP> [KEY=VALUE]

Argument	Description
<APP>	App name or id (app_…).
<KEY=VALUE>	Plain variables to set (repeat: FOO=1 BAR=2).
--instance <KEY=INSTANCE[:ROLE[:FIELD]]>	Variable from a project instance’s credential KEY=INSTANCE[:ROLE[:FIELD]] (role default app; field uri, host, port, username, password or database; default uri).
--secret <KEY=SECRET>	Variable from a project secret KEY=SECRET, resolved in the cell (repeat it).

zb apps env unset

Remove variables (repeat the key: zb apps env unset web FOO BAR).

zb apps env unset [OPTIONS] <APP> <KEY>

Argument	Description
<APP>	App name or id (app_…).
<KEY>	Variable names to remove.

zb apps get

Show one app: status, URL, current release, scaling, port and health check.

zb apps get [OPTIONS] <APP>

Argument	Description
<APP>	App name or id (app_…).

zb apps jobs

Jobs: one-off and cron commands in the app’s image with its environment.

Subcommand	What it does
zb apps jobs create	Create a job: zb apps jobs create web migrate --schedule "0 3 * * *" -- node migrate.js
zb apps jobs delete	Delete a job and its run history (asks first unless —yes)
zb apps jobs get	Show one job: schedule, command, limits and last run
zb apps jobs list	List an app’s jobs with their schedule and last run
zb apps jobs run	Run a job now; —wait waits for it to finish
zb apps jobs runs	List a job’s recent runs: state, exit code and duration
zb apps jobs update	Change a job: schedule, command (after --), concurrency, limits, size, enabled

zb apps jobs create

Create a job: zb apps jobs create web migrate --schedule "0 3 * * *" -- node migrate.js.

zb apps jobs create [OPTIONS] <APP> <NAME> [-- <COMMAND>...]

Argument	Description
<APP>	App name or id (app_…).
<NAME>	Job name, unique in the app.
--backoff-limit <N>	Retries of a failed run.
--concurrency <CONCURRENCY>	When a run is due while one is running: forbid (default), replace or allow. One of forbid, replace, allow.
--disabled	Create it disabled (a schedule does not fire until update --enable).
--schedule <CRON>	Cron schedule, 5 fields in UTC (“0 3 * * *”; default: on request only).
--size <SIZE>	Size: c0..c3 (default: the app’s).
--timeout-seconds <SECONDS>	Stop a run after this many seconds.
-- <COMMAND>...	The command and its arguments, after -- (runs in the app’s image).

zb apps jobs delete

Delete a job and its run history (asks first unless —yes).

zb apps jobs delete [OPTIONS] <APP> <JOB>

Argument	Description
<APP>	App name or id (app_…).
<JOB>	Job name or id (job_…).

zb apps jobs get

Show one job: schedule, command, limits and last run.

zb apps jobs get [OPTIONS] <APP> <JOB>

Argument	Description
<APP>	App name or id (app_…).
<JOB>	Job name or id (job_…).

zb apps jobs list

List an app’s jobs with their schedule and last run.

zb apps jobs list [OPTIONS] <APP>

Argument	Description
<APP>	App name or id (app_…).

zb apps jobs run

Run a job now; —wait waits for it to finish.

zb apps jobs run [OPTIONS] <APP> <JOB>

Argument	Description
<APP>	App name or id (app_…).
<JOB>	Job name or id (job_…).
--timeout <TIMEOUT>	Give up waiting after this many seconds (with —wait). Default 3600.
--wait	Wait until the run finishes (or failed).

zb apps jobs runs

List a job’s recent runs: state, exit code and duration.

zb apps jobs runs [OPTIONS] <APP> <JOB>

Argument	Description
<APP>	App name or id (app_…).
<JOB>	Job name or id (job_…).

zb apps jobs update

Change a job: schedule, command (after --), concurrency, limits, size, enabled.

zb apps jobs update [OPTIONS] <APP> <JOB> [-- <COMMAND>...]

Argument	Description
<APP>	App name or id (app_…).
<JOB>	Job name or id (job_…).
--backoff-limit <N>	Retries of a failed run.
--concurrency <CONCURRENCY>	When a run is due while one is running: forbid (default), replace or allow. One of forbid, replace, allow.
--disable	Disable the job (its schedule stops firing; manual runs still work).
--enable	Enable the job.
--schedule <CRON>	Cron schedule, 5 fields in UTC; "" makes the job on request only.
--size <SIZE>	Size: c0..c3; "" uses the app’s.
--timeout-seconds <SECONDS>	Stop a run after this many seconds.
-- <COMMAND>...	The command and its arguments, after -- (runs in the app’s image).

zb apps list

List the project’s apps (the global —project, else the default project).

zb apps list [OPTIONS]

zb apps logs

Print an app’s container logs, each line prefixed with its replica (-f follows them; —job-run shows a job run’s); —json prints the single-use stream URL instead.

zb apps logs [OPTIONS] <APP>

Argument	Description
<APP>	App name or id (app_…).
-f, --follow	Follow the stream until interrupted (the cell ends it after 30 minutes).
--job-run <RUN>	Logs of one job run (jrun_…, from zb apps jobs runs) instead of the app’s replicas.
--previous	The previous container’s logs (after a crash or an OOM kill).
--since <DURATION>	Only lines from the last DURATION (seconds, or 90s, 10m, 2h).
--tail <N>	Last N lines per replica (default 500, max 5000).

zb apps metrics

Show an app’s replicas, restarts, limits and recent CPU / memory samples.

zb apps metrics [OPTIONS] <APP>

Argument	Description
<APP>	App name or id (app_…).

zb apps releases

List an app’s releases, newest first (* marks the release the app runs).

zb apps releases [OPTIONS] <APP>

Argument	Description
<APP>	App name or id (app_…).

zb apps restart

Restart every replica with a rolling restart (recorded as a release).

zb apps restart [OPTIONS] <APP>

Argument	Description
<APP>	App name or id (app_…).

zb apps rollback

Roll back to an earlier release (default: the one before the current), pinned to that release’s digest.

zb apps rollback [OPTIONS] <APP>

Argument	Description
<APP>	App name or id (app_…).
--timeout <TIMEOUT>	Give up waiting after this many seconds (with —wait). Default 600.
--to <RELEASE>	Release to restore: its id (rel_…) or its number from zb apps releases.
--wait	Wait until the restored release serves (or failed).

zb apps scale

Change an app’s scaling: size, min/max replicas, CPU target and scale to zero.

zb apps scale [OPTIONS] <APP>

Argument	Description
<APP>	App name or id (app_…).
--cpu-target <PERCENT>	Average CPU percent the autoscaler keeps replicas at (default 70).
--idle-minutes <MINUTES>	Idle minutes before scaling to zero (default 15).
--max <N>	Maximum replicas; above —min the app autoscales on CPU (default 1).
--min <N>	Minimum replicas (default 1).
--no-scale-to-zero	Keep at least —min replicas running.
--scale-to-zero	Scale to zero replicas when idle; the next request wakes it (paid plans).
--size <SIZE>	Size of each replica: c0 (default), c1, c2, c3 (zb api GET /v1/sizes lists them).

zb apps start

Start a stopped app: its current release runs again.

zb apps start [OPTIONS] <APP>

Argument	Description
<APP>	App name or id (app_…).

zb apps stop

Stop an app: replicas go to zero and compute stops billing; releases, env, domains and jobs are kept.

zb apps stop [OPTIONS] <APP>

Argument	Description
<APP>	App name or id (app_…).

zb apps update

Change an app’s settings: scaling, port, protocol, health check, command, args or registry secret (rolls the running release).

zb apps update [OPTIONS] <APP>

Argument	Description
<APP>	App name or id (app_…).
--arg <ARG>	Override the image arguments, one per flag (repeat it).
--command <ARG>	Override the image entrypoint, one argument per flag (repeat it); "" restores the image’s.
--cpu-target <PERCENT>	Average CPU percent the autoscaler keeps replicas at (default 70).
--health-path <PATH>	HTTP readiness and liveness path, e.g. /healthz (default: a TCP check); "" clears it.
--idle-minutes <MINUTES>	Idle minutes before scaling to zero (default 15).
--max <N>	Maximum replicas; above —min the app autoscales on CPU (default 1).
--min <N>	Minimum replicas (default 1).
--no-scale-to-zero	Keep at least —min replicas running.
--port <PORT>	Container port the app listens on (default 8080).
--protocol <PROTOCOL>	http (default), tcp (TLS with SNI on the app host) or none (no ingress). One of http, tcp, none.
--registry-secret <SECRET>	Project secret with the registry credentials, for a private image (docker config JSON or user:token); "" clears it.
--scale-to-zero	Scale to zero replicas when idle; the next request wakes it (paid plans).
--size <SIZE>	Size of each replica: c0 (default), c1, c2, c3 (zb api GET /v1/sizes lists them).

zb backups

Backups, restores and point-in-time recovery.

Subcommand	What it does
zb backups create	Take a manual backup
zb backups get	Show one backup
zb backups health	Backup health across the org
zb backups list	List an instance’s backups
zb backups pitr-window	Show the point-in-time recovery window
zb backups restore	Restore a backup into a new instance (default) or in place
zb backups restores	List restores of an instance
zb backups settings	Show backup settings, or change them with flags

zb backups create

Take a manual backup.

zb backups create [OPTIONS] <INSTANCE>

Argument	Description
<INSTANCE>	Instance id.
--label <LABEL>

zb backups get

Show one backup.

zb backups get [OPTIONS] <INSTANCE> <BACKUP>

Argument	Description
<INSTANCE>	Instance id.
<BACKUP>	Backup id.

zb backups health

Backup health across the org.

zb backups health [OPTIONS]

zb backups list

List an instance’s backups.

zb backups list [OPTIONS] <INSTANCE>

Argument	Description
<INSTANCE>	Instance id.

zb backups pitr-window

Show the point-in-time recovery window.

zb backups pitr-window [OPTIONS] <INSTANCE>

Argument	Description
<INSTANCE>	Instance id.

zb backups restore

Restore a backup into a new instance (default) or in place.

zb backups restore [OPTIONS] <INSTANCE> <BACKUP>

Argument	Description
<INSTANCE>	Instance id.
<BACKUP>	Backup id.
--at <AT>	Point in time (RFC 3339) inside the PITR window.
--confirm <CONFIRM>	The instance name, typed as confirmation for —in-place.
--in-place	Restore over the source instance (asks you to type its name).
--name <NAME>	Name of the new instance.
--size <SIZE>	Size of the new instance.

zb backups restores

List restores of an instance.

zb backups restores [OPTIONS] <INSTANCE>

Argument	Description
<INSTANCE>	Instance id.

zb backups settings

Show backup settings, or change them with flags.

zb backups settings [OPTIONS] <INSTANCE>

Argument	Description
<INSTANCE>	Instance id.
--cross-region-target <CROSS_REGION_TARGET>	Region to copy backups to.
--frequency <FREQUENCY>	hourly, daily or weekly (capped by the plan).
--pitr <PITR>	Continuous archiving for point-in-time recovery.
--retention-days <RETENTION_DAYS>
--time <SCHEDULE_TIME_UTC>	Backup window start, HH:MM UTC.

zb completion

Print a shell completion script.

zb completion [OPTIONS] <SHELL>

Argument	Description
<SHELL>	Target shell [possible values: bash, elvish, fish, powershell, zsh].

zb connect

Open the engine’s shell (psql, mysql, valkey-cli, mongosh) with TLS and a one-time credential. The credential is passed through the child’s environment where the client supports it and is never written to disk or shell history.

zb connect [OPTIONS] <ID> [-- <EXTRA>...]

Argument	Description
<ID>	Instance id.
--ca <CA>	CA bundle to verify the server with (default: the system trust store).
--client <CLIENT>	Client binary to run instead of the engine default.
--db <DB>	Database name (Postgres default postgres, MySQL none).
--print	Print a masked connection URI instead of spawning a client (no credential is revealed).
-- <EXTRA>...	Extra arguments passed to the client after --.

zb cost-report

Monthly cost allocation per team and cost centre.

zb cost-report [OPTIONS]

Argument	Description
--csv	Print the server’s CSV export.
--month <MONTH>	YYYY-MM (UTC); default: the current month.

zb db

Declarative schemas as code (Supabase CLI layout and history table): zb db pull writes the live schema to supabase/schemas/SCHEMA.sql (edit those files: add a column, an index, a policy, …) zb db diff -f N writes the migration that brings a database to them, supabase/migrations/TIMESTAMP_N.sql zb db push applies the pending migrations, recorded in supabase_migrations.schema_migrations Branch-aware: a branch is its own instance with its own data, so try a change there first: zb api POST /v1/orgs/{org}/instances/INSTANCE/branches -d ’{“name”:“dev”}’ zb db diff INSTANCE —branch dev -f add_col # plan against the branch zb db push INSTANCE —branch dev # apply it there and verify zb db push INSTANCE # then promote the same migration file The diff loads the declared files into a shadow Postgres and validates the plan there: an embedded Postgres of the live server’s major (15-18) started for the command, or —shadow-url / ZB_SHADOW_DB_URL (a scratch server where you may CREATE DATABASE; needed for extensions the embedded build lacks: vector, postgis, …). PostgreSQL instances only.

Subcommand	What it does
zb db diff	Plan the migration from the database to the declared schema; -f writes it as a migration file
zb db migrations	Local migration files against the database’s history
zb db pull	Write the live schema as declared SQL files (supabase/schemas/SCHEMA.sql)
zb db push	Apply pending migrations (supabase/migrations) in filename order, each in its own transaction

zb db diff

Diff the database against the declared schema (<dir>/schemas/*.sql) and print the SQL that migrates it, each statement’s hazards as -- hazard: comments. With -f <name> it is written to <dir>/migrations/<UTC timestamp>_<name>.sql instead. The plan is validated on the shadow database. Index builds are plain (the migration stays transactional) unless —concurrent-indexes.

zb db diff [OPTIONS] [INSTANCE]

Argument	Description
<INSTANCE>	Instance id; with —branch, the instance whose branch to use.
--branch <BRANCH>	Branch to use: a branch name, git branch or instance id of INSTANCE’s branches (alone: a branch instance id).
--ca <PATH>	CA bundle to verify the instance with (default: the system trust store).
--concurrent-indexes	Build and drop indexes CONCURRENTLY (the migration then runs outside a transaction).
--db <NAME>	Database name on the instance (default postgres).
--db-url <URL>	Connect to this Postgres URL instead of an instance (local development; no credential reveal).
--dir <DIR>	Project directory holding schemas/ and migrations/. Default supabase.
-f, --file <NAME>	Write the plan as a new migration file with this name.
--schema <SCHEMA>	Schema to manage; repeat or comma-separate (default public).
--shadow-url <URL>	Scratch Postgres for loading the declared schema and validating plans (default: an embedded Postgres started for the command). Env ZB_SHADOW_DB_URL.

zb db migrations

Local migration files against the database’s history.

Subcommand	What it does
zb db migrations list	List local and applied migrations side by side

zb db migrations list

List local and applied migrations side by side.

zb db migrations list [OPTIONS] [INSTANCE]

Argument	Description
<INSTANCE>	Instance id; with —branch, the instance whose branch to use.
--branch <BRANCH>	Branch to use: a branch name, git branch or instance id of INSTANCE’s branches (alone: a branch instance id).
--ca <PATH>	CA bundle to verify the instance with (default: the system trust store).
--db <NAME>	Database name on the instance (default postgres).
--db-url <URL>	Connect to this Postgres URL instead of an instance (local development; no credential reveal).
--dir <DIR>	Project directory holding schemas/ and migrations/. Default supabase.

zb db pull

Read the database’s schema (each —schema) and write it as DDL to <dir>/schemas/<schema>.sql, the declared schema zb db diff compares against. Refuses to overwrite existing files without —force.

zb db pull [OPTIONS] [INSTANCE]

Argument	Description
<INSTANCE>	Instance id; with —branch, the instance whose branch to use.
--branch <BRANCH>	Branch to use: a branch name, git branch or instance id of INSTANCE’s branches (alone: a branch instance id).
--ca <PATH>	CA bundle to verify the instance with (default: the system trust store).
--db <NAME>	Database name on the instance (default postgres).
--db-url <URL>	Connect to this Postgres URL instead of an instance (local development; no credential reveal).
--dir <DIR>	Project directory holding schemas/ and migrations/. Default supabase.
--force	Overwrite existing declared-schema files.
--schema <SCHEMA>	Schema to manage; repeat or comma-separate (default public).
--shadow-url <URL>	Scratch Postgres for loading the declared schema and validating plans (default: an embedded Postgres started for the command). Env ZB_SHADOW_DB_URL.

zb db push

Apply the local migrations the database has not recorded in supabase_migrations.schema_migrations, in filename order. Each runs in its own transaction with its history row; a migration using CONCURRENTLY runs statement by statement outside a transaction. Versions the database has but the directory lacks are reported, not touched. —dry-run lists what would run.

zb db push [OPTIONS] [INSTANCE]

Argument	Description
<INSTANCE>	Instance id; with —branch, the instance whose branch to use.
--branch <BRANCH>	Branch to use: a branch name, git branch or instance id of INSTANCE’s branches (alone: a branch instance id).
--ca <PATH>	CA bundle to verify the instance with (default: the system trust store).
--db <NAME>	Database name on the instance (default postgres).
--db-url <URL>	Connect to this Postgres URL instead of an instance (local development; no credential reveal).
--dir <DIR>	Project directory holding schemas/ and migrations/. Default supabase.
--dry-run	List the migrations that would run, change nothing.

zb docs

Generate the CLI reference (Markdown or a man page) from this binary.

zb docs [OPTIONS]

Argument	Description
--check	With —mdx: fail instead of writing when the file is out of date.
--format <FORMAT>	One of markdown, man. Default markdown.
--mdx <MDX>	Write the generated reference between the markers in this .mdx file (apps/docs/src/content/docs/reference/cli.mdx).

zb functions

Edge functions: deploy, list, invoke, logs, versions, triggers (Deno / TypeScript, Supabase compatible).

Subcommand	What it does
zb functions cron	Cron triggers of a function
zb functions delete	Delete a function, its versions and triggers
zb functions deploy	Bundle (esbuild; npm:/jsr:/URL imports stay external) and deploy functions; —all deploys every directory
zb functions get	Show a function, its active version and triggers
zb functions invoke	Run a function once through its cell (verify_jwt does not apply; limits do) and print the response
zb functions list	List the project’s functions
zb functions logs	Invocation logs from the project’s cell (—follow streams)
zb functions new	Create <dir>/<NAME>/index.ts from a template (hello-world, stripe-webhook, openai-proxy, cron-job)
zb functions rollback	Make an earlier version active again
zb functions set	Change a function’s settings (—verify-jwt / —no-verify-jwt, —memory, —timeout, —enable / —disable)
zb functions triggers	Cron, database, storage, auth and queue triggers of a function
zb functions versions	List a function’s deployed versions

zb functions cron

Cron triggers of a function.

Subcommand	What it does
zb functions cron add	Run NAME on a schedule (5-field crontab or @hourly, … in —timezone)
zb functions cron list	List NAME’s cron triggers
zb functions cron rm	Remove a cron trigger

zb functions cron add

Run NAME on a schedule (5-field crontab or @hourly, … in —timezone).

zb functions cron add [OPTIONS]

Argument	Description
--body <BODY>	JSON body of each run.
--missed-runs <MISSED_RUNS>	After downtime: latest, all or skip. Default latest.
--schedule <SCHEDULE>	Crontab, e.g. ”*/5 * * * *”.
--timezone <TIMEZONE>	IANA time zone. Default UTC.

zb functions cron list

List NAME’s cron triggers.

zb functions cron list [OPTIONS]

zb functions cron rm

Remove a cron trigger.

zb functions cron rm [OPTIONS]

zb functions delete

Delete a function, its versions and triggers.

zb functions delete [OPTIONS]

zb functions deploy

Bundle (esbuild; npm:/jsr:/URL imports stay external) and deploy functions; —all deploys every directory.

zb functions deploy [OPTIONS] [NAME...]

Argument	Description
<NAME...>
--all	Deploy every function directory.
--dir <DIR>	Functions directory (default supabase/functions, else functions).
--entrypoint <ENTRYPOINT>	Entrypoint file (default <dir>/<name>/index.ts).
--import-map <IMPORT_MAP>	Import map (default <dir>/<name>/deno.json, else <dir>/import_map.json).
--memory <MEMORY>	Memory per isolate (MiB, within the plan).
--no-activate	Upload the version without making it active.
--no-verify-jwt	Let anyone call the function (webhooks); default: config.toml, else on.
--timeout <TIMEOUT>	Wall-clock limit (ms, within the plan).
--verify-jwt	Require a project JWT or key (the default for a new function).

zb functions get

Show a function, its active version and triggers.

zb functions get [OPTIONS]

zb functions invoke

Run a function once through its cell (verify_jwt does not apply; limits do) and print the response.

zb functions invoke [OPTIONS]

Argument	Description
-d, --data <DATA>	Request body (JSON text).
-H, --header <HEADER>	Request header Name: value (repeatable).
-X, --method <METHOD>	HTTP method. Default POST.
--path <PATH>	Path and query after the function name (/sub?x=1).

zb functions list

List the project’s functions.

zb functions list [OPTIONS]

zb functions logs

Invocation logs from the project’s cell (—follow streams).

zb functions logs [OPTIONS] [NAME]

Argument	Description
<NAME>
-f, --follow	Stream new lines.
--insecure	Skip TLS verification of the cell (private CA).
--level <LEVEL>	Only debug, info, warn or error.
--limit <LIMIT>	Lines (newest). Default 100.

zb functions new

Create <dir>/<NAME>/index.ts from a template (hello-world, stripe-webhook, openai-proxy, cron-job).

zb functions new [OPTIONS]

Argument	Description
--dir <DIR>	Functions directory.
-t, --template <TEMPLATE>	Template. Default hello-world.

zb functions rollback

Make an earlier version active again.

zb functions rollback [OPTIONS]

zb functions set

Change a function’s settings (—verify-jwt / —no-verify-jwt, —memory, —timeout, —enable / —disable).

zb functions set [OPTIONS]

Argument	Description
--disable	Disable the function (403).
--enable	Enable the function.
--memory <MEMORY>	Memory per isolate (MiB, 0 = plan default).
--no-verify-jwt	Let anyone call the function.
--timeout <TIMEOUT>	Wall-clock limit (ms, 0 = plan maximum).
--verify-jwt	Require a project JWT or key.

zb functions triggers

Cron, database, storage, auth and queue triggers of a function.

Subcommand	What it does
zb functions triggers add	Add a trigger to NAME (—kind cron|database|storage|auth|queue)
zb functions triggers deliveries	Deliveries of a storage or auth trigger, read from the project’s cell (—status dead: the dead letters)
zb functions triggers disable	Disable a trigger
zb functions triggers enable	Enable a trigger
zb functions triggers list	List NAME’s triggers
zb functions triggers replay	Queue a failed storage or auth delivery again
zb functions triggers rm	Remove a trigger (a database trigger’s webhook goes with it)

zb functions triggers add

Add a trigger to NAME (—kind cron|database|storage|auth|queue).

zb functions triggers add [OPTIONS]

Argument	Description
--batch-size <BATCH_SIZE>	queue: messages read at a time (default 5).
--body <BODY>	cron: JSON body of each run.
--bucket <BUCKET>	storage: bucket id.
--dead-letter-queue <DEAD_LETTER_QUEUE>	queue: where failed messages go (default <queue>_dlq).
--disabled	Create the trigger disabled.
--events <EVENTS>	database: insert,update,delete; storage: created,updated,deleted; auth: signup,login,user_updated,user_deleted.
--kind <KIND>	cron, database, storage, auth or queue.
--max-retries <MAX_RETRIES>	storage, auth, queue: retries before the dead letter (default 3). Default -1.
--missed-runs <MISSED_RUNS>	cron: after downtime latest, all or skip. Default latest.
--prefix <PREFIX>	storage: only object names starting with it.
--queue <QUEUE>	queue: pgmq queue of the primary database.
--schedule <SCHEDULE>	cron: crontab, e.g. ”*/5 * * * *”.
--table <TABLE>	database: [schema.]table.
--timezone <TIMEZONE>	cron: IANA time zone. Default UTC.
--visibility <VISIBILITY>	queue: visibility timeout in seconds (default the function’s timeout + 30).

zb functions triggers deliveries

Deliveries of a storage or auth trigger, read from the project’s cell (—status dead: the dead letters).

zb functions triggers deliveries [OPTIONS]

Argument	Description
--insecure	Skip TLS verification of the cell (private CA).
--status <STATUS>	pending, retrying, delivered or dead.

zb functions triggers disable

Disable a trigger.

zb functions triggers disable [OPTIONS]

zb functions triggers enable

Enable a trigger.

zb functions triggers enable [OPTIONS]

zb functions triggers list

List NAME’s triggers.

zb functions triggers list [OPTIONS]

zb functions triggers replay

Queue a failed storage or auth delivery again.

zb functions triggers replay [OPTIONS]

zb functions triggers rm

Remove a trigger (a database trigger’s webhook goes with it).

zb functions triggers rm [OPTIONS]

zb functions versions

List a function’s deployed versions.

zb functions versions [OPTIONS]

zb gen

Generate code from a project: zb gen types prints supabase-js compatible TypeScript types of the data API’s schemas.

Subcommand	What it does
zb gen types	TypeScript types of the data API’s schemas (supabase-js Database)

zb gen types

Print the Database type supabase-js uses (createClient<Database>(url, key)) for the schemas the project’s data API exposes: tables and views (Row / Insert / Update / Relationships), functions, enums and composite types. Reads the primary database’s catalog through the API; —secret-key reads it through /query/v1 on the project endpoint instead, —db-url from any Postgres you can reach.

zb gen types [OPTIONS]

Argument	Description
--db-url <DB_URL>	Read the catalog from this Postgres URL instead of the project.
--lang <LANG>	Output language (typescript). Default typescript.
-o, --output <OUTPUT>	Write to this file instead of stdout.
--schema <SCHEMA>	Comma-separated schemas (default: the schemas the data API exposes, or public with —db-url).
--secret-key <SECRET_KEY>	Project secret key: read the catalog through /query/v1 (env ZB_PROJECT_SECRET_KEY).

zb instances

Manage database instances.

Subcommand	What it does
zb instances create	Create an instance (status starts at requested)
zb instances credentials	One-time credential reveal and rotation
zb instances delete	Delete an instance (data retained per plan policy)
zb instances erase	Delete an instance and every backup, and issue an erasure certificate. Irreversible
zb instances get	Show one instance
zb instances list	List instances in the org (only the project’s with an explicit —project)
zb instances pause	Pause an instance: compute stops, storage is kept and billed
zb instances resize	Change an instance’s size
zb instances resume	Resume a paused instance

zb instances create

Create an instance (status starts at requested).

zb instances create [OPTIONS] --engine <ENGINE>

Argument	Description
--cost-centre <COST_CENTRE>	Cost-centre tag for chargeback.
--engine <ENGINE>	Engine id (postgres, mysql, valkey, ferretdb, libsql, …). Required.
--engine-version <ENGINE_VERSION>
--ha	High availability (standby replica).
--name <NAME>
--placement <PLACEMENT>	shared (default), dedicated-node or secure.
--region <REGION>
--replicas <REPLICAS>	Read replicas.
--size <SIZE>	Size id (f0 on the free plan, s1, s2, m2, …). Default: f0 on free orgs, s1 otherwise.
--storage-gb <STORAGE_GB>
--timeout <TIMEOUT>	Give up waiting after this many seconds (with —wait). Default 900.
--wait	Wait until the instance is ready (or failed).

zb instances credentials

One-time credential reveal and rotation.

Subcommand	What it does
zb instances credentials reveal	Reveal the instance credentials once (rate limited and audited; needs MFA if you turned it on or your org requires it)
zb instances credentials rotate	Rotate the credentials; old and new stay valid for a short overlap window

zb instances credentials reveal

Reveal the instance credentials once (rate limited and audited; needs MFA if you turned it on or your org requires it).

zb instances credentials reveal [OPTIONS] <ID>

Argument	Description
<ID>	Resource id.

zb instances credentials rotate

Rotate the credentials; old and new stay valid for a short overlap window.

zb instances credentials rotate [OPTIONS] <ID>

Argument	Description
<ID>	Resource id.

zb instances delete

Delete an instance (data retained per plan policy).

zb instances delete [OPTIONS] <ID>

Argument	Description
<ID>	Resource id.

zb instances erase

Delete an instance and every backup, and issue an erasure certificate. Irreversible.

zb instances erase [OPTIONS] <ID>

Argument	Description
<ID>	Resource id.
--confirm <CONFIRM>	The instance name, typed as confirmation (prompted when omitted).

zb instances get

Show one instance.

zb instances get [OPTIONS] <ID>

Argument	Description
<ID>	Resource id.

zb instances list

List instances in the org (only the project’s with an explicit —project).

zb instances list [OPTIONS]

zb instances pause

Pause an instance: compute stops, storage is kept and billed.

zb instances pause [OPTIONS] <ID>

Argument	Description
<ID>	Resource id.

zb instances resize

Change an instance’s size.

zb instances resize [OPTIONS] --size <SIZE> <ID>

Argument	Description
<ID>	Resource id.
--size <SIZE>	New size id (see zb api GET /v1/sizes). Required.

zb instances resume

Resume a paused instance.

zb instances resume [OPTIONS] <ID>

Argument	Description
<ID>	Resource id.

zb login

Save an API key (and API URL) in the OS config directory.

zb login [OPTIONS]

Argument	Description
--default-org <DEFAULT_ORG>	Default org id to use.
--default-project <DEFAULT_PROJECT>	Default project id to use.
--key <KEY>	API key (zb_...); prompted on stdin when omitted. Alias --api-key. Env ZB_API_KEY.

zb logout

Remove the saved API key.

zb logout [OPTIONS]

zb logs

Stream an instance’s events (status changes, backups, migrations).

zb logs [OPTIONS] <INSTANCE>

Argument	Description
<INSTANCE>	Instance id.
-f, --follow	Follow the stream until interrupted.

zb members

Org members and invites.

Subcommand	What it does
zb members invite	Invite someone by email
zb members invites	List pending invites
zb members list	List org members
zb members remove	Remove a member from the org
zb members set-role	Change a member’s org role

zb members invite

Invite someone by email.

zb members invite [OPTIONS] <EMAIL>

Argument	Description
<EMAIL>	Email address.
--role <ROLE>

zb members invites

List pending invites.

zb members invites [OPTIONS]

zb members list

List org members.

zb members list [OPTIONS]

zb members remove

Remove a member from the org.

zb members remove [OPTIONS] <USER>

Argument	Description
<USER>	User id.

zb members set-role

Change a member’s org role.

zb members set-role [OPTIONS] <USER> <ROLE>

Argument	Description
<USER>	User id.
<ROLE>	Role name.

zb migrate

Move a database into Databasezy.

zb migrate [OPTIONS] [COMMAND]

Argument	Description
--container <NAME|ID>	With --from local: run the dump tool inside this running Docker container (name or id) with docker exec, using the tool in its image and the container’s own credentials (override with ZB_DB_USER / ZB_DB_PASSWORD, forwarded by name, never on the command line).
--create	Create a new target instance first (in the global —project).
--db <DB>	Database name for --from local (also PGDATABASE / MYSQL_DATABASE). With —container it defaults to the container’s POSTGRES_DB / MYSQL_DATABASE.
--drop-target	Drop existing objects in the target first.
--dry-run	Print the plan and preflight checklist without starting anything.
--engine <ENGINE>	Engine hint when it cannot be inferred (.sql files, local, http sources).
--exclude <EXCLUDE>	Tables / collections / key patterns to skip.
--from <FROM>	Source: a connection URL, a file (.sql/.dump/.sql.gz/.rdb/.sqlite/.db/.duckdb/.bson.tar/.csv/.parquet), local (dump a server on this machine, or inside a Docker container with —container), d1:<database> (export a Cloudflare D1 database with wrangler) or another instance id.
--include <INCLUDE>	Tables / collections / key patterns to copy (comma separated, repeatable).
--mode <MODE>	copy (default) or copy_and_sync. Default copy.
--name <NAME>	Name of the created instance (with —create).
--no-wait	Return right after the migration is accepted instead of following progress.
--provider <PROVIDER>	Provider preset when the hostname does not say which (netlify, cloud-sql, vercel-postgres, vercel-kv, …). A line pasted from an env file (--from 'KV_URL=rediss://...') also hints it by the variable name.
--reverse-sync	After cutover, replicate the new instance back to the source so you can roll back (Postgres, --mode copy_and_sync).
--size <SIZE>	Size of the created instance (with —create).
--to <TO>	Target instance id.

Subcommand	What it does
zb migrate cancel	Cancel a running migration
zb migrate cutover	Drain the last writes, copy sequences, stop continuous sync and report the downtime (copy_and_sync migrations). Waits for the cutover to finish unless —no-wait
zb migrate status	Show status and progress of a migration
zb migrate supabase	Import a Supabase project’s users (with their passwords), storage and functions into the current project

zb migrate cancel

Cancel a running migration.

zb migrate cancel [OPTIONS] <ID>

Argument	Description
<ID>	Resource id.

zb migrate cutover

Drain the last writes, copy sequences, stop continuous sync and report the downtime (copy_and_sync migrations). Waits for the cutover to finish unless —no-wait.

zb migrate cutover [OPTIONS] <ID>

Argument	Description
<ID>	Resource id.
--no-wait	Return once the cutover is accepted.
--timeout <TIMEOUT>	Give up waiting after this many seconds (the cutover keeps running). Default 600.

zb migrate status

Show status and progress of a migration.

zb migrate status [OPTIONS] <ID>

Argument	Description
<ID>	Resource id.

zb migrate supabase

Imports auth users with their ids, password hashes and identities, storage buckets and objects, and the Edge Functions in supabase/functions into the current project (—project), and reports row-level security policies that call Supabase-only functions. Supabase credentials come from the environment only: SUPABASE_DB_URL, SUPABASE_SERVICE_ROLE_KEY, SUPABASE_ACCESS_TOKEN (optional: deployed functions and secret names), SUPABASE_S3_ACCESS_KEY_ID / SUPABASE_S3_SECRET_ACCESS_KEY (optional). They stay on this machine. Run with —dry-run first. Afterwards move the database with zb migrate --from "$SUPABASE_DB_URL" --to <primary instance>.

zb migrate supabase [OPTIONS]

Argument	Description
--dry-run	Read and report what would move; change nothing.
--functions-dir <FUNCTIONS_DIR>	Functions source (default supabase/functions, else functions).
--only <ONLY>	Import only these parts (auth, storage, functions, policies; comma separated).
--report <REPORT>	Write the JSON report to this file.
--s3-endpoint <S3_ENDPOINT>	Read objects through Supabase’s S3 endpoint (https://<ref>.supabase.co/storage/v1/s3) instead of the Storage API.
--s3-region <S3_REGION>	Region of the S3 endpoint (Project settings → Storage).
--supabase-url <SUPABASE_URL>	The Supabase project URL, https://<ref>.supabase.co (default: $SUPABASE_URL).

zb orgs

Organizations you belong to; use sets the default.

Subcommand	What it does
zb orgs create	Create an organization (you become its owner)
zb orgs get	Show one organization (default: the current one)
zb orgs list	List organizations you are a member of
zb orgs use	Save the default org in the config file

zb orgs create

Create an organization (you become its owner).

zb orgs create [OPTIONS] --name <NAME>

Argument	Description
--name <NAME>	Required.
--region <REGION>	Default region for new instances.
--slug <SLUG>

zb orgs get

Show one organization (default: the current one).

zb orgs get [OPTIONS] [ID]

Argument	Description
<ID>	Resource id.

zb orgs list

List organizations you are a member of.

zb orgs list [OPTIONS]

zb orgs use

Save the default org in the config file.

zb orgs use [OPTIONS] <ID>

Argument	Description
<ID>	Resource id.

zb projects

Projects in the org; use sets the default.

Subcommand	What it does
zb projects create	Create a project
zb projects delete	Delete an empty project
zb projects get	Show one project
zb projects jwt-keys	The project’s JWT signing keys (public halves; private keys stay in the cell)
zb projects keys	Project API keys: publishable (browsers, role anon) and secret (servers, role service_role)
zb projects list	List projects in the org
zb projects show	Show a project’s ref, endpoint and JWKS URL (default: the current project)
zb projects use	Save the default project in the config file

zb projects create

Create a project.

zb projects create [OPTIONS] --name <NAME>

Argument	Description
--name <NAME>	Required.
--slug <SLUG>
--team <TEAM>	Owning team id.

zb projects delete

Delete an empty project.

zb projects delete [OPTIONS] <ID>

Argument	Description
<ID>	Resource id.

zb projects get

Show one project.

zb projects get [OPTIONS] <ID>

Argument	Description
<ID>	Resource id.

zb projects jwt-keys

The project’s JWT signing keys (public halves; private keys stay in the cell).

Subcommand	What it does
zb projects jwt-keys list	List the signing keys and the JWKS URL
zb projects jwt-keys rotate	Rotate the signing key: the old key keeps verifying, the one before it is retired

zb projects jwt-keys list

List the signing keys and the JWKS URL.

zb projects jwt-keys list [OPTIONS]

zb projects jwt-keys rotate

Rotate the signing key: the old key keeps verifying, the one before it is retired.

zb projects jwt-keys rotate [OPTIONS]

zb projects keys

Project API keys: publishable (browsers, role anon) and secret (servers, role service_role).

Subcommand	What it does
zb projects keys create	Create a project key; the key is printed once
zb projects keys list	List the project’s active keys (the key itself is never shown again)
zb projects keys revoke	Revoke a project key; requests with it are refused within seconds

zb projects keys create

Create a project key; the key is printed once.

zb projects keys create [OPTIONS] --name <NAME>

Argument	Description
--expires <EXPIRES>	Expiry (RFC 3339; default: never).
--kind <KIND>	publishable (safe in browsers) or secret (servers only, bypasses row-level security). One of publishable, secret. Default publishable.
--name <NAME>	Name, e.g. web-app. Required.
--scope <SCOPE>	Scopes recorded with the key (comma separated; default: *).

zb projects keys list

List the project’s active keys (the key itself is never shown again).

zb projects keys list [OPTIONS]

zb projects keys revoke

Revoke a project key; requests with it are refused within seconds.

zb projects keys revoke [OPTIONS] <ID>

Argument	Description
<ID>	Resource id.

zb projects list

List projects in the org.

zb projects list [OPTIONS]

zb projects show

Show a project’s ref, endpoint and JWKS URL (default: the current project).

zb projects show [OPTIONS] [ID]

Argument	Description
<ID>	Resource id.

zb projects use

Save the default project in the config file.

zb projects use [OPTIONS] <ID>

Argument	Description
<ID>	Resource id.

zb realtime

Project realtime: broadcast, presence and database changes over WebSockets, database webhooks.

Subcommand	What it does
zb realtime disable	Disable realtime (connections close, the replication slot is dropped)
zb realtime enable	Enable realtime on the project (/realtime/v1)
zb realtime publish	Set the tables whose changes reach postgres_changes subscribers (none = publish nothing)
zb realtime show	Show realtime settings, the limits in force and the WebSocket URL
zb realtime webhooks	Database webhooks: POST table changes to a URL or a project function

zb realtime disable

Disable realtime (connections close, the replication slot is dropped).

zb realtime disable [OPTIONS]

zb realtime enable

Enable realtime on the project (/realtime/v1).

zb realtime enable [OPTIONS]

Argument	Description
--private-only	Refuse public channels (RLS on realtime.messages decides).

zb realtime publish

Set the tables whose changes reach postgres_changes subscribers (none = publish nothing).

zb realtime publish [OPTIONS]

Argument	Description
--events <EVENTS>	Events: INSERT, UPDATE, DELETE or *. Default [*].

zb realtime show

Show realtime settings, the limits in force and the WebSocket URL.

zb realtime show [OPTIONS]

zb realtime webhooks

Database webhooks: POST table changes to a URL or a project function.

Subcommand	What it does
zb realtime webhooks create	Create a webhook; the signing secret is printed once
zb realtime webhooks delete	Delete a webhook (queued deliveries are dead-lettered)
zb realtime webhooks deliveries	Recent deliveries of a webhook (—dead for the dead letters)
zb realtime webhooks list	List the project’s database webhooks
zb realtime webhooks replay	Queue a failed or dead-lettered delivery again

zb realtime webhooks create

Create a webhook; the signing secret is printed once.

zb realtime webhooks create [OPTIONS] --name <NAME> --table <TABLE>

Argument	Description
--events <EVENTS>	INSERT, UPDATE, DELETE or *. Default [INSERT].
--function <FUNCTION>	Project function to call instead of a URL.
--name <NAME>	Name. Required.
--table <TABLE>	Table (schema.table; public when no schema). Required.
--url <URL>	HTTPS URL to POST to.

zb realtime webhooks delete

Delete a webhook (queued deliveries are dead-lettered).

zb realtime webhooks delete [OPTIONS]

zb realtime webhooks deliveries

Recent deliveries of a webhook (—dead for the dead letters).

zb realtime webhooks deliveries [OPTIONS]

Argument	Description
--dead	Only dead-lettered deliveries.

zb realtime webhooks list

List the project’s database webhooks.

zb realtime webhooks list [OPTIONS]

zb realtime webhooks replay

Queue a failed or dead-lettered delivery again.

zb realtime webhooks replay [OPTIONS]

zb sandbox

Sandboxes: short-lived isolated containers to run code in (exec, files, snapshots).

Subcommand	What it does
zb sandbox cp	Copy a file into a sandbox (zb sandbox cp ./data.csv sbx_...:data.csv) or out of it (zb sandbox cp sbx_...:out.png .)
zb sandbox create	Create a sandbox; prints its id (no network unless —egress allows it)
zb sandbox delete	Stop a sandbox and remove it from the list
zb sandbox exec	Run a command (-- python3 main.py) or code (--code file.py) in a sandbox; streams its output and exits with its code
zb sandbox get	Show a sandbox: status, template, size, egress, timeouts and price
zb sandbox kill	Stop a sandbox now (its files are gone unless snapshotted)
zb sandbox list	List the project’s sandboxes (running ones; —all includes ended ones)
zb sandbox ls	List a directory of a sandbox (default /workspace)
zb sandbox snapshot	Snapshot a sandbox’s /workspace (restore with zb sandbox create --from-snapshot)

zb sandbox cp

Copy a file into a sandbox (zb sandbox cp ./data.csv sbx_...:data.csv) or out of it (zb sandbox cp sbx_...:out.png .).

zb sandbox cp [OPTIONS] <SRC> <DST>

Argument	Description
<SRC>	Local file (- = stdin) or SANDBOX:PATH.
<DST>	SANDBOX:PATH or a local file / directory (- = stdout).

zb sandbox create

Create a sandbox; prints its id (no network unless —egress allows it).

zb sandbox create [OPTIONS]

Argument	Description
--allow <ALLOW>	Allowlist rule (host[:ports] or public CIDR[:ports]); implies —egress allowlist (repeat it).
--egress <EGRESS>	Network: none (default), internet or allowlist. One of none, internet, allowlist.
--env <KEY=VALUE>	Environment variable KEY=VALUE (repeat it).
--from-snapshot <FROM_SNAPSHOT>	Restore /workspace from a snapshot (snap_…).
--idle-timeout <SECONDS>	Stop after this many seconds without exec (default 120).
--name <NAME>	Optional label.
--secret <ENV=SECRET@HOSTS>	Cloaked project secret ENV=SECRET@host[,host]: the sandbox sees a placeholder, the proxy adds the value for those hosts only.
--size <SIZE>	Size: x1 (default), x2 or x4.
--template <TEMPLATE>	Template: python (default), node or base.
--timeout <SECONDS>	Hard lifetime in seconds (default 300; 0 with —idle-timeout = until idle).

zb sandbox delete

Stop a sandbox and remove it from the list.

zb sandbox delete [OPTIONS] <ID>

Argument	Description
<ID>	Sandbox id (sbx_…).

zb sandbox exec

Run a command (-- python3 main.py) or code (--code file.py) in a sandbox; streams its output and exits with its code.

zb sandbox exec [OPTIONS] <ID> [-- <COMMAND>...]

Argument	Description
<ID>	Sandbox id (sbx_…).
--code <FILE>	Run this file (- = stdin) with —language instead of a command.
--cwd <CWD>	Working directory (default /workspace).
--env <KEY=VALUE>	Variable for this run KEY=VALUE (repeat it).
--language <LANGUAGE>	Interpreter of —code: python (default), node or bash. One of python, node, bash.
--stdin <FILE>	Send this file (- = this terminal’s stdin) as the command’s standard input.
--timeout <SECONDS>	Kill the run after this many seconds (default 60).
-- <COMMAND>...	The command and its arguments after -- (an argv: no shell unless you run sh -c).

zb sandbox get

Show a sandbox: status, template, size, egress, timeouts and price.

zb sandbox get [OPTIONS] <ID>

Argument	Description
<ID>	Sandbox id (sbx_…).

zb sandbox kill

Stop a sandbox now (its files are gone unless snapshotted).

zb sandbox kill [OPTIONS] <ID>

Argument	Description
<ID>	Sandbox id (sbx_…).

zb sandbox list

List the project’s sandboxes (running ones; —all includes ended ones).

zb sandbox list [OPTIONS]

Argument	Description
--all	Include stopped, killed and expired sandboxes.

zb sandbox ls

List a directory of a sandbox (default /workspace).

zb sandbox ls [OPTIONS] <ID> [PATH]

Argument	Description
<ID>	Sandbox id (sbx_…).
<PATH>	Directory (default /workspace).

zb sandbox snapshot

Snapshot a sandbox’s /workspace (restore with zb sandbox create --from-snapshot).

zb sandbox snapshot [OPTIONS] <ID>

Argument	Description
<ID>	Sandbox id (sbx_…).
--retention-days <RETENTION_DAYS>	Keep the snapshot this many days (default 7).

zb secrets

Function secrets of the project (names only are ever shown).

Subcommand	What it does
zb secrets list	List the secret names
zb secrets set	Set secrets (NAME=VALUE, —env-file .env, —ref NAME=instance:<id>:app)
zb secrets unset	Remove secrets

zb secrets list

List the secret names.

zb secrets list [OPTIONS]

zb secrets set

Set secrets (NAME=VALUE, —env-file .env, —ref NAME=instance:<id>:app).

zb secrets set [OPTIONS] [NAME=VALUE...]

Argument	Description
<NAME=VALUE...>
--env-file <ENV_FILE>	Read NAME=VALUE lines from a file.
--ref <REF>	NAME=instance:<id>:app (repeatable).

zb secrets unset

Remove secrets.

zb secrets unset [OPTIONS]

zb ssh-key

SSH public keys on your account (workspace SSH through the bastion).

Subcommand	What it does
zb ssh-key add	Register a public key (default: the first of ~/.ssh/id_ed25519.pub, id_ecdsa.pub, id_rsa.pub)
zb ssh-key list	List the SSH keys on your account
zb ssh-key rm	Remove an SSH key from your account; new sessions with it are refused

zb ssh-key add

Register a public key (default: the first of ~/.ssh/id_ed25519.pub, id_ecdsa.pub, id_rsa.pub).

zb ssh-key add [OPTIONS] [PATH]

Argument	Description
<PATH>	Public key file (.pub); private keys are refused.
--name <NAME>	Label (default: the key’s comment, else the file name).

zb ssh-key list

List the SSH keys on your account.

zb ssh-key list [OPTIONS]

zb ssh-key rm

Remove an SSH key from your account; new sessions with it are refused.

zb ssh-key rm [OPTIONS] <KEY>

Argument	Description
<KEY>	Key id, name or fingerprint (SHA256:…).

zb storage

Project storage: buckets, files (ss:///bucket/path), signed transfers and S3 credentials.

Subcommand	What it does
zb storage buckets	Create, list, change and delete buckets
zb storage cp	Copy files: local -> ss:///bucket/path (upload), ss:// -> local (download), ss:// -> ss:// (server side)
zb storage disable	Turn storage off (files stay; /storage/v1 answers 404)
zb storage enable	Turn storage on for the project (/storage/v1 on the project endpoint)
zb storage ls	List buckets, or the files of a bucket folder
zb storage mv	Move or rename an object (ss:///bucket/a ss:///bucket/b; across buckets too)
zb storage rm	Delete objects (with -r every object under a prefix)
zb storage s3-credentials	Print the S3 access key of a project secret key (aws, rclone, Cyberduck)
zb storage settings	Show the project’s storage settings, limits and URLs

zb storage buckets

Create, list, change and delete buckets.

Subcommand	What it does
zb storage buckets create	Create a bucket (private unless —public)
zb storage buckets delete	Delete an empty bucket
zb storage buckets empty	Delete every file of a bucket
zb storage buckets list	List the project’s buckets
zb storage buckets update	Change a bucket (flags given replace the stored values)

zb storage buckets create

Create a bucket (private unless —public).

zb storage buckets create [OPTIONS]

Argument	Description
--allowed-mime <ALLOWED_MIME>	Allowed MIME types, e.g. image/*,application/pdf (update: "" clears them).
--file-size-limit <FILE_SIZE_LIMIT>	Largest file, e.g. 5MB (update: 0 clears it).
--public	Files are readable without a key at the public URL.
--versioning	Keep prior versions of overwritten and deleted files (paid plans).

zb storage buckets delete

Delete an empty bucket.

zb storage buckets delete [OPTIONS]

zb storage buckets empty

Delete every file of a bucket.

zb storage buckets empty [OPTIONS]

zb storage buckets list

List the project’s buckets.

zb storage buckets list [OPTIONS]

zb storage buckets update

Change a bucket (flags given replace the stored values).

zb storage buckets update [OPTIONS]

Argument	Description
--allowed-mime <ALLOWED_MIME>	Allowed MIME types, e.g. image/*,application/pdf (update: "" clears them).
--file-size-limit <FILE_SIZE_LIMIT>	Largest file, e.g. 5MB (update: 0 clears it).
--private	Make the bucket private.
--public	Files are readable without a key at the public URL.
--versioning	Keep prior versions of overwritten and deleted files (paid plans).

zb storage cp

Copy files: local -> ss:///bucket/path (upload), ss:// -> local (download), ss:// -> ss:// (server side).

zb storage cp [OPTIONS]

Argument	Description
-r, --recursive	Copy a directory or a prefix.

zb storage disable

Turn storage off (files stay; /storage/v1 answers 404).

zb storage disable [OPTIONS]

zb storage enable

Turn storage on for the project (/storage/v1 on the project endpoint).

zb storage enable [OPTIONS]

Argument	Description
--no-s3	Keep the S3 protocol off.

zb storage ls

List buckets, or the files of a bucket folder.

zb storage ls [OPTIONS] [ss:///bucket[/prefix]

Argument	Description
<ss:///bucket[/prefix>
-r, --recursive	List every file under the prefix.

zb storage mv

Move or rename an object (ss:///bucket/a ss:///bucket/b; across buckets too).

zb storage mv [OPTIONS]

zb storage rm

Delete objects (with -r every object under a prefix).

zb storage rm [OPTIONS]

Argument	Description
-r, --recursive	Delete every object under the prefix.

zb storage s3-credentials

Print the S3 access key of a project secret key (aws, rclone, Cyberduck).

zb storage s3-credentials [OPTIONS]

Argument	Description
--secret-key <SECRET_KEY>	Project secret key (env ZB_PROJECT_SECRET_KEY).

zb storage settings

Show the project’s storage settings, limits and URLs.

zb storage settings [OPTIONS]

zb teams

Teams, their members and budgets.

Subcommand	What it does
zb teams add-member	Add a member to a team (or change their role)
zb teams budget	Show a team’s budget and month-to-date spend
zb teams create	Create a team
zb teams delete	Delete a team
zb teams get	Show one team
zb teams list	List teams
zb teams members	List a team’s members
zb teams remove-member	Remove a member from a team

zb teams add-member

Add a member to a team (or change their role).

zb teams add-member [OPTIONS] <TEAM> <USER>

Argument	Description
<TEAM>	Team id.
<USER>	User id.
--role <ROLE>	admin, operator or viewer. Default operator.

zb teams budget

Show a team’s budget and month-to-date spend.

zb teams budget [OPTIONS] <ID>

Argument	Description
<ID>	Resource id.

zb teams create

Create a team.

zb teams create [OPTIONS] --name <NAME>

Argument	Description
--budget-cents <BUDGET_CENTS>	Monthly budget in USD cents.
--cost-centre <COST_CENTRE>
--name <NAME>	Required.
--slug <SLUG>

zb teams delete

Delete a team.

zb teams delete [OPTIONS] <ID>

Argument	Description
<ID>	Resource id.

zb teams get

Show one team.

zb teams get [OPTIONS] <ID>

Argument	Description
<ID>	Resource id.

zb teams list

List teams.

zb teams list [OPTIONS]

zb teams members

List a team’s members.

zb teams members [OPTIONS] <ID>

Argument	Description
<ID>	Resource id.

zb teams remove-member

Remove a member from a team.

zb teams remove-member [OPTIONS] <TEAM> <USER>

Argument	Description
<TEAM>	Team id.
<USER>	User id.

zb usage

Usage and list-price cost for the current month (or —from/—to), grouped.

zb usage [OPTIONS]

Argument	Description
--by <BY>	Grouping. One of team, cost-centre, instance, metric. Default team.
--csv	Print CSV.
--from <FROM>	Start (RFC 3339); default: start of the current month.
--to <TO>	End (RFC 3339, exclusive); default: now.

zb ws

Cloud dev workspaces: create, start, stop, and connect over SSH (VS Code / Cursor Remote-SSH).

Subcommand	What it does
zb ws allowance	How many workspaces each member may own (owners and admins): list, set, reset to the plan default
zb ws code	Open a running workspace in VS Code, Cursor or Zed over SSH (writes its Host block to ~/.ssh/config first)
zb ws create	Create a workspace (attach it to a project with the global —project <id|slug>); prints its ssh command, or the approval request when a team policy needs one
zb ws delete	Delete a workspace and its home volume. Irreversible; asks first unless —yes
zb ws export	Export a running workspace’s home directory as .tar.gz into a bucket of its project (another project’s bucket with the global —project)
zb ws exports	List exports of a workspace’s home directory
zb ws get	Show one workspace: status, size, idle stop, estimate and its ssh command
zb ws instructions	A project’s shared agent instructions (AGENTS.md / CLAUDE.md synced into every repository of its workspaces; the global —project <id|slug>)
zb ws list	List your workspaces (—all: every workspace in the org you can see)
zb ws logs	Print the workspace container’s log (entrypoint, zb-wsd, dockerd); -f follows it until Ctrl-C
zb ws port-forward	Forward local ports to a running workspace through the bastion (3000, 8080:3000; repeat for more) until Ctrl-C
zb ws restore	Create a new workspace from a snapshot (size and disk default to the snapshot’s; the global —project attaches it)
zb ws revoke-sessions	Close every open SSH and web-terminal session of a workspace now (a lost laptop, a leaked key); asks first unless —yes
zb ws seats	Workspace hours per member this month (or —from/—to): live workspaces, allowance and usage (Team seat report)
zb ws sessions	List the open SSH, web-terminal and port-forward sessions of a workspace (—all: the last 7 days)
zb ws snapshot	Snapshots of a workspace’s home volume: take one now, list, delete (restore with zb ws restore)
zb ws ssh	Open an SSH session to a running workspace through the bastion (the system ssh, with the keys from zb ssh-key add)
zb ws ssh-config	Print the workspace’s Host block for ~/.ssh/config, or keep it there with —write (VS Code / Cursor Remote-SSH, Zed, scp, rsync)
zb ws start	Start a stopped workspace (the home volume is kept across stops)
zb ws stop	Stop a workspace: compute stops billing, the home volume is kept
zb ws update	Change a workspace: name, idle stop, disk (grow only), repositories, agents, or its project (the global —project <id|slug>, —detach-project)
zb ws usage	Compute, disk and snapshot usage and cost of one workspace this month (or —from/—to)

zb ws allowance

How many workspaces each member may own (owners and admins): list, set, reset to the plan default.

Subcommand	What it does
zb ws allowance list	List per-member workspace allowances and the plan default
zb ws allowance reset	Remove a member’s allowance override (back to the plan default)
zb ws allowance set	Set how many workspaces a member may own (0..100, or unlimited)

zb ws allowance list

List per-member workspace allowances and the plan default.

zb ws allowance list [OPTIONS]

zb ws allowance reset

Remove a member’s allowance override (back to the plan default).

zb ws allowance reset [OPTIONS] <USER_ID>

Argument	Description
<USER_ID>	Member’s user id (usr_…; zb members list).

zb ws allowance set

Set how many workspaces a member may own (0..100, or unlimited).

zb ws allowance set [OPTIONS] <USER_ID> <MAX>

Argument	Description
<USER_ID>	Member’s user id (usr_…; zb members list).
<MAX>	Workspaces the member may own: 0..100 or unlimited.

zb ws code

Open a running workspace in VS Code, Cursor or Zed over SSH (writes its Host block to ~/.ssh/config first).

zb ws code [OPTIONS] <WORKSPACE>

Argument	Description
<WORKSPACE>	Workspace name or id (ws_…).
--editor <EDITOR>	Editor to open. One of code, cursor, zed. Default code.
--path <PATH>	Folder to open (default: /home/dev, or /home/dev/dev/<repo> with exactly one repo).
--print	Print the command instead of running it (writes nothing).
--ssh-config <FILE>	SSH config file for the Host block (default: ~/.ssh/config).

zb ws create

Create a workspace (attach it to a project with the global —project <id|slug>); prints its ssh command, or the approval request when a team policy needs one.

zb ws create [OPTIONS] --size <SIZE> <NAME>

Argument	Description
<NAME>	Workspace name: lower-case letters, digits and -, unique in the org.
--agent <AGENT>	Agent to install at first start (claude-code, codex, opencode, gemini, cursor, devin, grok; repeat or comma separate).
--disk-gb <DISK_GB>	Home volume in GiB (default: the size’s included disk).
--idle-stop-minutes <IDLE_STOP_MINUTES>	Stop after this many idle minutes (default 120; 0 = never).
--owner <OWNER>	Member who owns it (user id; admins only, required with an API key; default: you).
--placement <PLACEMENT>	shared (default) or secure: the org’s dedicated nodes on a HIPAA cell (needs a signed BAA). One of shared, secure.
--region <REGION>	Region (default: the org’s default region).
--repo <OWNER/NAME>	GitHub repository to clone under ~/dev (owner/name; repeat or comma separate).
--restore <SNAPSHOT_ID>	Restore the home volume from this snapshot (wss_…; zb ws snapshot list).
--size <SIZE>	Workspace size (w1, w2, w3; zb api GET /v1/sizes lists them). Required.
--timeout <TIMEOUT>	Give up waiting after this many seconds (with —wait). Default 900.
--wait	Wait until the workspace is running (or failed).

zb ws delete

Delete a workspace and its home volume. Irreversible; asks first unless —yes.

zb ws delete [OPTIONS] <WORKSPACE>

Argument	Description
<WORKSPACE>	Workspace name or id (ws_…).

zb ws export

Export a running workspace’s home directory as .tar.gz into a bucket of its project (another project’s bucket with the global —project).

zb ws export [OPTIONS] --bucket <BUCKET> <WORKSPACE>

Argument	Description
<WORKSPACE>	Workspace name or id (ws_…).
--bucket <BUCKET>	Bucket of the workspace’s project. Required.
--key <KEY>	Object key (default: workspaces/<name>/<timestamp>.tar.gz).

zb ws exports

List exports of a workspace’s home directory.

zb ws exports [OPTIONS] <WORKSPACE>

Argument	Description
<WORKSPACE>	Workspace name or id (ws_…).

zb ws get

Show one workspace: status, size, idle stop, estimate and its ssh command.

zb ws get [OPTIONS] <WORKSPACE>

Argument	Description
<WORKSPACE>	Workspace name or id (ws_…).

zb ws instructions

A project’s shared agent instructions (AGENTS.md / CLAUDE.md synced into every repository of its workspaces; the global —project <id|slug>).

Subcommand	What it does
zb ws instructions get	Print the project’s agent instructions (Markdown)
zb ws instructions set	Replace the project’s agent instructions from a Markdown file (or - for stdin; an empty file removes them)

zb ws instructions get

Print the project’s agent instructions (Markdown).

zb ws instructions get [OPTIONS]

zb ws instructions set

Replace the project’s agent instructions from a Markdown file (or - for stdin; an empty file removes them).

zb ws instructions set [OPTIONS] --file <PATH>

Argument	Description
--file <PATH>	Markdown file to upload, or - to read stdin (at most 64 KiB). Required.

zb ws list

List your workspaces (—all: every workspace in the org you can see).

zb ws list [OPTIONS]

Argument	Description
--all	List every workspace in the org, not only yours.

zb ws logs

Print the workspace container’s log (entrypoint, zb-wsd, dockerd); -f follows it until Ctrl-C.

zb ws logs [OPTIONS] <WORKSPACE>

Argument	Description
<WORKSPACE>	Workspace name or id (ws_…).
-f, --follow	Keep streaming new lines until Ctrl-C.
--previous	The previous container’s log (after a restart or crash).
--tail <N>	Lines from the end of the log to start with. Default 200.

zb ws port-forward

Forward local ports to a running workspace through the bastion (3000, 8080:3000; repeat for more) until Ctrl-C.

zb ws port-forward [OPTIONS] <WORKSPACE> <PORT>

Argument	Description
<WORKSPACE>	Workspace name or id (ws_…).
<PORT>	PORT (same port both ends) or LOCAL_PORT:REMOTE_PORT; repeat for more.
--bind <ADDR>	Local address to listen on. Default 127.0.0.1.
--print	Print the ssh command instead of running it.

zb ws restore

Create a new workspace from a snapshot (size and disk default to the snapshot’s; the global —project attaches it).

zb ws restore [OPTIONS] <SNAPSHOT_ID> <NEW_NAME>

Argument	Description
<SNAPSHOT_ID>	Snapshot id (wss_…; zb ws snapshot list).
<NEW_NAME>	Name of the new workspace.
--disk-gb <DISK_GB>	Home volume in GiB, at least the snapshot’s (default: the snapshot’s).
--region <REGION>	Region (default: the org’s default region).
--size <SIZE>	Workspace size (default: the snapshot’s).
--timeout <TIMEOUT>	Give up waiting after this many seconds (with —wait). Default 900.
--wait	Wait until the workspace is running (or failed).

zb ws revoke-sessions

Close every open SSH and web-terminal session of a workspace now (a lost laptop, a leaked key); asks first unless —yes.

zb ws revoke-sessions [OPTIONS] <WORKSPACE>

Argument	Description
<WORKSPACE>	Workspace name or id (ws_…).

zb ws seats

Workspace hours per member this month (or —from/—to): live workspaces, allowance and usage (Team seat report).

zb ws seats [OPTIONS]

Argument	Description
--from <FROM>	Window start (YYYY-MM-DD or RFC 3339; default: the start of the month, UTC).
--to <TO>	Window end (YYYY-MM-DD or RFC 3339; default: now).

zb ws sessions

List the open SSH, web-terminal and port-forward sessions of a workspace (—all: the last 7 days).

zb ws sessions [OPTIONS] <WORKSPACE>

Argument	Description
<WORKSPACE>	Workspace name or id (ws_…).
--all	Include ended and revoked sessions of the last 7 days.

zb ws snapshot

Snapshots of a workspace’s home volume: take one now, list, delete (restore with zb ws restore).

Subcommand	What it does
zb ws snapshot create	Snapshot a workspace’s home volume now (paid plans)
zb ws snapshot delete	Delete a snapshot (also a retained one). Irreversible; asks first unless —yes
zb ws snapshot list	List snapshots of one workspace, or of every workspace in the org

zb ws snapshot create

Snapshot a workspace’s home volume now (paid plans).

zb ws snapshot create [OPTIONS] <WORKSPACE>

Argument	Description
<WORKSPACE>	Workspace name or id (ws_…).
--timeout <TIMEOUT>	Give up waiting after this many seconds (with —wait). Default 1800.
--wait	Wait until the snapshot is ready (or failed).

zb ws snapshot delete

Delete a snapshot (also a retained one). Irreversible; asks first unless —yes.

zb ws snapshot delete [OPTIONS] <SNAPSHOT_ID>

Argument	Description
<SNAPSHOT_ID>	Snapshot id (wss_…).

zb ws snapshot list

List snapshots of one workspace, or of every workspace in the org.

zb ws snapshot list [OPTIONS] [WORKSPACE]

Argument	Description
<WORKSPACE>	Workspace name or id (ws_…); omit for the whole org.

zb ws ssh

Open an SSH session to a running workspace through the bastion (the system ssh, with the keys from zb ssh-key add).

zb ws ssh [OPTIONS] <WORKSPACE> [-- <ARGS>...]

Argument	Description
<WORKSPACE>	Workspace name or id (ws_…).
--print	Print the ssh command instead of running it.
-- <ARGS>...	Extra ssh arguments or a remote command, after --.

zb ws ssh-config

Print the workspace’s Host block for ~/.ssh/config, or keep it there with —write (VS Code / Cursor Remote-SSH, Zed, scp, rsync).

zb ws ssh-config [OPTIONS] <WORKSPACE>

Argument	Description
<WORKSPACE>	Workspace name or id (ws_…).
--alias <NAME>	Host alias to use instead of zb-<name>.
--file <PATH>	SSH config file to write (default: ~/.ssh/config, on Windows %USERPROFILE%.ssh\config).
--remove	Remove the workspace’s managed block from the SSH config.
--write	Add or update a managed block for the workspace in ~/.ssh/config (idempotent).

zb ws start

Start a stopped workspace (the home volume is kept across stops).

zb ws start [OPTIONS] <WORKSPACE>

Argument	Description
<WORKSPACE>	Workspace name or id (ws_…).
--timeout <TIMEOUT>	Give up waiting after this many seconds (with —wait). Default 600.
--wait	Wait until the workspace is running (or failed).

zb ws stop

Stop a workspace: compute stops billing, the home volume is kept.

zb ws stop [OPTIONS] <WORKSPACE>

Argument	Description
<WORKSPACE>	Workspace name or id (ws_…).
--timeout <TIMEOUT>	Give up waiting after this many seconds (with —wait). Default 600.
--wait	Wait until the workspace is stopped (or failed).

zb ws update

Change a workspace: name, idle stop, disk (grow only), repositories, agents, or its project (the global —project <id|slug>, —detach-project).

zb ws update [OPTIONS] <WORKSPACE>

Argument	Description
<WORKSPACE>	Workspace name or id (ws_…).
--agent <AGENT>	Replace the agents installed at start (repeat or comma separate; —agent "" clears).
--detach-project	Detach the workspace from its project.
--disk-gb <DISK_GB>	Grow the home volume to this many GiB (never shrinks).
--idle-stop-minutes <IDLE_STOP_MINUTES>	Stop after this many idle minutes (0 = never).
--name <NAME>	New name (the ssh-config alias zb-<name> changes with it).
--repo <OWNER/NAME>	Replace the GitHub repositories (owner/name; repeat or comma separate; —repo "" clears).

zb ws usage

Compute, disk and snapshot usage and cost of one workspace this month (or —from/—to).

zb ws usage [OPTIONS] <WORKSPACE>

Argument	Description
<WORKSPACE>	Workspace name or id (ws_…).
--from <FROM>	Window start (YYYY-MM-DD or RFC 3339; default: the start of the month, UTC).
--to <TO>	Window end (YYYY-MM-DD or RFC 3339; default: now).