bitbucket-cli — CLI reference

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 for interactive terminal use only (agents/scripts should omit): TUI in `config init`, colorized JSON elsewhere; errors without a TTY
`--timeout`		request timeout, e.g. 30s
`--use-context`		use a named context for this invocation
`--verbose, -v`	`false`	verbose diagnostics on stderr

bitbucket-cli auth

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` 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 branch

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 comment

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); literal \n \t \r are decoded to real newlines/tabs (use --content-file for exact bytes)
`--content-file`		read content from this file (sent as exact bytes, no escape decoding)
`--dry-run`	`false`	preview the HTTP request without sending it
`--inline`		inline anchor as <path>:<line> (line is the new/post-change file line unless --side old)
`--pr`		<workspace>/<repo>/<id> or PR URL
`--reply-to`	`0`	reply to this comment ID
`--side`	`new`	diff side the --inline line refers to: new (post-change) or old (pre-change/removed)

bitbucket-cli comment delete

Delete one or more comments

bitbucket-cli comment delete <comment-id>... [flags]

Delete a PR comment. Pass several comment IDs to delete them in one run, or a single '-' to read newline-separated IDs from stdin. --yes (or --dry-run) is required and applies to the whole batch.

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
`--tasks`	`false`	only comments that are actionable tasks
`--unresolved`	`false`	only comments whose thread is not resolved

bitbucket-cli comment resolve

Resolve (or reopen) a comment thread

bitbucket-cli comment resolve <comment-id> [flags]

Mark a PR comment thread resolved, or reopen it with --unresolve. On Data Center this is also how a task (a BLOCKER-severity comment) is completed or reopened. Bitbucket Cloud's separate task objects are not covered — this resolves comment threads, the `resolved` field surfaced by `comment list` and `pr threads`.

Options

Flag	Default	Description
`--dry-run`	`false`	preview the HTTP request without sending it
`--pr`		<workspace>/<repo>/<id> or PR URL
`--unresolve`	`false`	reopen the thread instead of resolving it

Examples

  bitbucket-cli comment resolve 42 --pr myws/myrepo/7
  bitbucket-cli comment resolve 42 --pr myws/myrepo/7 --unresolve

bitbucket-cli comment update

Edit a comment

bitbucket-cli comment update <comment-id> [flags]

Options

Flag	Default	Description
`--content`		new content (Markdown); literal \n \t \r are decoded to real newlines/tabs
`--dry-run`	`false`	preview the HTTP request without sending it
`--pr`		<workspace>/<repo>/<id> or PR URL

bitbucket-cli commit

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 config

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 file

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 pr

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 one or more PRs

bitbucket-cli pr approve <workspace>/<repo>/<id>... [flags]

Approve a PR. Pass several PR references to approve them in one run, or a single '-' to read newline-separated references from stdin. With more than one, output is a {items, has_more} aggregate with a per-PR ok/error and the exit code is non-zero if any approval failed.

Options

Flag	Default	Description
`--dry-run`	`false`	preview the HTTP request without sending it

Examples

  bitbucket-cli pr approve myws/myrepo/7
  bitbucket-cli pr approve myws/myrepo/7 myws/myrepo/8
  bitbucket-cli pr inbox --format json | jq -r '.items[].ref' | bitbucket-cli pr approve -

bitbucket-cli pr checkout

Print (or run, with --exec) git fetch (source + base) + checkout for a PR

bitbucket-cli pr checkout <workspace>/<repo>/<id> [flags]

Options

Flag	Default	Description
`--base`		base branch to fetch (default: the PR's destination branch, looked up via the API)
`--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`		git remote to fetch from (default: upstream if present, else origin)

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); literal \n \t \r are decoded to real newlines/tabs (use --description-file for exact bytes)
`--description-file`		read description from this file (sent as exact bytes, no escape decoding)
`--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 fork: <ws>/<repo> (DC also needs --target)
`--target`		destination branch (default: repo default)
`--title`		PR title

bitbucket-cli pr decline

Decline (close without merging) one or more PRs

bitbucket-cli pr decline <workspace>/<repo>/<id>... [flags]

Decline a PR. Pass several PR references to decline them in one run, or a single '-' to read newline-separated references from stdin. --yes (or --dry-run) is required and applies to the whole batch.

Options

Flag	Default	Description
`--dry-run`	`false`	preview the HTTP request without sending it
`--message`		decline message; literal \n \t \r are decoded to real newlines/tabs
`--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
`--commentable`	`false`	list the new/old-side line numbers each file can carry an inline comment on
`--line-numbers`	`false`	prefix each line with its old/new file line numbers (for picking --inline lines)
`--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 and base branch

bitbucket-cli pr fetch <workspace>/<repo>/<id> [flags]

Options

Flag	Default	Description
`--base`		base branch to fetch (default: the PR's destination branch, looked up via the API)
`--exec`	`false`	actually run `git fetch` in the current working directory
`--remote`		git remote to fetch from (default: upstream if present, else origin)

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; literal \n \t \r are decoded to real newlines/tabs
`--strategy`	`merge_commit`	merge_commit \| squash \| fast_forward
`--yes`	`false`	confirm the merge

bitbucket-cli pr request-changes

Cast (or withdraw) a request-changes / needs-work 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> [flags]

Options

Flag	Default	Description
`--comment`	`0`	only the thread containing this comment id (root or reply)
`--unresolved`	`false`	only threads that are not resolved

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; literal \n \t \r are decoded to real newlines/tabs
`--dry-run`	`false`	preview the HTTP request without sending it
`--reviewer`	`[]`	replace reviewer list (repeatable)
`--title`		new title

bitbucket-cli repo

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; literal \n \t \r are decoded to real newlines/tabs
`--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 skill

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 status

Report whether the companion Skill is loaded and installed

bitbucket-cli skill status [flags]

Options

Flag	Default	Description
`--project`	`false`	check the project skills dirs (./.claude/skills, ./.agents/skills) instead of $HOME

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 tag

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 user

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 workspace

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