This is the full developer documentation for Bitbucket CLI # Bitbucket CLI > Clone repositories, manage pull requests, and automate workflows from your terminal. If you know GitHub's gh, you'll feel right at home. ## Install [Section titled “Install”](#install) Requires [Bun](https://bun.sh) 1.0+ runtime. * npm ```bash npm install -g @pilatos/bitbucket-cli ``` * pnpm ```bash pnpm add -g @pilatos/bitbucket-cli ``` * Bun ```bash bun install -g @pilatos/bitbucket-cli ``` ```bash bb auth login # authenticate bb repo clone myworkspace/myrepo # clone a repository bb pr create -t "My awesome feature" # create a PR bb pr list # list open PRs ``` *** ## What can you do? [Section titled “What can you do?”](#what-can-you-do) Repository management Clone, create, list, view, and delete repositories. ```bash bb repo clone workspace/repo bb repo create my-new-project bb repo list -w myworkspace ``` Pull requests Full PR lifecycle — create, review, approve, merge. ```bash bb pr create -t "Add feature" bb pr approve 42 bb pr merge 42 --strategy squash ``` Code review View diffs, checkout PR branches, inspect checks. ```bash bb pr diff 42 bb pr checkout 42 bb pr checks 42 ``` CI/CD pipelines Trigger, inspect, and stop Bitbucket Pipelines. ```bash bb pipeline run --branch main bb pipeline list --status FAILED bb pipeline logs 42 ``` Workspaces and projects Find the workspaces you belong to and the projects inside them. ```bash bb workspace list bb project list bb project view PROJ ``` Issues, snippets, and commits Track issues, share snippets, read history, and publish build statuses. ```bash bb issue list --state open bb snippet create -t notes -f a.txt bb commit list --limit 10 bb status set abc1234 --key BB-DEPLOY --state SUCCESSFUL ``` See [Issue commands](/commands/issue/) and [Snippet commands](/commands/snippet/). Jump to the web UI Open Bitbucket pages — PRs, files, commits, settings — in your browser. ```bash bb browse 42 bb browse src/cli.ts:20 bb browse --pipelines ``` Scripting and automation Every command speaks JSON. `--json` projects to a field list, `--jq` filters in-process — no external `jq` binary, no shell pipe. ```bash bb pr list --json id,title,author.display_name bb pipeline run --branch main --json --jq '.build_number' ``` A field list returns a flat array of objects; dotted paths keep their full name as the key. See the [Scripting guide](/guides/scripting/). Raw API access Reach any Bitbucket 2.0 endpoint not yet wrapped by a typed command. ```bash bb api /user bb api /repositories/{workspace}/{repo}/pullrequests --paginate bb api POST /repositories/ws/repo/issues -f title=Bug ``` *** ## PR workflows [Section titled “PR workflows”](#pr-workflows) [Create, edit, and view](/commands/pr/create-and-edit/)Open a PR, change its title or description, list PRs, inspect one. [Review and merge](/commands/pr/review-and-merge/)Approve, decline, mark drafts ready, and merge with explicit strategy control. [Diff and checkout](/commands/pr/diff-and-checkout/)Review patch output, fetch PR branches locally, and open browser diffs. [Activity and checks](/commands/pr/activity-and-checks/)Inspect activity history and CI/build status before approving or merging. [Review comments](/commands/pr/comments/)List, add, view, edit, reply to, resolve, unresolve, and delete general or inline review comments. [Reviewers](/commands/pr/reviewers/)Add and remove reviewers. Adding someone already assigned is a no-op, as is removing someone who is not. [All PR commands](/commands/pr/) *** ## Explore [Section titled “Explore”](#explore) [Scripting guide](/guides/scripting/)JSON output, exit codes, shell patterns. [CI/CD integration](/guides/cicd/)GitHub Actions, GitLab CI, Jenkins, and more. [Recipes](/recipes/)Auto-merge on green CI, bulk reviewer assignment, fork sync, reporting, retry wrappers. [AI agent integration](/guides/ai-agents/)Wire the CLI into coding agents and tool-calling loops. [Troubleshooting](/help/troubleshooting/)Common issues and solutions. *** ## Community [Section titled “Community”](#community) This is an **unofficial**, community-maintained CLI. Not affiliated with Atlassian. * [GitHub Repository](https://github.com/0pilatos0/bitbucket-cli) * [Report Issues](https://github.com/0pilatos0/bitbucket-cli/issues) * [Contribute](https://github.com/0pilatos0/bitbucket-cli/blob/main/CONTRIBUTING.md) # API Command — Raw Authenticated Bitbucket API Access > Call any Bitbucket Cloud 2.0 API endpoint through the CLI's authenticated stack — the escape hatch for endpoints not yet wrapped by a typed command. Mirrors gh api. `bb api` sends an authenticated request to any Bitbucket Cloud 2.0 endpoint through the same stack as every other command: Basic/Bearer auth, automatic OAuth token refresh, rate-limit and transient-error retries, and secret redaction. Same shape as `gh api`. Every global flag is inherited — see [Global Flags](/reference/global-flags/). The ones that matter here are `--json [fields]`, `--jq `, `-w/--workspace`, `-r/--repo`, and `--no-color`/`--no-unicode`, which style the error and `--paginate` warning lines. `--no-truncate` and `--locale` change nothing: `bb api` prints no tables and no dates. ## `bb api` [Section titled “bb api”](#bb-api) ```bash bb api [options] [method] ``` ### Arguments [Section titled “Arguments”](#arguments) | Argument | Description | | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `method` | Optional HTTP verb (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`), case-insensitive. When omitted, defaults to `GET`, or `POST` when fields/body are present. Both `bb api GET /user` and `bb api /user` work. | | `endpoint` | The API path, relative to `https://api.bitbucket.org/2.0` (a leading `/` is optional). A redundant leading `/2.0` is stripped, so paths copied straight out of the Bitbucket REST docs (`/2.0/user`) work unchanged. `{workspace}` and `{repo}` placeholders are substituted from `--workspace`/`--repo` or the current repository. | ### Options [Section titled “Options”](#options) | Option | Description | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `-X, --method ` | HTTP method. Overrides a positional verb. | | `-f, --raw-field ` | Add a string parameter. Query param on `GET`/`HEAD`, JSON body field otherwise. Repeatable. | | `-F, --field ` | Add a typed parameter: `true`/`false`/`null` and numbers are converted; `@file` reads a file and `@-` reads stdin. Repeatable. | | `--input ` | Read the raw request body from a file, or `-` for stdin. Sent as `application/json` (override with `-H 'Content-Type: ...'`). Mutually exclusive with `-f`/`-F`. | | `-H, --header ` | Add a request header. Repeatable. `Authorization` is managed automatically and cannot be set here. | | `-i, --include` | Print the HTTP status line and response headers before the body (text mode only — suppressed under `--json`). | | `--paginate` | Follow the cursor (`next`) across pages and merge every page into a single `{ "values": [...] }` result (`GET`/`HEAD` only). | ### Argument errors [Section titled “Argument errors”](#argument-errors) Positionals are strict: at most two, and with two the first must be an HTTP verb. Every case below exits `1` without sending a request. ```text $ bb api ✗ An endpoint path is required (e.g. /user). Run `bb api --help` for usage. $ bb api GET ✗ An endpoint path is required after the method (e.g. bb api GET /user). Run `bb api --help` for usage. $ bb api GTE /user ✗ 'GTE' is not a valid HTTP method. Expected one of: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS. Run `bb api --help` for usage. (Did you mean GET?) $ bb api -X GTE /user ✗ --method must be one of: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS (Did you mean GET?) $ bb api GET /user /extra error: too many arguments for 'api'. Expected 2 arguments but got 3: GET, /user, /extra. ``` ### Examples [Section titled “Examples”](#examples) ```bash # Current user bb api /user # Explicit method (equivalent to the above) bb api GET /user # List every pull request, following pagination, using the current repository bb api /repositories/{workspace}/{repo}/pullrequests --paginate # Create an issue (method inferred as POST because fields are present) bb api /repositories/my-ws/my-repo/issues -f title=Bug -f priority=major # -F applies gh-style magic typing: true/false/null and numbers become JSON literals bb api PUT /repositories/my-ws/my-repo -F is_private=true # Send a JSON body from a file bb api PUT /repositories/my-ws/my-repo/pullrequests/42 --input body.json # Pipe a body in from stdin cat body.json | bb api POST /repositories/my-ws/my-repo/pullrequests/42/comments --input - # Force a GET with query parameters (fields normally infer POST) bb api GET /repositories/my-ws/my-repo/pullrequests -f state=MERGED # Filter the response with jq (no --json needed — bb api output is already JSON) bb api /repositories/my-ws --jq '.values[].name' # Inspect the status line and response headers bb api -i /user ``` ### How fields are sent [Section titled “How fields are sent”](#how-fields-are-sent) * **`GET` / `HEAD`** — `-f`/`-F` are appended as a URL query string (`?key=value&...`). * **Every other method** — `-f`/`-F` are assembled into a JSON request body. * Repeating the same key turns it into an array, matching `gh`. ### Placeholders [Section titled “Placeholders”](#placeholders) `{workspace}` and `{repo}` are resolved only when they actually appear in the path, so `bb api /user` works outside a checkout. ```bash # Inside a Bitbucket checkout, these resolve automatically: bb api /repositories/{workspace}/{repo}/commits # Or override explicitly: bb api -w my-ws -r my-repo /repositories/{workspace}/{repo}/commits ``` ### Output [Section titled “Output”](#output) The response body is printed to stdout. JSON responses are pretty-printed and respect the global `--json [fields]` projection and `--jq` filtering. Non-JSON responses (e.g. raw diffs) are printed verbatim, and `--json`/`--jq` are inert on them. An empty response body (e.g. a `HEAD` or `204`) prints nothing in text mode, and `{}` under `--json`, so a downstream `jq` never sees zero bytes. ```bash bb api /user ``` ```json { "type": "user", "username": "my-user", "display_name": "My User", "account_id": "557058:..." } ``` `bb api` is the only command where `--jq` works without `--json`; everywhere else a bare `--jq` fails with `✗ --jq requires --json`. On a paginated endpoint, `--json ` unwraps the `values` array and drops the envelope (`pagelen`, `size`, `next`), returning a bare array of projected objects. Projection runs before `--jq`, so once you pass `--json ` the expression sees that flat array — use `.[]`, not `.values[]`. ```bash # Envelope intact bb api /repositories/my-ws --jq '.values[].name' # Projected and unwrapped bb api /repositories/my-ws --json name --jq '.[].name' ``` ### Notes [Section titled “Notes”](#notes) * **Authentication is automatic.** The same credentials as the rest of the CLI are attached to every request; you cannot (and need not) set `Authorization` yourself. * **Only the Bitbucket API host is allowed.** Absolute URLs are accepted only when they point at `api.bitbucket.org`. This prevents the CLI from sending your token to a foreign host. Pagination cursors (which are absolute `api.bitbucket.org` URLs) are followed safely. * **`--paginate` degrades instead of erroring.** On a non-`GET`/`HEAD` request it prints `--paginate only applies to GET/HEAD requests; ignoring it.` on stderr and sends the request unpaginated. If the first response has no `values` array — a single resource rather than a collection — it prints `--paginate: response has no "values" array; returning the first page only.` and returns page 1. Both warnings are suppressed under `--json`. Combined with `-i`, the status line and headers printed are the first page’s. * **Errors surface the API response.** On a non-2xx status, the API’s error body is printed and the command exits non-zero. With `--json`, the error payload (including `statusCode` and `response`) is emitted as structured JSON. A `401` or `403` also carries a `hint` with the next step to take. The generic `404` hint is deliberately suppressed here — you supplied the URL yourself, so advice about `--workspace`/`--repo` would not apply. Note the API error body prints to **stdout** while the error line and its hint go to **stderr**, so in a terminal the hint appears after the body. * **Retries and redaction are inherited** from the shared API client — rate limits (`429`) and the transient gateway errors `502`/`503`/`504` are retried with backoff, and sensitive values are redacted from `DEBUG` logs. ### Related [Section titled “Related”](#related) * [Scripting & Automation](/guides/scripting/) — combine `bb api` with `--jq` to build pipelines over endpoints without a typed command. * [JSON Output](/reference/json-output/) — how `--json` projection and `--jq` filtering work across the CLI. * [Authentication](/getting-started/authentication/) — the auth methods that `bb api` reuses. # Auth Commands > Authentication commands reference Manage authentication with Bitbucket. Global options available on all auth commands: `--json [fields]`, `--jq `, `--no-color`, `--no-unicode`, `--locale `. See [Global flags](/reference/global-flags/) for the full list. ## `bb auth login` [Section titled “bb auth login”](#bb-auth-login) Authenticate with Bitbucket using OAuth (default) or an API token. ```bash bb auth login [options] ``` ### Options [Section titled “Options”](#options) | Option | Description | | -------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `-u, --username ` | Bitbucket username (implies API token auth) | | `-p, --password ` | Bitbucket API token (implies API token auth) | | `--with-token` | Read the API token from stdin so it never appears in shell history or process args (implies API token auth) | | `--app-password` | Use API token authentication instead of OAuth (see the note below) | | `--client-id ` | Custom OAuth consumer client ID | | `--client-secret ` | Custom OAuth consumer client secret | ### Examples [Section titled “Examples”](#examples) ```bash # Login with OAuth (opens browser) bb auth login # Login with a custom OAuth consumer bb auth login --client-id YOUR_KEY --client-secret YOUR_SECRET # Login with API token bb auth login -u myuser -p your-api-token # Login by piping the token via stdin (keeps it out of shell history and `ps`) echo "$BB_API_TOKEN" | bb auth login -u myuser --with-token # Login using environment variables (API token) export BB_USERNAME=myuser export BB_API_TOKEN=your-api-token bb auth login ``` Tip `--with-token` is the safest way to pass a token. Unlike `-p`, the token is read from stdin, so it never lands in your shell history or in process-listing tools like `ps`. It pairs well with secret managers, e.g. `my-secret-tool get bb-token | bb auth login -u myuser --with-token`. Two rules: `--with-token` cannot be combined with `-p/--password` (hard error, `VALIDATION_INVALID`), and it reads all of stdin and trims it, so an empty stdin fails instead of prompting — `bb auth login -u me --with-token < /dev/null` errors with `No API token found on stdin.` ### How it works [Section titled “How it works”](#how-it-works) OAuth is used unless any of `--app-password`, `--with-token`, `-u`, `-p`, or the `BB_API_TOKEN` environment variable is present. **OAuth flow (default):** 1. The CLI starts a local callback server and opens your browser 2. You authorize the CLI on Bitbucket’s consent screen 3. Bitbucket redirects back to the CLI with an authorization code 4. The CLI exchanges the code for access and refresh tokens 5. Tokens are stored in your config file 6. Access tokens expire after 2 hours and are refreshed automatically Note The OAuth flow needs a browser that can reach a loopback callback server on `http://localhost:19872/callback`. There is **no device-code flow**, so on headless hosts (SSH sessions, containers, CI) use API token auth — ideally `--with-token` — instead. **API token flow:** 1. You provide your Bitbucket username and API token (token via `-p`, piped to stdin with `--with-token`, or the `BB_API_TOKEN` environment variable) 2. The CLI stores the credentials in your config file 3. The CLI verifies the credentials by fetching your user information 4. If verification fails, credentials are not saved Note The `--app-password` flag is a legacy name. It triggers API token authentication, not Bitbucket app passwords (which are deprecated). Prefer `-u`/`-p`, `--with-token`, or the environment variables. ### Required scopes (API token) [Section titled “Required scopes (API token)”](#required-scopes-api-token) `bb auth login` and `bb auth status` need `read:user:bitbucket` to verify your identity, and so does `bb pr list --mine` (it resolves your account UUID). Repository and pull request commands need `read:repository:bitbucket` and `read:pullrequest:bitbucket`, plus the matching `write:` scopes to create, edit, merge, approve, or decline. Creating a repository needs the admin scope (legacy `repository:admin`) and deleting one needs the delete scope (legacy `repository:delete`); Atlassian publishes these as `admin:repository:bitbucket` and `delete:repository:bitbucket`. Everything else — pipelines, issues, snippets, projects — needs its own scope. See [Token scopes](/reference/token-scopes/) for the per-command table. OAuth logins request a fixed scope set: `account repository repository:admin pullrequest pullrequest:write`. Commands outside repositories and pull requests (`bb pipeline`, `bb issue`, `bb snippet`, `bb project`) are not covered, and neither is `bb repo delete`. Use an API token with the matching scopes for those. See the [Authentication guide](/getting-started/authentication/) for setup instructions. *** ## `bb auth logout` [Section titled “bb auth logout”](#bb-auth-logout) Log out of Bitbucket and remove stored credentials. ```bash bb auth logout [options] ``` ### Examples [Section titled “Examples”](#examples-1) ```bash bb auth logout # Machine-readable result bb auth logout --json ``` ### What gets removed [Section titled “What gets removed”](#what-gets-removed) * **OAuth**: Revokes the token on Bitbucket’s side, then removes `oauthAccessToken`, `oauthRefreshToken`, `oauthExpiresAt`, `authMethod`, and custom OAuth consumer credentials from the config file. * **API Token**: Removes `username` and `apiToken` from the config file. Other settings like `defaultWorkspace`, `skipVersionCheck`, and `versionCheckInterval` are preserved. If revocation fails, the CLI still clears local credentials and warns you to revoke the token manually (`revokeFailed: true` in `--json`). *** ## `bb auth status` [Section titled “bb auth status”](#bb-auth-status) Show current authentication status and account information. ```bash bb auth status [options] ``` ### Examples [Section titled “Examples”](#examples-2) ```bash # Check authentication status bb auth status # Get status as JSON bb auth status --json ``` ### Output [Section titled “Output”](#output) When authenticated with OAuth: ```plaintext ✓ Logged in to Bitbucket Authentication: OAuth Username: myuser Display name: My Name Account ID: 712020:3cfed7e0-0ed6-49fc-bb35-410a00ccee6f Token expires: in 1h 42m Default workspace: myworkspace ``` When authenticated with API token: ```plaintext ✓ Logged in to Bitbucket Authentication: API Token Username: myuser Display name: My Name Account ID: 712020:3cfed7e0-0ed6-49fc-bb35-410a00ccee6f Default workspace: myworkspace ``` The `Default workspace:` line appears only when `defaultWorkspace` is set. On an OAuth login with a stale token, `Token expires:` reads `expired (will refresh automatically)`. When not authenticated: ```plaintext ℹ Not logged in Run bb auth login to authenticate. ``` Caution `bb auth status --json` reports `method: "basic"` for API-token logins, while `bb auth login --json` reports `method: "api_token"` for the same credentials. In scripts, match on `!== "oauth"` rather than on either literal. See [JSON output](/reference/json-output/) for the full payloads. *** ## `bb auth token` [Section titled “bb auth token”](#bb-auth-token) Print the current access token. ```bash bb auth token [options] ``` ### Examples [Section titled “Examples”](#examples-3) ```bash # Print the token bb auth token # Copy it to the clipboard bb auth token | pbcopy # Use it against the raw API (OAuth login — bearer token) curl -H "Authorization: Bearer $(bb auth token)" https://api.bitbucket.org/2.0/user # Use it against the raw API (API token login — base64 basic credentials) curl -H "Authorization: Basic $(bb auth token)" https://api.bitbucket.org/2.0/user # Get token as JSON bb auth token --json ``` ### Output [Section titled “Output”](#output-1) * **OAuth**: Prints the bearer access token (automatically refreshes if expired). `--json` reports `type: "bearer"`. * **API Token**: Prints a base64-encoded `username:apiToken` string suitable for HTTP Basic auth headers. `--json` reports `type: "basic"`. Caution Anyone holding this token has your Bitbucket access, within the scopes you granted. Don’t paste it into logs, CI output, or issue reports. # Browse Command — Open Bitbucket Pages from the Terminal > Open Bitbucket Cloud web pages — repo home, files, branches, commits, pull requests, pipelines, settings — directly from the CLI, or print the URL for scripts. `bb browse` opens Bitbucket Cloud web pages — repository home, files, branches, commits, pull requests, pipelines, settings, and more — in your default browser. Mirrors `gh browse`. It also doubles as a script-friendly URL builder: pass `--no-browser` to print the URL instead, or `--json url` for machine-readable output. It accepts the [global flags](/reference/global-flags/), including `--json [fields]`, `--jq `, `-w, --workspace`, and `-r, --repo`. ## `bb browse` [Section titled “bb browse”](#bb-browse) ```bash bb browse [target] [options] ``` ### Arguments [Section titled “Arguments”](#arguments) | Argument | Description | | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `target` | Optional positional. Resolved by shape: pure digits → PR id, 7–40 hex chars → commit SHA, anything else → file/dir path. Append `:` to a path for a line anchor (e.g. `src/cli.ts:42`). | ### Resource flags [Section titled “Resource flags”](#resource-flags) Resource flags are mutually exclusive — pick at most one. They cannot be combined with a positional `target` (except `--branch`, which is a modifier that pairs with a path target). | Option | Opens | | ----------------- | --------------------------------------------------------------------- | | `--pr ` | A specific pull request | | `--prs` | The pull-requests list | | `--pull-requests` | Alias for `--prs` | | `--branch ` | The branch source tree (or, with ``, that path on the branch) | | `--branches` | The branches list | | `--commit [sha]` | A specific commit (defaults to current HEAD when no SHA is given) | | `--commits` | The commits list | | `--pipelines` | The pipelines page | | `--pipeline ` | A specific pipeline run | | `--downloads` | The downloads page | | `--issue ` | A specific issue | | `--issues` | The issue tracker | | `--wiki` | The wiki | | `--settings` | Repository admin / settings | ### Behavior flags [Section titled “Behavior flags”](#behavior-flags) | Option | Description | | ------------------ | --------------------------------------------------- | | `-n, --no-browser` | Print the URL to stdout instead of opening it | | `--json [fields]` | Emit `{ "url": "..." }` (does not open the browser) | ### Examples [Section titled “Examples”](#examples) ```bash # Repo home bb browse # A file at the current branch bb browse src/cli.ts # A file at a specific line bb browse src/cli.ts:42 # A file on a specific branch bb browse --branch release/2.0 src/cli.ts # Just the branch tree bb browse --branch release/2.0 # Pull request #217 (positional shorthand) bb browse 217 # Pull request #217 (explicit) bb browse --pr 217 # Pull-request list bb browse --prs # A commit by SHA bb browse abc1234 # Current HEAD commit bb browse --commit # Pipelines tab bb browse --pipelines # Repo settings bb browse --settings # Print the URL only — useful in scripts and pipes bb browse --pr 217 --no-browser # Script-friendly URL retrieval bb browse --pr 217 --json url ``` ### Notes [Section titled “Notes”](#notes) * **Positional disambiguation.** A bare `` is treated as a pull request id (the most common case). Use `--issue ` to open an issue with the same number. * **Branch defaulting.** When you give a path target without `--branch`, the CLI uses your current git branch (`git rev-parse --abbrev-ref HEAD`). Outside a git checkout (when using `--workspace`/`--repo` overrides), it falls back to the literal `HEAD` segment, which Bitbucket resolves server-side to the repository’s default branch. * **URL encoding.** Workspace and repository slugs, branch names, and path segments are URL-encoded individually, so branches with slashes (`feature/foo`) and paths or names with spaces still produce valid URLs. Path separators (`/` between segments) are preserved. * **No API calls.** `bb browse` never talks to the Bitbucket API — it only builds URLs. It does shell out to git: to resolve workspace and repository from your remote (skipped only when you pass both `-w` and `-r`), and to resolve a ref — `git rev-parse --abbrev-ref HEAD` for a path target without `--branch`, `git rev-parse HEAD` for `--commit` with no SHA. `--branch `, an explicit SHA, and the resource flags need no extra git call. * **`--json` does not open the browser.** Either output mode (JSON or `--no-browser`) suppresses the open action, so scripts can capture the URL deterministically. ### Output [Section titled “Output”](#output) In default mode, `bb browse` prints a short status line and shells out to the [`open`](https://www.npmjs.com/package/open) helper to launch the URL. With `--no-browser`: ```text https://bitbucket.org/myworkspace/myrepo/pull-requests/217 ``` With `--json`: ```json { "url": "https://bitbucket.org/myworkspace/myrepo/pull-requests/217" } ``` `--jq` output is JSON-quoted (the embedded jq has no `-r`), so for a bare, pipe-ready URL use `--no-browser` as shown above. Reach for `--jq` when you are feeding a JSON consumer: ```bash bb browse --pr 217 --json url --jq '.url' ``` ### Related [Section titled “Related”](#related) * [`bb pr diff --web`](/commands/pr/diff-and-checkout/) — open the PR diff page directly in the browser. * [Repository Context](/guides/repository-context/) — how the CLI infers workspace and repository from your current directory. * [Scripting & Automation](/guides/scripting/) — capture URLs from `bb browse` to feed other tools. # Commit Commands - Inspect Repository History > Reference for Bitbucket CLI commit commands. List commit history for a branch, tag, or revision and view full commit details from the command line. Inspect commits in a Bitbucket repository — list the history of a branch, tag, or revision, and view the full details of a single commit. Commit commands operate at **repository** scope. Run them inside a cloned Bitbucket repository, or pass `-w, --workspace ` and `-r, --repo ` explicitly. Global options available on all commit commands: `--json [fields]`, `--jq `, `--no-color`, `--no-unicode`, `--no-truncate`, `--locale `, `-w, --workspace`, `-r, --repo`. A `` is a full 40-character hash or any abbreviated prefix (`abc1234`). `--json` output is wrapped in an envelope keyed by `workspace` and `repoSlug`; the `# →` comments below show each shape. *** ## `bb commit list` [Section titled “bb commit list”](#bb-commit-list) List commits, newest first. ```bash bb commit list [options] ``` ### Options [Section titled “Options”](#options) | Option | Description | | ------------------ | ---------------------------------------------------------------------------- | | `--ref ` | Branch, tag, or commit SHA to list history for (default: current git branch) | | `--limit ` | Maximum number of commits (default: 25) | | `--all` | List all commits (overrides `--limit`) | ### Examples [Section titled “Examples”](#examples) ```bash # Inside a git repository: history of the current branch bb commit list bb commit list --ref main bb commit list --ref v1.0.0 --limit 50 # → { workspace, repoSlug, [ref], count, commits } bb commit list --json # Hashes only, via built-in --jq bb commit list --json --jq '.commits[].hash' ``` ### Notes [Section titled “Notes”](#notes) * **Default ref:** with no `--ref`, the CLI uses the current git branch when run inside a git repository. When branch detection fails (outside a git repository, detached HEAD), it falls back to the repository’s default commit listing instead of erroring. * Columns: short hash (7 characters), first line of the commit message (truncated to 60 characters; disable with `--no-truncate`), author (Bitbucket display name, or the name parsed from the raw git author), and commit date. * `--limit` is enforced across paginated responses. When results are capped the CLI prints `Showing 25 commits. Use --limit or --all to see more.` (suppressed with `--json`). * An unknown `--ref` returns `Ref 'no-such-branch' not found in acme/api. Pass --ref to choose a different ref.` *** ## `bb commit view` [Section titled “bb commit view”](#bb-commit-view) View the full details of a single commit. `` is a full or abbreviated hash. ```bash bb commit view [options] ``` ### Examples [Section titled “Examples”](#examples-1) ```bash bb commit view abc1234 # → { workspace, repoSlug, commit } bb commit view abc1234 --json # Raw author string of the commit bb commit view abc1234 --json --jq '.commit.author.raw' ``` ### Notes [Section titled “Notes”](#notes-1) * The human view shows the full hash, author (raw `Name ` when available), date, parent commits (short hashes), and the complete commit message including the body. * In `--json` mode, `commit` is the raw commit resource as returned by the Bitbucket API (hash, author, parents, message, links, …). * An unknown sha returns `Commit abc1234 not found in acme/api.` *** ## See also [Section titled “See also”](#see-also) * [Status Commands](/commands/status/) — read and report build statuses on commits. * [Scripting & Automation](/guides/scripting/) — JSON envelopes, `--jq`, exit codes. # Completion Commands > Install or remove bb tab completion for bash, zsh, and fish, and see exactly what the completer suggests. Tab completion for bash, zsh, and fish. Global options: every global flag is accepted here (see [Global Flags](/reference/global-flags/)). Only `--json`, `--no-color` and `--no-unicode` change anything — `--jq` needs `--json`, and `--no-truncate`/`--locale`/`-w`/`-r` have no output to affect. ## `bb completion install` [Section titled “bb completion install”](#bb-completion-install) ```bash bb completion install [options] ``` This command is interactive. It asks two questions: 1. **“Which Shell do you use ?”** — pick `bash`, `zsh`, or `fish`. The default is `bash`; the prompt does **not** preselect your current shell. 2. **“We will install completion to ``, is it ok ?”** — confirm, or decline and supply an absolute path of your own. It then appends a source line to that file and writes the completion script under `~/.config/tabtab/`. | Shell | Config file offered | | ----- | ---------------------------- | | bash | `~/.bashrc` | | zsh | `~/.zshrc` | | fish | `~/.config/fish/config.fish` | Because it prompts, `bb completion install` is not scriptable. It blocks on the shell question in CI, `--json` included. A failure throws error code `9001` ([`COMPLETION_INSTALL_FAILED`](/reference/error-codes/)) with the message `Failed to install completions: `, and the command exits `1`. ### After installing [Section titled “After installing”](#after-installing) Restart your shell, or source the file you chose: ```bash source ~/.bashrc # bash source ~/.zshrc # zsh source ~/.config/fish/config.fish # fish ``` Then check it works: ```bash bb # every top-level command (the root flags are offered too) bb repo # clone, create, list, view, delete, default-reviewers ``` ### JSON output [Section titled “JSON output”](#json-output) `--json` replaces both the success line and the “Restart your shell…” follow-up with a single object: ```json { "success": true, "shellCompletion": { "command": "bb", "installed": true } } ``` ## `bb completion uninstall` [Section titled “bb completion uninstall”](#bb-completion-uninstall) ```bash bb completion uninstall [options] ``` No prompt. It deletes `~/.config/tabtab/bb.`, removes the `bb` lines from `~/.config/tabtab/__tabtab.`, and drops the source line from your shell config once no other package is left in that file. Both `` and that config file come from `$SHELL` — your login shell, not the shell you happen to be typing in, and not the shell you picked at the install prompt. If they disagree, the source line is left behind and you have to delete it by hand. On success it prints `✓ Shell completions uninstalled successfully!`; with `--json` you get the same envelope as install, with `"installed": false`. Most uninstall failures are swallowed by tabtab: it prints `ERROR while uninstalling ` and resolves anyway, so the command still reports success and exits `0`. Error code `9002` ([`COMPLETION_UNINSTALL_FAILED`](/reference/error-codes/)) only fires for failures thrown outside that handler. ## What gets completed [Section titled “What gets completed”](#what-gets-completed) Completions are generated from the live command tree, so they always match the commands and flags the CLI actually ships. * **Commands and subcommands** — every command in the tree, at every depth. * **Options** — every flag on the command plus the inherited globals (`--json`, `--jq`, `--no-color`, `--no-unicode`, `--no-truncate`, `--locale`, `--workspace`, `--repo`, `--help`), plus `--version` on the bare `bb`. Only long forms are suggested; short aliases like `-w` still work but are never offered. * **Flag values** for options with a fixed set of choices. Commands and flags carry their help text as a completion description. zsh and fish display it alongside the name; bash shows bare names. Enum **values** never carry a description, so they are bare in every shell. ### Flag-value completion [Section titled “Flag-value completion”](#flag-value-completion) Completing right after a flag that takes a fixed set of values suggests those values, and nothing else: ```bash $ bb pr merge 42 --strategy merge_commit squash fast_forward squash_fast_forward rebase_fast_forward rebase_merge $ bb pr list --state OPEN MERGED DECLINED SUPERSEDED $ bb snippet list --role owner contributor member $ bb pr diff --color auto always never $ bb api -X GET POST PUT PATCH HEAD OPTIONS DELETE ``` ### Example session [Section titled “Example session”](#example-session) ```bash $ bb pr pr $ bb pr activity approve checks checkout comments create decline diff edit list merge ready reviewers view $ bb pr create -- # the command's own flags, plus inherited global flags: --title --body --source --destination --close-source-branch --draft --reviewer --default-reviewers --no-default-reviewers --json --jq --no-color --no-unicode --no-truncate --locale --workspace --repo --help ``` ### Related [Section titled “Related”](#related) * [Global Flags](/reference/global-flags/) — the flags the completer offers on every command. * [Error Codes](/reference/error-codes/) — `9001` and `9002` in context. * [Scripting & Automation](/guides/scripting/) — `--json` envelopes and exit codes for the non-interactive commands. # Config Commands > Configuration commands reference Manage CLI configuration settings. Global options available on all config commands: `--json [fields]`, `--jq `, `--no-color`, `--no-unicode`, `--locale `. See [Global flags](/reference/global-flags/) for the full list. ## Configuration file [Section titled “Configuration file”](#configuration-file) Configuration is stored in a JSON file at: * **Linux/macOS**: `~/.config/bb/config.json` (fixed path — `XDG_CONFIG_HOME` is not read) * **Windows**: `%APPDATA%\bb\config.json`, falling back to `%USERPROFILE%\AppData\Roaming\bb\config.json` On Linux and macOS the CLI creates the directory `0700` and the file `0600`, and refuses to run if either grants group or other access. See [Configuration file](/reference/configuration/) for the permission rules and how to fix them. ## Available settings [Section titled “Available settings”](#available-settings) | Key | `bb config get` | `bb config set` | Description | | --------------------------------- | ------------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------ | | `defaultWorkspace` | yes | yes | Default workspace for commands | | `skipVersionCheck` | yes | yes | Disable update notifications (default: false) | | `versionCheckInterval` | yes | yes | Days between update checks (default: 1) | | `prCreateIncludeDefaultReviewers` | yes | yes | Auto-add the repository’s default reviewers on `bb pr create` (default: false) | | `username` | yes | no — use `bb auth login` | Bitbucket username | | `apiToken` | no — use `bb auth token` | no — use `bb auth login` | Bitbucket API token (masked in `bb config list`) | | `lastVersionCheck` | no | no | Timestamp of the last update check. Auto-managed; `bb config get lastVersionCheck` fails with `Unknown config key` | `bb auth login` also writes `authMethod` — `basic` for API tokens, `oauth` for OAuth — and, after an OAuth login, the `oauth*` keys (`oauthAccessToken`, `oauthRefreshToken`, `oauthExpiresAt`, and custom consumer credentials). Only `bb auth login` and `bb auth logout` touch those keys; see [Configuration file](/reference/configuration/) for the full schema. ### Configuration file format [Section titled “Configuration file format”](#configuration-file-format) ```json { "authMethod": "basic", "username": "myuser", "apiToken": "ATBB_xxxxxxxxxxxxxxxxxxxx", "defaultWorkspace": "myworkspace", "skipVersionCheck": false, "versionCheckInterval": 1, "prCreateIncludeDefaultReviewers": false } ``` Don’t edit this file by hand. Use `bb config set` for settings and `bb auth login` for credentials. ## `bb config get` [Section titled “bb config get”](#bb-config-get) Print a configuration value. ```bash bb config get ``` Readable keys: `username`, `defaultWorkspace`, `skipVersionCheck`, `versionCheckInterval`, `prCreateIncludeDefaultReviewers`. Any other key exits `1` with `Unknown config key ''`, except `apiToken`, which points you at `bb auth token`. ### Examples [Section titled “Examples”](#examples) ```bash # Get default workspace bb config get defaultWorkspace # Get username bb config get username # Get output as JSON bb config get defaultWorkspace --json ``` *** ## `bb config set` [Section titled “bb config set”](#bb-config-set) Set a configuration value. ```bash bb config set ``` Settable keys, and the values each accepts: | Key | Accepted values | Stored type | | --------------------------------- | ---------------------------------- | ----------- | | `defaultWorkspace` | Any string | string | | `skipVersionCheck` | `true` or `false` | boolean | | `versionCheckInterval` | Positive integer (`>= 1`), in days | number | | `prCreateIncludeDefaultReviewers` | `true` or `false` | boolean | ### Examples [Section titled “Examples”](#examples-1) ```bash # Set default workspace bb config set defaultWorkspace myworkspace # Disable update notifications bb config set skipVersionCheck true # Check for updates weekly instead of daily bb config set versionCheckInterval 7 # Get output as JSON bb config set defaultWorkspace myworkspace --json ``` Values that don’t match the key’s type are rejected and exit `1`: ```bash bb config set skipVersionCheck maybe ``` ```plaintext ✗ Invalid value for 'skipVersionCheck'. Expected 'true' or 'false'. ``` JSON output for typed keys: ```json { "success": true, "key": "skipVersionCheck", "value": true } ``` Caution `bb config set username …` and `bb config set apiToken …` are rejected outright: ```plaintext ✗ Cannot set 'username' directly. Use 'bb auth login' to configure authentication. ``` Use `bb auth login` for credentials. *** ## `bb config list` [Section titled “bb config list”](#bb-config-list) List all configuration values. ```bash bb config list [options] ``` ### Examples [Section titled “Examples”](#examples-2) ```bash # List all config bb config list # List as JSON for scripting bb config list --json # Read one value out of the JSON bb config list --json --jq '.config.defaultWorkspace' ``` ### Output [Section titled “Output”](#output) ```plaintext Config file: /Users/you/.config/bb/config.json KEY VALUE ---------------- ----------- username myuser defaultWorkspace myworkspace apiToken ******** skipVersionCheck false Settable keys: defaultWorkspace, skipVersionCheck, versionCheckInterval, prCreateIncludeDefaultReviewers. Run 'bb config set --help' for details. ``` With an empty config file the table is replaced by `ℹ No configuration set`; the `Config file:` line and the `Settable keys:` footer still print. `apiToken` is always masked. OAuth credentials are omitted from `bb config list` entirely — after an OAuth login the listing shows no auth rows at all. # Issue Commands - Manage the Bitbucket Issue Tracker > Reference for Bitbucket CLI issue commands. List, view, create, edit, close, and comment on Bitbucket Cloud issues from the command line, mirroring gh issue. Manage issues in a repository’s built-in issue tracker — list, view, create, edit, close, and comment, mirroring the ergonomics of `gh issue`. Issue commands operate at **repository** scope. Run them inside a cloned Bitbucket repository, or pass `-w, --workspace ` and `-r, --repo ` explicitly. Global options available on all issue commands: `--json [fields]`, `--jq `, `--no-color`, `--no-unicode`, `--no-truncate`, `--locale `, `-w, --workspace`, `-r, --repo`. See [Global flags](/reference/global-flags/) for the full list. The per-command tables below list only command-specific options. Caution Bitbucket’s issue tracker is **opt-in per repository** and disabled by default. When it is off, every issues endpoint answers `404` and `bb issue list` / `bb issue create` report: *“This repository’s issue tracker is disabled (or the repo was not found). Enable it under Repository settings → Issue tracker on Bitbucket, or check `--workspace`/`--repo`. Many teams use Jira instead — see the docs.”* *** ## `bb issue list` [Section titled “bb issue list”](#bb-issue-list) List issues. By default only “open-ish” issues are shown (states `new` and `open`), sorted most recently updated first. ```bash bb issue list [options] ``` ### Options [Section titled “Options”](#options) | Option | Description | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `--state ` | Filter by exact state: `submitted`, `new`, `open`, `resolved`, `on-hold`, `invalid`, `duplicate`, `wontfix`, or `closed` | | `--kind ` | Filter by kind: `bug`, `enhancement`, `proposal`, or `task` | | `--assignee ` | Filter by assignee username | | `--reporter ` | Filter by reporter username | | `--query ` | Raw Bitbucket `q` filter expression (escape hatch) | | `--limit ` | Maximum number of issues (default: 25) | | `--all` | List all issues (overrides `--limit`) | ### Examples [Section titled “Examples”](#examples) ```bash bb issue list bb issue list --state resolved bb issue list --kind bug --assignee some.user bb issue list --limit 50 # Raw q escape hatch (replaces the default state filter) bb issue list --query 'priority="blocker" AND state!="closed"' # Project to specific fields (returns a flat array) bb issue list --json id,title,state # Filter with built-in --jq — ids of critical issues bb issue list --json --jq '.issues[] | select(.priority == "critical") | .id' ``` ### Notes [Section titled “Notes”](#notes) * **Filter composition:** without `--state` or `--query` the command filters on `(state="new" OR state="open")`. An explicit `--state` matches exactly (the CLI’s `on-hold` maps to the API’s `"on hold"`). `--kind`, `--assignee`, and `--reporter` clauses are AND-ed on. * **`--query` grouping:** the expression replaces the default state filter. It is wrapped in parentheses and placed first in the AND-ed clause list, so a top-level `OR` inside it stays correctly grouped against `--kind`/`--assignee`/`--reporter`. The composed expression comes back as `filters.q` in `--json` output. * **JSON envelope:** `{ workspace, repoSlug, filters, count, issues }`, where `filters` echoes the active flags plus the effective `q` expression. * TITLE is truncated to 50 characters in the table; pass the global `--no-truncate` for full titles (`--json` always carries the full value). UPDATED is formatted with `--locale`/`BB_LOCALE`, falling back to the system locale and then `en-US`. * `--limit` is enforced across paginated responses; a hint shows when results were capped (suppressed with `--json`). *** ## `bb issue view` [Section titled “bb issue view”](#bb-issue-view) View the full details of a single issue. ```bash bb issue view [options] ``` ### Arguments [Section titled “Arguments”](#arguments) | Argument | Description | | -------- | -------------------- | | `id` | Issue ID (e.g. `42`) | ### Examples [Section titled “Examples”](#examples-1) ```bash bb issue view 42 # Print just the state, for a CI guard bb issue view 42 --json --jq '.issue.state' ``` ### Notes [Section titled “Notes”](#notes-1) * Human output shows the id, title, state, kind, priority, reporter, assignee, created/updated dates, votes, the issue body, and the web URL. * **JSON envelope:** `{ workspace, repoSlug, issue }`. * A `404` is reported as `Issue # not found in /.`, with a reminder that a disabled issue tracker 404s identically. *** ## `bb issue create` [Section titled “bb issue create”](#bb-issue-create) Create an issue. ```bash bb issue create --title