# CLI: Global flags & exit codes

What every command shares: flags, environment, config and exit codes.

## Global flags

These flags work on every command.

| Flag | Default | Description |
|------|---------|-------------|
| `--api-url` | `https://bumpkit.dev/v1`, or `BUMPKIT_API_URL` | API base URL |
| `--workspace UUID` | | Assert the authenticated workspace before an action |
| `--json` | `false` | Print machine-readable JSON |
| `--no-color` | `false` | Disable color (same as setting `NO_COLOR`) |
| `-h`, `--help` | | Help for the command |
| `-v`, `--version` | | Print the version (root command only) |

`hooks install` and `provenance enable`, `disable` and `record` parse their own flags. `--api-url`, `--workspace` and `--no-color` still work on them, but `--json` is an unknown flag and exits with code 2. `check` and `gate` define their own `--json`. Long flags take two dashes: `-base` is not `--base`.

### Workspace assertion

`--workspace UUID` checks the current API key against `GET /v1/me` before running an action. Use the UUID from `bumpkit whoami --json`, `bumpkit workspace list` or the dashboard. A mismatch or failed verification stops the action. On other commands the flag does not switch workspaces.

With `login`, `--workspace` preselects that workspace on the browser approval page, and the CLI keeps the new key only if it belongs to that workspace; otherwise it revokes the key and saves nothing. Invalid UUIDs return `INVALID_WORKSPACE_ID`; other guard failures return `WORKSPACE_MISMATCH` or `WORKSPACE_VERIFICATION_FAILED`, including structured errors with `--json`.

For MCP, `bumpkit --workspace UUID mcp` verifies the key before starting the stdio server. `bumpkit --workspace UUID mcp config` prints client configuration containing the workspace assertion without accessing the API, writing files or including credentials. Local help, version and installation commands do not require a workspace request.

## Environment variables and config

### Sign-in and config file

`bumpkit login` saves the CLI's API key, workspace name and email to a JSON config file:

| Location | Used when |
|----------|-----------|
| `$BUMPKIT_CONFIG_DIR/config.json` | `BUMPKIT_CONFIG_DIR` is set |
| `$XDG_CONFIG_HOME/bumpkit/config.json` | `XDG_CONFIG_HOME` is set |
| `~/.config/bumpkit/config.json` | Otherwise |

The file is written with mode `0600` in a `0700` directory. If `BUMPKIT_API_URL` is set when you sign in, `login` also saves that URL to the file.

### Variables

| Variable | Description |
|----------|-------------|
| `BUMPKIT_API_KEY` | API key. It takes precedence over the key in the config file. Set it in CI instead of running `bumpkit login`. |
| `BUMPKIT_API_URL` | API base URL. Lookup order: `--api-url`, then `BUMPKIT_API_URL`, then the URL saved in the config file, then `https://bumpkit.dev/v1`. |
| `BUMPKIT_CONFIG_DIR` | Directory for `config.json`. |
| `XDG_CONFIG_HOME` | Base directory for `bumpkit/config.json` when `BUMPKIT_CONFIG_DIR` is not set. |
| `NO_COLOR` | Any value turns color off. Color is also off when `TERM=dumb` or when standard output is not a terminal. |
| `GITHUB_TOKEN` | In GitHub Actions, `gate` uses it to read the pull request's approving reviews and to post `--comment`. |
| `GITHUB_EVENT_PATH`, `GITHUB_HEAD_REF`, `GITHUB_ACTIONS` | Read by `gate` in GitHub Actions to find the pull request, its base commit and its branch. |
| `GITHUB_STEP_SUMMARY` | When set, `gate` appends its decision to the job summary as Markdown. |

### CI variables

| Variable | Used by | Description |
|----------|---------|-------------|
| `GITLAB_CI`, `BITBUCKET_BUILD_NUMBER`, `TF_BUILD`, `BUILDKITE`, `CIRCLECI`, `BUILD_TAG` | `gate` | Detect GitLab CI, Bitbucket Pipelines, Azure Pipelines, Buildkite, CircleCI and Jenkins (a `BUILD_TAG` starting with `jenkins-`). `gate` then reads the merge or pull request, its base and its repository from that CI's own variables. |
| `GITHUB_SERVER_URL` | `gate`, `verify` | In GitHub Actions on GitHub Enterprise Server, names the server in the repository name, so it never reads as a github.com repository |
| `BUMPKIT_GITHUB_TOKEN`, `GITHUB_TOKEN`, `GITHUB_API_URL` | `gate` | GitHub token for approvals and comments on Buildkite, CircleCI and Jenkins, and the API URL when your GitHub Enterprise server doesn't use `/api/v3`. |
| `BUMPKIT_GITLAB_TOKEN`, `GITLAB_TOKEN` | `gate` | GitLab token for approvals and comments. Falls back to `CI_JOB_TOKEN`. |
| `BUMPKIT_BITBUCKET_TOKEN`, `BITBUCKET_ACCESS_TOKEN` | `gate` | Bitbucket Cloud token. |
| `SYSTEM_ACCESSTOKEN` | `gate` | Azure DevOps token. |

### Beta variables

> **Beta, early access.** Each variable works once the commands that read it are on for your workspace.

| Variable | Used by | Description |
|----------|---------|-------------|
| `BUMPKIT_IDEMPOTENCY_KEY` | `check`, `gate` | Idempotency key sent with the check and gate requests, so a retried request never runs twice. A random key is used when this is unset. |
| `BUMPKIT_CACHE_DIR` | `pause`, `provenance`, `check`, `gate`, `guard`, `blast-radius`, `predict`, `quality`, `tests`, `when` | Where the CLI keeps its local cache (default: your user cache directory plus `bumpkit`). |
| `BUMPKIT_AGENT_ID` | `claim`, `claims`, `intent`, `renew`, `unclaim`, `contracts sync`, `agent-report`, `testdb lease`, `lessons propose`, `agents spend`, `gate` | The agent's id: who holds a lease, makes a claim, leases a test database, proposes a lesson or spends (default: `cli` for claims). `gate` sends it so `agents:` budgets apply. `BUMPKIT_AGENT` is accepted as an alias. |
| `BUMPKIT_SESSION` | `claim`, `intent`, `renew`, `unclaim` | Which run of the agent (default: this host and shell). |
| `JIRA_BASE_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN` | `criteria` | Read acceptance criteria from linked Jira issues. |
| `LINEAR_API_KEY` | `criteria` | Read acceptance criteria from linked Linear issues. |
| `TEST_DB_ADMIN_URL` | `testdb` | `postgres://` URL of the Postgres server that holds your test databases. The CLI creates and drops leased databases there. |
| `TEST_DB_ALLOWED_HOSTS` | `testdb` | Comma-separated hosts (or `host:port`) the CLI may create databases on. It refuses any other server, and refuses when this is empty. |
| `TEST_DB_TEMPLATE` | `testdb` | Database to copy each lease from (optional). |
| `TEST_DB_MAX_LEASES` | `testdb lease` | Active leases allowed on the test server (default `20`). |

## Exit codes

| Code | Meaning |
|------|---------|
| `0` | Success, or the release passed |
| `1` | The command ran and its result is negative (see below), the command failed (not signed in, or an API or git error), or the command doesn't exist. An unknown subcommand names the closest real one: `Did you mean this?` |
| `2` | Usage error (unknown flag, wrong number of arguments). `check`, `gate` and `deploy` also exit `2` when they couldn't run. |

By command:

| Command | `0` | `1` | `2` |
|---------|-----|-----|-----|
| `check` | Verdict is `ship` or `review` | Verdict is `block` | Bad flag, not signed in, no tag to start from, git or API error |
| `gate` | Outcome is `pass` | Outcome is `fail` or `needs_approval` | Bad flag, invalid policy, not signed in, git or API error. With `on_error: pass` in the policy, errors exit `0` instead (an invalid policy still exits `2`). |
| `guard` | Pass; run directly, a change that only needs approval; with `--hook`, the reply goes to the agent as JSON; also when Bumpkit can't be reached or the feature is off | Run directly and the change has proven problems | Bad flag or `--hook` value; with `--hook windsurf`, a change that doesn't pass (Windsurf blocks the push on exit `2`) |
| `recall` | Always, unless a flag is wrong | | Bad flag |
| `deploy` | Recorded | API error | Bad flag, bad time, not signed in, no commit or repository |
| `hooks install` | Installed | An install step failed | Not in a git repository, no `install`, or a bad flag |
| `hooks pr` | Opened, already open, or already on the default branch | Not signed in, or an API error | No repository, or a bad flag |
| `pause` | Allowed; with `--hook`, always (the reply goes to the agent) | Run directly and the command is asked about or denied | No command, bad flag or `--hook` value |
| `release health` | Healthy, degraded or unknown | The release regressed, not signed in, or an API error | Wrong number of arguments |
| `install` | Installed and the installed copy ran | The archive's binaries aren't next to it, the directory can't be written, or the installed `bumpkit` didn't run | `--system` and `--user` together |
| `update` | Updated, or already the latest version | Download, checksum or write failed | |
| `uninstall` | Removed | `sudo` was declined or failed | |

Beta commands with their own codes: `verify` exits `1` when the head fails. `test triage` exits `1` when any failure is likely real. `contracts sync` exits `1` when this branch has incoming alerts. `agent-report` exits `1` when any claim is contradicted. `intent` exits `1` when it predicts a conflict.

## Other commands

| Command | Description |
|---------|-------------|
| `bumpkit version` | Print the CLI version |
| `bumpkit completion SHELL` | Generate the autocompletion script for `bash`, `zsh`, `fish` or `powershell` |
| `bumpkit help [command]` | Help about any command |