# CLI: Admin

Run your workspace: people, keys, billing, audit and evidence.

## bumpkit team

Manage workspace members and invitations.

| Subcommand | Usage | Description |
|------------|-------|-------------|
| `list` (alias `ls`) | `bumpkit team list` | List members and pending invitations |
| `invite` | `bumpkit team invite EMAIL` | Email someone an invitation, including an existing Bumpkit account; teammates are unlimited |
| `cancel` | `bumpkit team cancel INVITATION_ID` | Cancel a pending invitation |
| `remove` (alias `rm`) | `bumpkit team remove MEMBER_ID` | Remove a member and revoke every API key they created, in the audit log as `key.revoke`. They stay out of first sign-in and IdP-managed access until you invite them again or provision them through SCIM. `-y`, `--yes` skips the confirmation. |

### Beta: roles

> **Beta, early access.** Flag: `roles`.

| Subcommand | Usage | Description |
|------------|-------|-------------|
| `role` | `bumpkit team role MEMBER_ID ROLE` | Change a member's role: `owner`, `org_admin`, `policy_admin`, `approver`, `member`, `viewer` or `auditor` |

`team invite` also takes `--role`, the role to join with (default `member`). The CLI can invite as `member` or `viewer` and can lower a role. A person signed in to the dashboard grants anything higher, and sends invitations when Bumpkit can't email them. See [SSO, SCIM & Roles](/docs/sso).

## bumpkit keys

Manage API keys.

| Subcommand | Usage | Description |
|------------|-------|-------------|
| `create` | `bumpkit keys create LABEL [--expires YYYY-MM-DD]` | Create an API key; it is shown once |
| `list` (alias `ls`) | `bumpkit keys list` | List API keys |
| `delete` (aliases `revoke`, `rm`) | `bumpkit keys delete KEY_ID` | Delete an API key you created, or any key as an owner or admin; anything using it stops working. `-y`, `--yes` skips the confirmation. |

```bash
bumpkit keys create ci-pipeline --expires 2027-12-31
```

## bumpkit billing

Credits used by release checks, for owners and admins. 1 credit = 1 release check = $0.10, re-runs of the same commit are free, and every workspace gets 60 free credits each calendar month (UTC).

| Subcommand | Usage | Description |
|------------|-------|-------------|
| `status` | `bumpkit billing status` | This period's credits used, free credits left, paid credits and free re-runs |
| `usage` | `bumpkit billing usage [--period YYYY-MM] [--by repo\|source\|outcome\|actor] [--json] [--csv]` | One period's credits, broken down by repository, source, outcome or who ran each check |
| `portal` | `bumpkit billing portal [--no-browser]` | Manage an existing customer’s Stripe billing account (owners) |

| Flag | Default | Description |
|------|---------|-------------|
| `--period` | current month | Billing period as `YYYY-MM`, UTC (`usage`) |
| `--by` | `repo` | `repo`, `source`, `outcome` or `actor` (`usage`). `outcome` lists **Checked, no gate decision** for a release check that ran without a release gate decision, for example from the CLI or API |
| `--csv` | `false` | Print the period's billable checks as CSV; the export is written to the audit log (`usage`) |
| `--no-browser` | `false` | Print the link instead of opening it (`portal`) |

```bash
# September's credits by who ran each check
bumpkit billing usage --period 2026-09 --by actor
# Every billable check in September as CSV
bumpkit billing usage --period 2026-09 --csv > bumpkit-usage-2026-09.csv
```

`--json` prints the same report as [GET /v1/billing/usage](/docs/api-admin#get-v1-billing-usage), and the dashboard's Usage and billing page and the `get_billing_usage` MCP tool show the same numbers. Credit purchases aren't enabled yet; contact the Bumpkit team at hello@bumpkit.dev.

## bumpkit settings

Workspace name and public changelog. See [Changelog Pages](/docs/changelog-pages).

| Subcommand | Usage | Description |
|------------|-------|-------------|
| `view` | `bumpkit settings view` | Show workspace settings |
| `set` | `bumpkit settings set [flags]` | Change workspace settings (owners and admins) |

`settings set` flags:

| Flag | Default | Description |
|------|---------|-------------|
| `--changelog` | | `public` or `private` |
| `--name` | | Workspace name |
| `--repository` | | Repository the public changelog shows |
| `--slug` | | Public changelog address: `bumpkit.dev/c/SLUG` |
| `--title` | | Public changelog title |
| `--memory-approval` | | Beta (flag `memory_approval`): `on` makes every memory saved through the API wait for a person's approval; `off` turns that off |
| `--draft-after-merge` | | Beta (flag `grouped_releases`): `on` (the default) has Bumpkit draft a grouped release after every merge to the default branch; `off` means a release is drafted only when someone prepares one |
| `--publish-audience` | | Beta (flag `grouped_releases`), repeatable: `target=audience`, whose notes a publish target gets. Defaults: `changelog=customer`, `github_release=customer`, `slack=engineering`, `discord=engineering`, `notion=engineering`, `confluence=engineering`. `target=` resets one |
| `--vulnerability-alerts` | | Beta (flag `code_index`): which new advisories alert: `all` (the default), `reachable`, `critical_high` or `off` |
| `--auto-fix-prs` | | Beta (flag `code_index`): open fix pull requests automatically for `off` (the default), `critical` or `critical_high` |

```bash
bumpkit settings set --changelog public --slug acme --repository https://github.com/acme/api
bumpkit settings set --publish-audience slack=support
bumpkit settings set --vulnerability-alerts reachable --auto-fix-prs critical_high
```

## bumpkit audit

Show who changed what in the workspace, and from where (owners, admins and auditors).

Events show the action, time, actor, source and target. Large feature grants show a feature count; use `--details` for every granted feature, or `--json` for the complete records.

| Flag | Default | Description |
|------|---------|-------------|
| `--limit` | `100` | How many events (max 500) |
| `--details` | `false` | Show full targets, including every granted feature |

### Beta: audit export and streaming

> **Beta, early access.** Flag: `siem_streaming`.

Export the full audit trail for a period, or stream new audit events to your SIEM. See [Compliance Evidence](/docs/compliance#manage-audit-access-and-streaming-from-the-cli).

| Subcommand | Usage | Description |
|------------|-------|-------------|
| `export` | `bumpkit audit export [--days N \| --from YYYY-MM-DD --to YYYY-MM-DD] [--format jsonl\|csv] [-o FILE]` | Download every audit event in the period |
| `streaming list` | `bumpkit audit streaming list` | List destinations with their pending and dead-letter counts, never their credentials |
| `streaming create` | `bumpkit audit streaming create --kind KIND --name NAME --url URL --secret-file FILE --yes` | Add a destination and start streaming new events to it |
| `streaming test` | `bumpkit audit streaming test DESTINATION_ID --yes` | Send a sample event to a destination |
| `streaming disable`, `enable` | `bumpkit audit streaming disable DESTINATION_ID --yes` | Pause or resume a destination; a paused one stays configured |
| `streaming remove` | `bumpkit audit streaming remove DESTINATION_ID --yes` | Delete a destination and its configuration |
| `streaming dead-letters list` | `bumpkit audit streaming dead-letters list` | List batches that failed to deliver |
| `streaming dead-letters redeliver` | `bumpkit audit streaming dead-letters redeliver BATCH_ID --yes` | Send a failed batch to its destination again |

`audit export` needs a key created by an owner, admin or auditor. You get the whole period, not just the latest 500 events that `bumpkit audit` shows. Pass `--days` (1 to 730) or both `--from` and `--to`, not both. With neither, you get the last 90 days. A period with more than 50,000 events fails with `400 EXPORT_TOO_LARGE`, so split it into shorter periods. The export is written to the audit log as `audit.export`.

| Flag | Default | Description |
|------|---------|-------------|
| `--days` | | The last N days, 1 to 730 |
| `--from`, `--to` | | Start and end dates, `YYYY-MM-DD`; `--to` can't be before `--from` |
| `--format` | `jsonl` | `jsonl` (JSON Lines) or `csv` |
| `-o`, `--output` | Standard output | File to write, with owner-only permissions |

`audit streaming` is for owners and admins. `--kind` is `webhook`, `splunk`, `datadog` or `s3`. Read the credential from a file, or pass `--secret-file -` to read it from standard input. It can be up to 512 bytes. Never put it in the URL. `--config-file` takes an optional JSON object of provider settings, up to 128 KiB, such as Splunk's `index` or S3's `bucket` and `region`. Only one of the two inputs can read standard input. Every command that sends data or changes a destination asks you to confirm; `-y`, `--yes` confirms up front.

```bash
bumpkit audit export --days 30 --format csv -o audit.csv
bumpkit audit streaming list
```

## bumpkit auditors

> **Beta, early access.** Flag: `auditor_access`.

Give an outside auditor read-only access to your evidence and audit events, through a link that expires. Owners and admins manage links. See [Compliance Evidence](/docs/compliance#manage-audit-access-and-streaming-from-the-cli).

| Subcommand | Usage | Description |
|------------|-------|-------------|
| `list` | `bumpkit auditors list` | Show each link's ID, auditor, state (active, expired or revoked) and expiry, never its token |
| `create` | `bumpkit auditors create LABEL [--days N] --yes` | Create a link and print its URL once |
| `revoke` | `bumpkit auditors revoke LINK_ID --yes` | Turn a link off right away |

`LABEL` names the auditor or audit firm, up to 64 characters. `--days` sets the expiry, 1 to 90 (default `30`). Save the URL when you create the link. Bumpkit shows it only once, and anyone who has it can use it until it expires or you revoke it. `-y`, `--yes` confirms `create` and `revoke` without a prompt.

```bash
bumpkit auditors create "Audit firm" --days 30 --yes
bumpkit auditors list
bumpkit auditors revoke LINK_ID --yes
```

## bumpkit evidence

> **Beta, early access.** Flag: `compliance_export`.

Change-management evidence for audits. See [Compliance Evidence](/docs/compliance).

| Subcommand | Usage | Description |
|------------|-------|-------------|
| `export` | `bumpkit evidence export [flags]` | Download tamper-evident evidence for a period |

Exporting needs a key created by an owner, admin or auditor. Other roles and keys not tied to a person, such as CI keys, get `403 ROLE_REQUIRED`, and the refusal is in the audit log. In CI, export with an auditor's key.

`evidence export` flags:

| Flag | Default | Description |
|------|---------|-------------|
| `--days` | | The last N days instead of `--from`/`--to` |
| `--format` | `json` | `json` or `csv` |
| `--from` | | Start date, `YYYY-MM-DD` |
| `-o`, `--output` | Standard output | File to write |
| `--to` | | End date, `YYYY-MM-DD` |

```bash
bumpkit evidence export --from 2026-07-01 --to 2026-09-30 --format csv -o q3.csv
```

### Beta: signed bundles

> **Beta, early access.** Flag: `signed_evidence`.

`evidence export --signed` downloads a signed, tamper-evident bundle (zip) you can verify offline.

| Subcommand | Usage | Description |
|------------|-------|-------------|
| `verify` | `bumpkit evidence verify BUNDLE [flags]` | Check offline that a signed evidence bundle hasn't been changed |

| Flag | Default | Description |
|------|---------|-------------|
| `--public-key` | | The signer's base64 Ed25519 public key |
| `--public-key-file` | | A file holding the public key, or the JSON published at the key URL |
| `--expected-workspace` | | Require this workspace ID and a pinned public key |

```bash
bumpkit evidence export --signed --days 365 -o evidence.zip
bumpkit evidence verify evidence.zip --public-key-file bumpkit-key.json
```

### Beta: governance evidence

> **Beta, early access.** Flag: `governance_evidence`.

`evidence governance` exports proof that each agent-written change got the human review your policy asks for: who wrote it, the approvals, the gate decision and any override review, with the gaps flagged. See [Compliance Evidence](/docs/compliance).

| Subcommand | Usage | Description |
|------------|-------|-------------|
| `governance` | `bumpkit evidence governance [--days N \| --from YYYY-MM-DD --to YYYY-MM-DD] [--format json\|csv] [-o FILE]` | Download governance evidence for a period |

It needs a key created by an owner, admin or auditor. Pass `--days` (1 to 730) or both `--from` and `--to`. With neither, you get the last 90 days. `--format` is `json` (the default) or `csv`. Without `-o`, the export goes to standard output; with it, the file gets owner-only permissions. Each export is written to the audit log.

```bash
bumpkit evidence governance --days 90 -o governance.json
```

## bumpkit findings

> **Beta, early access.** Flag: `finding_feedback`.

Teach Bumpkit which findings are real.

| Subcommand | Usage | Description |
|------------|-------|-------------|
| `feedback` | `bumpkit findings feedback FINDING_ID (--real \| --false-positive) [flags]` | Mark a finding real or a false positive |
| `precision` | `bumpkit findings precision [flags]` | Show each checker's measured precision |

`findings feedback` takes `--real` (the finding is a real problem), `--false-positive` (the finding is wrong) and `--reason` (why, in a sentence). `findings precision` takes `--days` (default `90`).

## bumpkit incidents

> **Beta, early access.** Flag: `forensics`.

Trace production errors to the release behind them. See [Release Health & Forensics](/docs/release-health).

| Subcommand | Usage | Description |
|------------|-------|-------------|
| `report` | `bumpkit incidents report --error TEXT [flags]` | Report a production error and rank the releases behind it, with a likelihood |
| `list` | `bumpkit incidents list [flags]` | Recent production errors and the release that fixed each one |
| `resolve` | `bumpkit incidents resolve INCIDENT_ID --version VERSION [flags]` | Record the release that fixed an incident |

`incidents report` flags:

| Flag | Default | Description |
|------|---------|-------------|
| `--error` | | The error message and stack trace |
| `--file` | | A file in the stack trace (repeatable) |
| `--lookback-days` | | How far back to look for releases |
| `--repository` | The origin remote | Repository URL |
| `--since` | | When the error started (RFC 3339) |

`incidents list` takes `--limit` (default `50`, max 500). `incidents resolve` takes `--version` (the release that fixed it, like `v2.3.1`) and `--sha` (the commit of the fix, optional).

```bash
bumpkit incidents resolve 3f2c9a1e-8b7d-4c2a-9e1f-6a5b4c3d2e1f --version v2.3.1 --sha 4b7a1d2
```

## bumpkit report

> **Beta, early access.** Flags: `leadership_dashboards`, `confidence_score`.

Leadership report for a period: releases shipped, blocked, needing approval and overridden; the agent and human share of code and of incidents; and confidence and risk per repository and CODEOWNERS team. See [Confidence Score & Leadership](/docs/confidence-score).

```text
bumpkit report [flags]
bumpkit report [command]
```

| Flag | Default | Description |
|------|---------|-------------|
| `--csv` | `false` | Print the weekly breakdown as CSV |
| `--days` | `90` | How many days back |
| `--from` | | First day, `YYYY-MM-DD` (with `--to`) |
| `--repo` | | Only this repository, e.g. `acme/api` |
| `--team` | | Only this CODEOWNERS team, e.g. `@acme/payments` |
| `--to` | | Last day, `YYYY-MM-DD` (with `--from`) |

| Subcommand | Usage | Description |
|------------|-------|-------------|
| `readiness` | `bumpkit report readiness [flags]` | Release readiness report: verdict first, then releases, blockers, authorship, risk and approval waits |
| `score` | `bumpkit report score CHECK_ID` | A gated release's confidence score and what moved it |
| `confidence` | `bumpkit report confidence` | How accurate the confidence score has been on your releases |
| `risk` | `bumpkit report risk [flags]` | Where releases broke before: risk per file, area or repository |
| `outcome` | `bumpkit report outcome CHECK_ID --kind revert\|incident\|hotfix\|regression [flags]` | Record what happened to a release after it shipped, so future scores reflect it. Viewers and auditors can't |
| `retrain` | `bumpkit report retrain` | Update this workspace's confidence and risk scores from its latest outcomes now (owners and admins) |
| `pooling` | `bumpkit report pooling on\|off` | Opt this workspace in or out of sharing anonymous outcomes across workspaces (owners and admins) |

`report readiness` flags: `--repo` (one repository; default every repository), `--days` (default `30`), `--from` and `--to` (`YYYY-MM-DD`, together), `--format` (`pdf`, `csv` or `json`; default `pdf`) and `-o`/`--output` (file to write; default `bumpkit-readiness.pdf` for PDF, standard output otherwise). See [Release readiness report](/docs/confidence-score#release-readiness-report). `report risk` flags: `--limit` (default `50`, max 500), `--repo` (only this repository) and `--scope` (`file`, `area` or `repository`; default `file`). `report outcome` flags: `--kind` (`revert`, `incident`, `hotfix` or `regression`) and `--note` (what happened, kept in the audit record).

```bash
bumpkit report --from 2026-07-01 --to 2026-09-30 --csv > q3.csv
```

## bumpkit scorecards

> **Beta, early access.** Flag: `agent_scorecards`.

How each coding agent's changes fared.

| Flag | Default | Description |
|------|---------|-------------|
| `--days` | `30` | Window in days |

## bumpkit proven

> **Beta, early access.** Flag: `proven_changes`.

Which kinds of change, in which part of each repository, ship without problems, with the backtest. `bumpkit proven show AREA KIND` lists one class's changes and problems. See [Proven changes](/docs/confidence-score#proven-changes).

| Flag | Default | Description |
|------|---------|-------------|
| `--repository` | every repository; `show` uses this checkout's origin | Repository as `owner/name` |

## bumpkit compatibility

> **Beta, early access.** Flag: `compatibility_matrix`.

Each supported version pair declared under [`compatibility`](/docs/bumpkit-yml#compatibility) in `bumpkit.yml`, with its verdict from recorded evidence: compatible, breaking or not checked. See [Compatibility matrix](/docs/contract-checks#compatibility-matrix).

```text
bumpkit compatibility [--repository OWNER/NAME]
bumpkit compatibility show KEY
bumpkit compatibility export [--format csv|json] [--repository OWNER/NAME]
bumpkit compatibility sync [--repository OWNER/NAME] [--policy FILE]
```

| Command | What it does |
|---------|--------------|
| `compatibility` | List each pair with its key, verdict and why |
| `show KEY` | Show one pair version by version, with each break's file and version |
| `export` | Print the matrix as CSV or JSON for a procurement review |
| `sync` | Read the `compatibility` section into the matrix now. Needs an owner or admin key |

| Flag | Default | Description |
|------|---------|-------------|
| `--repository` | every repository; `sync` uses this checkout's origin | Only pairs this repository declares or provides, as `owner/name` |
| `--format` | `csv` | `export` only: `csv` or `json` |
| `--policy` | `bumpkit.yml` as committed on the default branch | `sync` only: the file to send. With the GitHub App on the repository, Bumpkit reads the file from the default branch itself and ignores this |

## Workspace domains and SCIM tokens

These commands use the signed-in workspace and the same owner or admin permissions as Settings → Single sign-on and SCIM, including the changes only an owner can make. They require a person-bound API key and the corresponding workspace feature access.

```sh
bumpkit domains list
bumpkit domains add example.com
bumpkit domains verify DOMAIN_ID
bumpkit domains remove DOMAIN_ID --yes
bumpkit scim tokens list
bumpkit scim tokens create Okta
bumpkit scim tokens revoke TOKEN_ID --yes
```

After adding a domain, `domains list` shows the exact DNS TXT name and value. Publish that record before running `domains verify`; verification performs the same DNS ownership check as the dashboard. Replace IDs with values returned by the list command. Removal and token revocation require interactive confirmation or `--yes`.

SCIM token creation prints the new secret once. Save it directly in your identity provider. Listing tokens returns only their prefix and metadata, including with `--json`. SSO configuration and SCIM group-role mapping are available with the commands below.


### SSO configuration and SCIM group mappings

```sh
bumpkit identity sso view
bumpkit identity sso set --file sso.json --yes
bumpkit identity sso remove --yes
bumpkit identity sso unlink MEMBER_EMAIL --yes
bumpkit scim groups list
bumpkit scim groups set-role GROUP_ID viewer --yes
bumpkit scim groups set-role GROUP_ID none --yes
```

`identity sso view` returns configuration, callback and SAML metadata URLs, and whether a client secret is saved. Stored secrets are never returned. `identity sso set` accepts one JSON object from a file or stdin (`--file -`), never a secret command-line flag. Prepare the file privately with mode `0600`; do not commit it. Use the supported fields: `protocol` (`oidc` or `saml`), `enabled`, `enforced`, `jit`, `default_role`, and the protocol's fields. OIDC uses `issuer`, `client_id`, and `client_secret`; SAML uses `entity_id`, `sso_url`, and `certificate` (PEM). Omitting an OIDC client secret preserves the saved secret. The response never echoes the secret supplied.

A person signed in to the dashboard sets up or changes the identity provider, turns single sign-on off, removes it, creates SCIM tokens, and grants any role above `member`. The CLI gets `HUMAN_APPROVAL_REQUIRED` for those and can make the other changes. SSO saves perform the same issuer discovery or SAML certificate validation as the dashboard. Enforcing SSO requires an enabled provider and at least one verified workspace email domain. The default role cannot be owner. Reading or updating settings through the CLI does not establish an SSO-authenticated browser session.

SCIM groups are provisioned by your identity provider. `set-role` updates the group's mapping and member permissions the same way the dashboard does, including revoking API keys when required after a downgrade. Use `none` to clear a mapping. Settings changes, SSO removal and group mapping changes require interactive confirmation or `--yes`.

### IdP-managed MCP access

> **Beta, early access.** Flag: `idp_managed_mcp`.

```sh
bumpkit identity sso managed-mcp view
bumpkit identity sso managed-mcp clients add Claude
```

| Command | What it does |
| --- | --- |
| `bumpkit identity sso managed-mcp view` | Whether it's on or required, the issuer, audience, resource, token endpoint, audience tenant and scopes for your identity provider, and the registered clients without secrets |
| `bumpkit identity sso managed-mcp set --enabled [--required] [--tenant TENANT] [--role-domain DOMAIN] --yes` | Turn it on (`--enabled`), require it for verified domains (`--required`), set the identity provider tenant for multi-tenant issuers (`--tenant`) and the Athenz domain (`--role-domain`); with no flags it turns off. Turning it on needs OIDC single sign-on turned on |
| `bumpkit identity sso managed-mcp clients add NAME [--client-id ID]` | Register an MCP client, with the client ID your identity provider puts in ID-JAGs if it chooses its own; prints its `client_id` and `client_secret` once |
| `bumpkit identity sso managed-mcp clients remove CLIENT_ID --yes` | Remove a client and stop every token issued to it |
| `bumpkit identity sso managed-mcp test --file FILE` | Check an ID-JAG without using it up; `--file -` (the default) reads standard input, and the token is never a flag |

See [IdP-managed MCP access](/docs/idp-managed-mcp).

## Stored dashboard views

These reads require an account-bound key; authenticate with `bumpkit login` and inspect the workspace with `bumpkit whoami`.

```bash
bumpkit status --json
bumpkit quality history --repository acme/api --days 90 --json
bumpkit swarm status --json
bumpkit merge-plans --json
bumpkit report confidence status --repository acme/api --days 90 --json
```

| Command | Stored view and defaults |
| --- | --- |
| `status` | Current UTC billing-month activity, the latest 5 checks, repository and people counts and onboarding state when enabled. For credits, use `bumpkit billing usage`. |
| `quality history` | Same repository options and selection as the Quality page: the latest repositories, the latest snapshots in chronological order and author totals. `--days 7|30|90` (default 30) sets the release decision trend: decisions and findings by severity per day, or per week for 90 days, and the repositories with the highest blocked rate. Without a matching repository selection, uses the most recently recorded repository. Requires an available quality feature. |
| `swarm status` | Workspace-wide active claims, active intents and stored merge plans. Requires an available swarm feature. |
| `merge-plans` | Stored merge plans ordered by repository. Requires merge planning. Unlike `merge-plan`, this does not fetch pull requests or compute a new plan. |
| `report confidence status` | How accurate scores have been, the riskiest files and areas, and the latest release scores. `--repository` filters the risk rows; recent scores stay workspace-wide, matching the dashboard. With finding feedback on, it also shows precision over time and per rule for `--days 7|30|90` (default 30). Requires confidence scores. |

These commands read stored data and do not run an analysis, publish a check or modify the workspace. `quality` without `history` still analyzes local changes. `report confidence` without `status` returns score accuracy only.

Leadership already uses `bumpkit report --days 90 --json` for the dashboard's default window. Match a selected repository with `--repo` and team with `--team`, or use the same `--from` and `--to` dates as the page.