Create, Edit, and View PRs

Create and inspect pull requests (PRs).

See Global flags for JSON output, workspace/repository selection, and display options.

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. It returns reviewers, 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; asked for in an interactive terminal when missing)
`-b, --body <body>`	PR description
`-F, --body-file <file>`	Read the description from a file, or `-` for stdin
`-s, --source <branch>`	Source branch (default: current branch)
`-d, --destination <branch>`	Destination branch (default: the repository’s main branch)
`--close-source-branch`	Close source branch after merge
`--draft`	Create the PR as draft
`--reviewer <user>`	Add a reviewer by name, email, `@me`, 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
`--dry-run`	Print the write request instead of sending it (details)

Examples

# Create a PR from the current branch to the repository's main branch
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

# Read a multi-line markdown description from a file, or from stdin with -
bb pr create -t "Add login page" -F description.md
git log -1 --format=%b | bb pr create -t "Add login page" -F -

# 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 by nickname or display name (repeatable)
bb pr create -t "Add new feature" --reviewer jdoe --reviewer "Jane Smith"

# Or by 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'

Interactive prompts

Run bb pr create without --title in an interactive terminal and it asks for the title, then for an optional one-line description (press Enter to skip it; a --body or --body-file you passed is kept and not asked for). Use --body-file for a multi-line description. The questions come after the repository and source branch are resolved, so a bad context fails before you type anything.

Outside an interactive terminal (pipes, CI, --json, --no-input) a missing title still fails straight away with Pull request title is required. Use --title option.

Reviewers

By default bb pr create attaches no reviewers. Use --default-reviewers to include the defaults suggested by Bitbucket’s web UI.

--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 a nickname or display name (matched against the workspace members), an email (workspace admins only), @me, an account ID (e.g. 712020:3cfed7e0-...) or a UUID in curly braces (e.g. {c1cb1bb5-...}). An unknown or ambiguous name aborts the create and, when ambiguous, lists the candidates. See Identifying users for the rules. You can’t review your own PR, so the author (including @me) is dropped from the list.
The CLI excludes the author when the current-user lookup returns a UUID. If that lookup fails, Bitbucket may reject a self-review assignment.
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.

Notes

-F/--body-file sends the file content exactly as written, so markdown with backticks, quotes or $ needs no shell escaping
Passing both -b/--body and -F/--body-file fails with Cannot combine --body with --body-file. Pass one or the other.
-F - reads stdin, so it can’t also answer the title prompt: pass --title with it
An unreadable path fails with Failed to read file '<path>': <reason>

`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 use the open PR whose source branch is your current git branch (how it is picked).

Options

Option	Description
`-t, --title <title>`	New PR title
`-b, --body <body>`	New PR description
`-F, --body-file <file>`	Read the description from a file, or `-` for stdin
`--dry-run`	Print the write request instead of sending it (details)

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, or from stdin with -
bb pr edit 42 -F description.md
cat description.md | bb pr edit 42 -F -

# 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`)
`--author <user>`	Only PRs authored by this user (see below for accepted forms)
`--reviewer <user>`	Only PRs with this reviewer (see below for accepted forms)
`--mine`	Same as `--reviewer @me`
`--source <branch>`	Only PRs from this source branch
`--destination <branch>`	Only PRs into this destination branch
`--query <bbql>`	Raw BBQL filter, combined with the other filters using `AND`

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

# PRs you opened
bb pr list --author @me

# PRs assigned to you for review (same as --mine)
bb pr list --reviewer @me

# The open PR for a branch
bb pr list --source feature/login

# Merged PRs into develop
bb pr list --destination develop -s MERGED

# Anything BBQL can express, e.g. a title search
bb pr list --query 'title ~ "hotfix"'

Notes

Draft PRs are shown with a [DRAFT] prefix in the title
--limit is enforced across paginated API responses
Columns: ID, TITLE, AUTHOR, BRANCHES, UPDATED. UPDATED is relative on a terminal (2 hours ago) and ISO 8601 when piped
Long titles and branch names are shortened to fit the terminal width. Pass --no-truncate for full titles; --json output is never truncated
All filters run server-side through the Bitbucket q parameter, so --limit counts matching PRs only
--author and --reviewer accept a nickname, display name, email (workspace admins only), @me, an account ID or a {uuid}, resolved the same way as bb pr create --reviewer (see Identifying users), then match on the UUID
--mine is kept for compatibility. It means “PRs I review”, not “PRs I wrote”; use --author @me for those
A malformed --query is rejected by Bitbucket with an HTTP 400 and its error message

`bb pr status`

Show what needs your attention in the current repository: the open PR for the branch you have checked out, your open PRs, and open PRs where you are a reviewer.

bb pr status

myworkspace/myrepo

Current branch
  #42  Add login page  [feature/login]

Created by you
  #42  Add login page  [feature/login]
  #40  [DRAFT] Rework settings  [settings]

Requesting your review
  #38  Bump dependencies  [deps]

Notes

The “Current branch” section only appears filled when you run the command inside a clone of the target repository; with -w/-r pointing at another repository it reads “Not on a branch of this repository”
Each list shows up to 25 PRs; the footer names the bb pr list command that shows the rest
--json returns { workspace, repoSlug, currentBranch, currentBranchPullRequest, createdByYou, reviewRequested }; currentBranch and currentBranchPullRequest are null when there is nothing to show

`bb pr view`

View pull request details.

bb pr view [id] [options]

[id] is the PR number. Omit it to use the open PR for your current branch.

Examples

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

# View the open PR for the current branch
bb pr view

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

Notes

On a terminal the output opens in your pager (less -FRX unless BB_PAGER or PAGER says otherwise). Short output prints and returns straight away