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