Create, Edit, and View PRs

Create and inspect pull requests (PRs).

Global options work on every PR command: --json [fields], --jq <expression>, --no-color, --no-unicode, --no-truncate, --locale <locale>, -w, --workspace, -r, --repo — see Global Flags.

Field projection (--json id,title) works on list commands such as bb pr list. It does not work on bb pr create, bb pr edit or bb pr view. The payload there is a single PR carrying a reviewers array, and the projector unwraps that array instead — you get the reviewers back, or [] when there are none. Use --json --jq '{...}' on those three.

`bb pr create`

Create a pull request.

bb pr create [options]

Options

Option	Description
`-t, --title <title>`	PR title (required)
`-b, --body <body>`	PR description
`-s, --source <branch>`	Source branch (default: current branch)
`-d, --destination <branch>`	Destination branch (default: main)
`--close-source-branch`	Close source branch after merge
`--draft`	Create the PR as draft
`--reviewer <user>`	Add a reviewer by account ID or `{uuid}` (repeatable)
`--default-reviewers`	Include the repository’s default reviewers (opt-in)
`--no-default-reviewers`	Skip default reviewers even when the config key enables them

Examples

# Create a PR from current branch to main
bb pr create -t "Add new feature"

# Create a PR with full details
bb pr create -t "Add login page" -b "Implements user login functionality" -d develop

# Create a PR that will close the source branch after merging
bb pr create -t "Hotfix: Critical bug" --close-source-branch

# Create a draft PR
bb pr create -t "WIP: Add feature" --draft

# Auto-add the repository's default reviewers (matches the Bitbucket web UI)
bb pr create -t "Add new feature" --default-reviewers

# Add specific reviewers (repeatable; accepts account ID or {uuid})
bb pr create -t "Add new feature" \
  --reviewer "712020:3cfed7e0-0ed6-49fc-bb35-410a00ccee6f" \
  --reviewer "{c1cb1bb5-2e32-456e-a373-43978dc12aa1}"

# Combine defaults + explicit additions (duplicates are de-duped)
bb pr create -t "Add new feature" --default-reviewers \
  --reviewer "712020:3cfed7e0-0ed6-49fc-bb35-410a00ccee6f"

# Capture the new PR's URL from JSON output for scripting
bb pr create -t "Add new feature" --json --jq '.links.html.href'

Reviewers

By default bb pr create does not attach reviewers to the PR — this differs from the Bitbucket web UI, which auto-populates the repository’s default reviewers.

--default-reviewers opts in per-invocation. The command fetches the repository’s effective default reviewers (repo-level + project-inherited) and attaches them.
--reviewer <user> adds specific reviewers regardless of the defaults and can be passed multiple times. Accepts an account ID (e.g. 712020:3cfed7e0-...) or a UUID in curly braces (e.g. {c1cb1bb5-...}). Bitbucket Cloud’s GDPR changes retired username lookups, so nicknames are not accepted.
The PR author is automatically excluded from the reviewer list — Bitbucket rejects PRs that list the author as a reviewer.
To make --default-reviewers the default behavior, set the config key:
Terminal window
```
bb config set prCreateIncludeDefaultReviewers true
```
Pass --no-default-reviewers to skip defaults for a single invocation when this is enabled.
If the default-reviewer fetch fails (network error, permission issue, etc.) the CLI prints Could not fetch default reviewers: … Continuing without them. and creates the PR anyway. Only the defaults are dropped — reviewers you passed with --reviewer are still attached. A failed --reviewer lookup, by contrast, aborts the create.

See bb repo default-reviewers to inspect or manage the underlying default reviewer list.

`bb pr edit`

Edit an existing pull request’s title or description.

bb pr edit [id] [options]

[id] is the PR number. Omit it to auto-detect the open PR whose source branch matches your current git branch.

Options

Option	Description
`-t, --title <title>`	New PR title
`-b, --body <body>`	New PR description
`-F, --body-file <file>`	Read description from file

Examples

# Edit the title by ID
bb pr edit 42 -t "Updated: Add new feature"

# Edit the description
bb pr edit 42 -b "This PR implements the new login flow"

# Edit both title and description
bb pr edit 42 -t "New title" -b "New description"

# Auto-detect the PR from the current branch and update the title
bb pr edit -t "Updated title"

# Read the description from a file
bb pr edit 42 -F description.md

# Get the updated PR as JSON
bb pr edit 42 -t "New title" --json

Notes

When no ID is provided, the command searches for an open PR where the source branch matches your current git branch
At least one of --title, --body, or --body-file must be provided
If both -b/--body and -F/--body-file are given, the file wins and no error is raised
An unreadable path fails with Failed to read file '<path>': <reason>

`bb pr list`

List pull requests.

bb pr list [options]

Options

Option	Description
`-s, --state <state>`	Filter by state: OPEN, MERGED, DECLINED, SUPERSEDED (default: OPEN)
`--limit <number>`	Maximum number of PRs (default: 25)
`--all`	List all PRs (overrides `--limit`)
`--mine`	Show only PRs where you are a reviewer

Examples

# List open PRs in current repository
bb pr list

# List merged PRs
bb pr list -s MERGED

# List declined PRs
bb pr list -s DECLINED

# List PRs in specific repository
bb pr list -w myworkspace -r myrepo

# List with JSON output for scripting
bb pr list --json

# Project to specific fields (returns a flat array)
bb pr list --json id,title,author.display_name

# Filter with built-in --jq (no external jq binary needed)
bb pr list --json --jq '.pullRequests[] | select(.state == "OPEN") | .title'

# List more results
bb pr list --limit 50

# Fetch every open PR, ignoring the default limit of 25
bb pr list --all

# Show only PRs assigned to you for review
bb pr list --mine

Notes

Draft PRs are shown with a [DRAFT] prefix in the title
--limit is enforced across paginated API responses
The TITLE column is truncated to 50 characters, and the [DRAFT] prefix counts against that budget. Pass --no-truncate for full titles; --json output is never truncated

--mine does not mean “my PRs”

--mine filters PRs where you are assigned as a reviewer, not PRs you authored. It uses the Bitbucket API’s reviewers.uuid filter. To find PRs you created, filter the JSON yourself:

bb pr list --json --jq '.pullRequests[] | select((.author.nickname // .author.display_name) == "your-username")'

`bb pr view`

View pull request details.

bb pr view <id> [options]

<id> is the PR number.

Examples

# View PR #42 in current repository
bb pr view 42

# View PR in specific repository
bb pr view 42 -w myworkspace -r myrepo

# Get PR details as JSON
bb pr view 42 --json

# Pick out fields with built-in --jq
bb pr view 42 --json --jq '{id, title, state, author: .author.display_name}'

# Extract just the web URL
bb pr view 42 --json --jq '.links.html.href'