CLI reference
bitbucket-cli browses repositories, drives the full pull-request review and merge lifecycle, posts inline review comments, and queries branches and commits. It supports Bitbucket Cloud and Data Center / Server, and emits agent-friendly JSON with structured errors.
Generated from the command tree, so it always matches --help.
Global flags
Persistent flags accepted by every command.
| Flag | Default | Description |
|---|---|---|
--allow-writes | false | override read-only mode (defaults.read_only / BITBUCKET_CLI_READ_ONLY) for this invocation |
--base-url | Bitbucket site URL (overrides config) | |
--config | config directory (default ~/.angelmsger/bitbucket, falling back to ~/.bitbucket when only that exists) | |
--fields | comma-separated dot-path fields to keep | |
--flavor | backend flavor: cloud, datacenter or auto | |
--format, -f | output format: json, table or ndjson | |
--pretty | false | human-friendly mode: interactive TUI in `config init`, colorized JSON elsewhere |
--timeout | request timeout, e.g. 30s | |
--use-context | use a named context for this invocation | |
--verbose, -v | false | verbose diagnostics on stderr |
bitbucket-cli authcommand group
Inspect and manage stored credentials
bitbucket-cli auth
bitbucket-cli auth login
Store a credential for the configured server
bitbucket-cli auth login
Prompt for a secret and store it securely. Run `config init --pretty` first if the server URL is not set.
Examples
bitbucket-cli auth login bitbucket-cli --use-context staging auth login
bitbucket-cli auth logout
Remove the stored credential for the configured server
bitbucket-cli auth logout
bitbucket-cli auth status
Show whether a usable credential is configured
bitbucket-cli auth status
bitbucket-cli branchcommand group
List and manage repository branches
bitbucket-cli branch
bitbucket-cli branch create
Create a branch from a starting ref
bitbucket-cli branch create <name> [flags]
Options
| Flag | Default | Description |
|---|---|---|
--dry-run | false | preview without sending |
--from-ref | starting ref (branch name or commit hash) | |
--repo | <workspace>/<repo> |
bitbucket-cli branch delete
Delete a branch
bitbucket-cli branch delete <name> [flags]
Options
| Flag | Default | Description |
|---|---|---|
--dry-run | false | preview the HTTP request without sending it |
--repo | <workspace>/<repo> | |
--yes | false | confirm the deletion |
bitbucket-cli branch get
Show a single branch
bitbucket-cli branch get <name> [flags]
Options
| Flag | Default | Description |
|---|---|---|
--repo | <workspace>/<repo> |
bitbucket-cli branch list
List branches in a repository
bitbucket-cli branch list [flags]
Options
| Flag | Default | Description |
|---|---|---|
--all | false | fetch every page of results |
--cursor | start from this pagination cursor (the 'next' of a prior page) | |
--limit | 0 | page size (default from config) |
--query | filter by name substring | |
--repo | <workspace>/<repo> | |
--sort | sort key |
bitbucket-cli commentcommand group
Read and write pull-request comments
bitbucket-cli comment
bitbucket-cli comment add
Add a comment on a PR (general or inline)
bitbucket-cli comment add [flags]
Options
| Flag | Default | Description |
|---|---|---|
--content | comment body (Markdown) | |
--content-file | read content from this file | |
--dry-run | false | preview the HTTP request without sending it |
--inline | inline anchor as <path>:<line> | |
--pr | <workspace>/<repo>/<id> or PR URL | |
--reply-to | 0 | reply to this comment ID |
bitbucket-cli comment delete
Delete a comment
bitbucket-cli comment delete <comment-id> [flags]
Options
| Flag | Default | Description |
|---|---|---|
--dry-run | false | preview the HTTP request without sending it |
--pr | <workspace>/<repo>/<id> or PR URL | |
--yes | false | confirm the deletion |
bitbucket-cli comment list
List comments on a PR
bitbucket-cli comment list [flags]
Options
| Flag | Default | Description |
|---|---|---|
--all | false | fetch every page of results |
--cursor | start from this pagination cursor (the 'next' of a prior page) | |
--limit | 0 | page size (default from config) |
--pr | <workspace>/<repo>/<id> or PR URL |
bitbucket-cli comment update
Edit a comment
bitbucket-cli comment update <comment-id> [flags]
Options
| Flag | Default | Description |
|---|---|---|
--content | new content (Markdown) | |
--dry-run | false | preview the HTTP request without sending it |
--pr | <workspace>/<repo>/<id> or PR URL |
bitbucket-cli commitcommand group
Query commits in a repository
bitbucket-cli commit
bitbucket-cli commit compare
List the commits between two refs
bitbucket-cli commit compare [flags]
Options
| Flag | Default | Description |
|---|---|---|
--from | exclude commits reachable from this ref | |
--repo | <workspace>/<repo> | |
--to | include commits reachable from this ref |
bitbucket-cli commit get
Show a single commit
bitbucket-cli commit get <hash> [flags]
Options
| Flag | Default | Description |
|---|---|---|
--repo | <workspace>/<repo> |
bitbucket-cli commit list
List commits in a repository
bitbucket-cli commit list [flags]
Options
| Flag | Default | Description |
|---|---|---|
--all | false | fetch every page of results |
--branch | branch or ref to walk from | |
--cursor | start from this pagination cursor (the 'next' of a prior page) | |
--limit | 0 | page size (default from config) |
--path | filter to commits touching this path | |
--repo | <workspace>/<repo> | |
--since | earliest commit date | |
--until | latest commit date |
bitbucket-cli configcommand group
Manage bitbucket-cli configuration
bitbucket-cli config
bitbucket-cli config delete-context
Delete a context and its stored credential
bitbucket-cli config delete-context <name>
Examples
bitbucket-cli config delete-context staging
bitbucket-cli config get-contexts
List the configured contexts
bitbucket-cli config get-contexts
List every context in the config file. The current context — the one used when --use-context is not given — is marked.
Examples
bitbucket-cli config get-contexts bitbucket-cli config get-contexts --format table
bitbucket-cli config init
Interactively set up server URL and credentials
bitbucket-cli config init
Run the interactive setup wizard. It collects a server URL, detects the flavor, validates a credential and stores it. The wizard can also configure additional named contexts for working with several servers.
Examples
bitbucket-cli config init --pretty # interactive TUI (recommended) bitbucket-cli config init # plain line-by-line wizard (scripts, non-TTY)
bitbucket-cli config path
Print the config file path
bitbucket-cli config path
bitbucket-cli config show
Show the resolved configuration
bitbucket-cli config show [flags]
Options
| Flag | Default | Description |
|---|---|---|
--explain | false | annotate each value with its source |
bitbucket-cli config use-context
Switch the current context
bitbucket-cli config use-context <name>
Set the current context — the server used by default. Override it for a single command with the global --use-context flag instead.
Examples
bitbucket-cli config use-context staging
bitbucket-cli doctor
Diagnose configuration, credentials and connectivity
bitbucket-cli doctor [flags]
Options
| Flag | Default | Description |
|---|---|---|
--no-update-check | false | skip the check for a newer bitbucket-cli release |
Examples
bitbucket-cli doctor bitbucket-cli doctor --no-update-check
bitbucket-cli filecommand group
Browse and read repository source files at any ref
bitbucket-cli file
bitbucket-cli file get
Read a file's raw contents at a ref
bitbucket-cli file get <workspace>/<repo> [flags]
Options
| Flag | Default | Description |
|---|---|---|
--output | write raw bytes to this file; `-` for stdout | |
--path | file path within the repo (required) | |
--range | 1-based inclusive line range, e.g. 10:40 (client-side slicing) | |
--ref | branch / tag / commit (default: repository default branch) |
bitbucket-cli file list
List entries under a repository path at a ref
bitbucket-cli file list <workspace>/<repo> [flags]
Options
| Flag | Default | Description |
|---|---|---|
--all | false | fetch every page of results |
--cursor | start from this pagination cursor (the 'next' of a prior page) | |
--limit | 0 | page size (default from config) |
--path | path within the repo to list (empty = root) | |
--ref | branch / tag / commit (default: repository default branch) |
bitbucket-cli file tree
Recursively list files under a path at a ref
bitbucket-cli file tree <workspace>/<repo> [flags]
Options
| Flag | Default | Description |
|---|---|---|
--depth | 0 | maximum depth from --path (0 = unlimited) |
--path | subtree root (empty = repo root) | |
--ref | branch / tag / commit (default: repository default branch) |
bitbucket-cli prcommand group
Drive Bitbucket pull requests (list, review, merge)
bitbucket-cli pr
bitbucket-cli pr activity
List the activity timeline of a PR
bitbucket-cli pr activity <workspace>/<repo>/<id> [flags]
Options
| Flag | Default | Description |
|---|---|---|
--all | false | fetch every page of results |
--cursor | start from this pagination cursor (the 'next' of a prior page) | |
--limit | 0 | page size (default from config) |
bitbucket-cli pr approve
Approve a PR
bitbucket-cli pr approve <workspace>/<repo>/<id> [flags]
Options
| Flag | Default | Description |
|---|---|---|
--dry-run | false | preview the HTTP request without sending it |
bitbucket-cli pr checkout
Print (or run, with --exec) git fetch + checkout for a PR
bitbucket-cli pr checkout <workspace>/<repo>/<id> [flags]
Options
| Flag | Default | Description |
|---|---|---|
--branch | pr/%d | local branch name format; %d is replaced with the PR id |
--exec | false | actually run the git commands in the current working directory |
--remote | origin | git remote name to fetch from |
bitbucket-cli pr commits
List commits included in a PR
bitbucket-cli pr commits <workspace>/<repo>/<id> [flags]
Options
| Flag | Default | Description |
|---|---|---|
--all | false | fetch every page of results |
--cursor | start from this pagination cursor (the 'next' of a prior page) | |
--limit | 0 | page size (default from config) |
bitbucket-cli pr create
Open a new pull request
bitbucket-cli pr create [flags]
Options
| Flag | Default | Description |
|---|---|---|
--close-source-branch | false | close the source branch on merge |
--description | PR description (Markdown) | |
--description-file | read description from this file | |
--dry-run | false | preview the HTTP request without sending it |
--repo | <workspace>/<repo> | |
--reviewer | [] | reviewer UUID (Cloud) or username (DC); repeatable |
--source | source branch | |
--source-repo | cross-repo source (Cloud forks): <ws>/<repo> | |
--target | destination branch (default: repo default) | |
--title | PR title |
bitbucket-cli pr decline
Decline (close without merging) a PR
bitbucket-cli pr decline <workspace>/<repo>/<id> [flags]
Options
| Flag | Default | Description |
|---|---|---|
--dry-run | false | preview the HTTP request without sending it |
--message | decline message | |
--yes | false | confirm declining |
bitbucket-cli pr diff
Print the unified diff of a PR (use --path to scope to one file)
bitbucket-cli pr diff <workspace>/<repo>/<id> [flags]
Options
| Flag | Default | Description |
|---|---|---|
--path | restrict the diff to a single file path |
bitbucket-cli pr fetch
Print (or run, with --exec) git fetch for a PR's source ref
bitbucket-cli pr fetch <workspace>/<repo>/<id> [flags]
Options
| Flag | Default | Description |
|---|---|---|
--exec | false | actually run `git fetch` in the current working directory |
--remote | origin | git remote name to fetch from |
bitbucket-cli pr files
List changed files in a PR (diffstat: path / status / added / removed)
bitbucket-cli pr files <workspace>/<repo>/<id>
bitbucket-cli pr get
Show a pull request
bitbucket-cli pr get <workspace>/<repo>/<id> | <url> [flags]
Options
| Flag | Default | Description |
|---|---|---|
--scope | summary | summary | full | diff | commits | activity |
bitbucket-cli pr inbox
List PRs involving me across repositories (--role reviewer by default)
bitbucket-cli pr inbox [flags]
List pull requests involving the authenticated user across every accessible repository. Data Center uses the dashboard endpoint — a single call covers every project. Bitbucket Cloud has no global reviewer index, so --role reviewer (and --role participant) require --workspace; --role author works globally via the user's `/pullrequests/<uuid>` endpoint.
Options
| Flag | Default | Description |
|---|---|---|
--all | false | fetch every page of results |
--cursor | start from this pagination cursor (the 'next' of a prior page) | |
--limit | 0 | page size (default from config) |
--role | reviewer | reviewer | author | participant |
--state | OPEN | OPEN | MERGED | DECLINED | ALL |
--workspace | Cloud workspace to scope reviewer / participant queries to (ignored on Data Center) |
bitbucket-cli pr list
List pull requests in a repository
bitbucket-cli pr list [flags]
Options
| Flag | Default | Description |
|---|---|---|
--all | false | fetch every page of results |
--author | filter by author username | |
--cursor | start from this pagination cursor (the 'next' of a prior page) | |
--limit | 0 | page size (default from config) |
--query | server-side filter (Cloud `q=`) | |
--repo | <workspace>/<repo> or Bitbucket repo URL | |
--reviewer | filter by reviewer username | |
--source | filter by source branch | |
--state | OPEN | OPEN | MERGED | DECLINED | ALL |
--target | filter by destination branch |
bitbucket-cli pr merge
Merge a PR
bitbucket-cli pr merge <workspace>/<repo>/<id> [flags]
Options
| Flag | Default | Description |
|---|---|---|
--close-source-branch | false | close the source branch after merging |
--dry-run | false | preview the HTTP request without sending it |
--message | merge commit message | |
--strategy | merge_commit | merge_commit | squash | fast_forward |
--yes | false | confirm the merge |
bitbucket-cli pr request-changes
Cast (or withdraw) a request-changes vote (Cloud only)
bitbucket-cli pr request-changes <workspace>/<repo>/<id> [flags]
Options
| Flag | Default | Description |
|---|---|---|
--dry-run | false | preview the HTTP request without sending it |
--withdraw | false | withdraw a previous request-changes vote |
bitbucket-cli pr status
Show merge readiness: mergeable, conflicts, reviewers, CI builds
bitbucket-cli pr status <workspace>/<repo>/<id>
bitbucket-cli pr threads
List PR review threads grouped by file and anchor
bitbucket-cli pr threads <workspace>/<repo>/<id>
bitbucket-cli pr unapprove
Withdraw an approval
bitbucket-cli pr unapprove <workspace>/<repo>/<id> [flags]
Options
| Flag | Default | Description |
|---|---|---|
--dry-run | false | preview the HTTP request without sending it |
bitbucket-cli pr update
Edit a PR's title, description, or reviewers
bitbucket-cli pr update <workspace>/<repo>/<id> [flags]
Options
| Flag | Default | Description |
|---|---|---|
--description | new description | |
--dry-run | false | preview the HTTP request without sending it |
--reviewer | [] | replace reviewer list (repeatable) |
--title | new title |
bitbucket-cli repocommand group
Browse and manage Bitbucket repositories
bitbucket-cli repo
bitbucket-cli repo clone-url
Print the HTTPS or SSH clone URL of a repository
bitbucket-cli repo clone-url <workspace>/<repo> | <url> [flags]
Options
| Flag | Default | Description |
|---|---|---|
--protocol | https | https or ssh |
bitbucket-cli repo create
Create a repository
bitbucket-cli repo create <slug> [flags]
Options
| Flag | Default | Description |
|---|---|---|
--description | repository description | |
--dry-run | false | preview the HTTP request instead of sending it |
--name | human-friendly name (defaults to slug) | |
--private | true | make the repository private |
--workspace | workspace slug / project key |
bitbucket-cli repo delete
Delete a repository (irreversible)
bitbucket-cli repo delete <workspace>/<repo> | <url> [flags]
Options
| Flag | Default | Description |
|---|---|---|
--dry-run | false | preview the HTTP request without sending it |
--yes | false | confirm the deletion |
bitbucket-cli repo get
Show a repository's details
bitbucket-cli repo get <workspace>/<repo> | <url>
bitbucket-cli repo list
List repositories in a workspace (Cloud) or project (Data Center)
bitbucket-cli repo list [flags]
Options
| Flag | Default | Description |
|---|---|---|
--all | false | fetch every page of results |
--cursor | start from this pagination cursor (the 'next' of a prior page) | |
--limit | 0 | page size (default from config) |
--query | server-side filter expression (Cloud `q=`) | |
--role | filter by role (Cloud only): owner|contributor|member | |
--sort | sort key (Cloud only) | |
--workspace | workspace slug (Cloud) or project key (Data Center) |
bitbucket-cli skillcommand group
Install the companion Skill for coding agents (Claude Code, Codex)
bitbucket-cli skill
bitbucket-cli skill install
Deploy the embedded Skill into a coding agent's skills directory
bitbucket-cli skill install [flags]
Write the companion `bitbucket` Skill — bundled inside this binary — into a coding agent's skills directory. With no flags it probes for installed agents (Claude Code, Codex) and installs into each one found. Re-run it after upgrading the CLI to refresh the Skill to the matching version.
Options
| Flag | Default | Description |
|---|---|---|
--agent | [] | target agents instead of auto-detecting (claude-code, codex) |
--dir | explicit skills base directory; installs into <dir>/bitbucket | |
--project | false | install into the project (./.claude/skills, ./.agents/skills) instead of $HOME |
bitbucket-cli skill path
Print where the Skill would be installed, and whether it is
bitbucket-cli skill path [flags]
Options
| Flag | Default | Description |
|---|---|---|
--agent | [] | limit to specific agents (claude-code, codex) |
--dir | explicit skills base directory | |
--project | false | use the project skills directories instead of $HOME |
bitbucket-cli skill show
Print the embedded SKILL.md to stdout
bitbucket-cli skill show
bitbucket-cli skill uninstall
Remove the companion Skill from a coding agent's skills directory
bitbucket-cli skill uninstall [flags]
Delete a previously installed `bitbucket` Skill. With no flags it probes for installed agents (Claude Code, Codex) and removes the Skill from each one found.
Options
| Flag | Default | Description |
|---|---|---|
--agent | [] | target agents instead of auto-detecting (claude-code, codex) |
--dir | explicit skills base directory; removes <dir>/bitbucket | |
--project | false | remove from the project (./.claude/skills, ./.agents/skills) instead of $HOME |
bitbucket-cli tagcommand group
List and inspect repository tags
bitbucket-cli tag
bitbucket-cli tag get
Show a single tag (commit hash + date / message on Cloud)
bitbucket-cli tag get <name> [flags]
Options
| Flag | Default | Description |
|---|---|---|
--repo | <workspace>/<repo> |
bitbucket-cli tag list
List tags in a repository
bitbucket-cli tag list [flags]
Options
| Flag | Default | Description |
|---|---|---|
--all | false | fetch every page of results |
--cursor | start from this pagination cursor (the 'next' of a prior page) | |
--limit | 0 | page size (default from config) |
--query | filter by name substring | |
--repo | <workspace>/<repo> | |
--sort | sort key |
bitbucket-cli usercommand group
Discover Bitbucket users (workspace members on Cloud / global users on DC)
bitbucket-cli user
bitbucket-cli user get
Show details of a single user (UUID/account_id on Cloud; slug/username on DC)
bitbucket-cli user get <selector>
bitbucket-cli user list
List users (workspace members on Cloud / global users on DC)
bitbucket-cli user list [flags]
List Bitbucket users. Cloud: --workspace is required (Cloud has no global user list; the API exposes members of a specific workspace). DC: --workspace is ignored; the global /users endpoint is used. Use --query to filter by display-name substring.
Options
| Flag | Default | Description |
|---|---|---|
--all | false | fetch every page of results |
--cursor | start from this pagination cursor (the 'next' of a prior page) | |
--limit | 0 | page size (default from config) |
--query | filter by display-name substring | |
--workspace | workspace slug (Cloud only; ignored on DC) |
bitbucket-cli user me
Print the user the configured credentials authenticate as (alias for whoami)
bitbucket-cli user me
bitbucket-cli version
Print version information
bitbucket-cli version
bitbucket-cli whoami
Print the user the configured credentials authenticate as
bitbucket-cli whoami
Examples
bitbucket-cli whoami
bitbucket-cli workspacecommand group
List and inspect Bitbucket workspaces (Cloud) / projects (DC)
bitbucket-cli workspace
bitbucket-cli workspace get
Show details of a single workspace / project
bitbucket-cli workspace get <slug>
bitbucket-cli workspace list
List every workspace / project the current credentials can see
bitbucket-cli workspace list [flags]
List every Bitbucket workspace (Cloud) or project (Data Center) the authenticated user can see. The `slug` field of each entry is what every other command's --workspace flag expects.
Options
| Flag | Default | Description |
|---|---|---|
--all | false | fetch every page of results |
--cursor | start from this pagination cursor (the 'next' of a prior page) | |
--limit | 0 | page size (default from config) |
--query | filter by name substring | |
--role | filter by role (Cloud only): owner | collaborator | member |