# PR Commands

> Task-based reference for creating, reviewing, and merging pull requests

Manage pull requests (PRs) in Bitbucket repositories. New here? Start with [Create, edit, and view](/commands/pr/create-and-edit/).

See [Global flags](/reference/global-flags/) for JSON output, workspace/repository selection, and display options.

## Command groups

[Create, edit, and view](/commands/pr/create-and-edit/)Open a PR, change its title or description, list and filter PRs, see your PR status, inspect one.

[Activity and checks](/commands/pr/activity-and-checks/)Read the activity timeline and CI build statuses before approving or merging.

[Diff and checkout](/commands/pr/diff-and-checkout/)Print the patch or diffstat, fetch the PR branch locally, open the diff in a browser.

[Review and merge](/commands/pr/review-and-merge/)Approve, request changes, decline, mark a draft ready, and merge with an explicit strategy.

[Comments](/commands/pr/comments/)List, add, view, edit, reply to, resolve, unresolve, and delete general or inline review comments.

[Reviewers](/commands/pr/reviewers/)Add and remove reviewers. Adding someone already assigned is a no-op, as is removing someone who is not.

## Pull request from the current branch

Commands that act on one pull request take its ID as an optional `[id]`: `view`, `activity`, `checks`, `edit`, `merge`, `approve`, `decline`, `ready`, `diff`, and `comments list`. Leave it out and the CLI asks Bitbucket for the open pull request whose source branch is your current git branch, in the repository your checkout’s `origin` points at. That keeps a fork’s `main` from matching your `main`, and still works from a fork with `--repo` set to upstream.

```bash
git switch feature/login
bb pr view      # the open PR from feature/login
bb pr checks
bb pr merge --strategy squash
```

It only picks a pull request when exactly one matches. No match, several matches (the same branch opened against two destinations), or a detached `HEAD` all stop with an error asking for the ID. `bb pr checkout`, `bb pr reviewers` and the other `bb pr comments` subcommands still need the ID.

## Most-used commands

| Task                                                | Command                                             |
| --------------------------------------------------- | --------------------------------------------------- |
| Create a PR                                         | `bb pr create -t "Add feature"`                     |
| Create a PR with the repository’s default reviewers | `bb pr create -t "Add feature" --default-reviewers` |
| List open PRs                                       | `bb pr list`                                        |
| List all PRs (ignore the default limit)             | `bb pr list --all`                                  |
| List PRs you opened                                 | `bb pr list --author @me`                           |
| List PRs where you are a reviewer                   | `bb pr list --reviewer @me`                         |
| Your PRs, review requests and current branch PR     | `bb pr status`                                      |
| View PR details                                     | `bb pr view 42`                                     |
| View the PR for the current branch                  | `bb pr view`                                        |
| View checks                                         | `bb pr checks 42`                                   |
| Wait for checks to finish                           | `bb pr checks 42 --watch`                           |
| Review diff                                         | `bb pr diff 42 --stat`                              |
| Checkout PR locally                                 | `bb pr checkout 42`                                 |
| Approve PR                                          | `bb pr approve 42`                                  |
| Request changes                                     | `bb pr request-changes 42`                          |
| Merge PR                                            | `bb pr merge 42 --strategy squash`                  |

## JSON for automation

List commands wrap their results in an envelope. Bare `bb pr list --json` returns `{workspace, repoSlug, state, filters, count, pullRequests}`, so a `--jq` filter starts at `.pullRequests[]`. Adding a field list (`--json id,title`) drops the envelope and returns a flat array, so the filter starts at `.[]` instead. Single-PR commands like `bb pr view` return the PR object itself, with no envelope.

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


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


# Combine projection + filter (jq runs after projection)
bb pr list --json id,title,state --jq '.[] | select(.state == "OPEN") | .title'


# Grab a PR URL from view output
bb pr view 42 --json --jq '.links.html.href'


# Capture totals for the returned diffstat page
bb pr diff 42 --stat --json --jq '{filesChanged, totalAdditions, totalDeletions}'
```

Diffstat totals can be partial; see [Diff and checkout](/commands/pr/diff-and-checkout/).

`--json <fields>` misfires on `bb pr create`, `bb pr edit` and `bb pr view`, see [Create, Edit, and View PRs](/commands/pr/create-and-edit/) for why, and [JSON Output](/reference/json-output/) for the full reference.