Create, Edit, and View PRs

Create and inspect pull requests.

Global options available on all PR commands: --json [fields], --jq <expression>, --no-color, -w, --workspace, -r, --repo.

`bb pr create`

Create a new pull request.

bb pr create [options]

Options

Option	Description
`-t, --title <title>`	Pull request title (required)
`-b, --body <body>`	Pull request description
`-s, --source <branch>`	Source branch (default: current branch)
`-d, --destination <branch>`	Destination branch (default: main)
`-w, --workspace <workspace>`	Workspace
`-r, --repo <repo>`	Repository
`--close-source-branch`	Close source branch after merge
`--draft`	Create the pull request 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
`--json`	Output as JSON

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 repo'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'

# Project the response to just the fields you need
bb pr create -t "Add new feature" --json id,title,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 PR is still created without reviewers and a warning is printed — the failure does not block the creation.

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]

Arguments

Argument	Description
`id`	Pull request ID (optional - auto-detects from current branch)

Options

Option	Description
`-t, --title <title>`	New pull request title
`-b, --body <body>`	New pull request description
`-F, --body-file <file>`	Read description from file
`-w, --workspace <workspace>`	Workspace
`-r, --repo <repo>`	Repository
`--json`	Output as JSON

Examples

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

# Edit PR 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 PR from current branch and update title
bb pr edit -t "Updated title"

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

# Get 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
The --body-file option reads the entire file contents as the new description

`bb pr list`

List pull requests.

bb pr list [options]

Options

Option	Description
`-w, --workspace <workspace>`	Workspace
`-r, --repo <repo>`	Repository
`-s, --state <state>`	Filter by state: OPEN, MERGED, DECLINED, SUPERSEDED (default: OPEN)
`--limit <number>`	Maximum number of PRs (default: 25)
`--mine`	Show only pull requests where you are a reviewer
`--json`	Output as JSON

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

# Show only pull requests 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

--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, use --json with jq:

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]

Arguments

Argument	Description
`id`	Pull request ID

Options

Option	Description
`-w, --workspace <workspace>`	Workspace
`-r, --repo <repo>`	Repository
`--json`	Output as JSON

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

# Project to specific fields
bb pr view 42 --json id,title,state,author.display_name

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