Reviewers

Manage pull request (PR) reviewers.

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

Looking for repo-level defaults?

This page covers reviewers on existing pull requests. To manage the repository’s default reviewers, the list Bitbucket auto-suggests when someone opens a PR, see bb repo default-reviewers. bb pr create can also auto-apply them via --default-reviewers or the prCreateIncludeDefaultReviewers config key.

Identifying users

The <user> positional (and bb pr create --reviewer) accepts any of these:

Form	Example	How it is resolved
@me	@me	The authenticated account (GET /user)
Account ID	712020:3cfed7e0-0ed6-49fc-bb35-410a00ccee6f	Looked up directly
UUID in braces	{c1cb1bb5-2e32-456e-a373-43978dc12aa1}	Looked up directly
Email	[email protected]	Workspace members filtered by email (admins only)
Nickname or display name	jdoe, "Jane Doe"	Exact, case-insensitive match on workspace members

Names are matched against the members of the PR’s workspace. A nickname match wins over a display name match. The member list is fetched once per command run (one request per 50 members) and reused for every name you pass. An email asks Bitbucket for that member directly and only counts if the member Bitbucket returns has that email.

• No match fails with No member of workspace '<ws>' has the nickname or display name '<name>' (error code 2002).

• Several matches (two people called “John Park”) fail with error code 5002 and list every candidate with its account ID, so you can rerun with the ID:

  'John Park' matches 2 members of workspace 'myworkspace':
    John Park  nickname: jpark  712020:3cfed7e0-0ed6-49fc-bb35-410a00ccee6f
    John Park  nickname: johnp  712020:9a1b2c3d-0ed6-49fc-bb35-410a00ccee6f
  Pass one of the account IDs above instead.

• Email lookups only work when Bitbucket lets you filter members by email, which it allows for workspace admins and workspace or integration tokens. Bitbucket never returns email addresses, so for everyone else an email simply finds no match; use a name or ID instead.

Account IDs and UUIDs also come back from bb pr reviewers list --json, as the account_id and uuid fields, which is the most reliable form for scripts:

# One object per reviewer: [{"account_id": "712020:3cfed..."}, …]
bb pr reviewers list 42 --json account_id

# Raw IDs for shell scripts
bb pr reviewers list 42 --json --jq '.reviewers[].account_id' --raw-output

--json account_id returns a flat array of objects. Built-in --jq prints JSON-quoted strings unless you add --raw-output. For assigning reviewers in bulk, including author exclusion, see the reviewer assignment recipe.

See bb pr create for matching --reviewer examples.

bb pr reviewers

Subcommand	Description
list <id>	List reviewers on a pull request
add <id> <user>	Add a reviewer to a pull request
remove <id> <user>	Remove a reviewer from a pull request

None of the three take command-specific options, only the global ones. <id> is the pull request ID; <user> is any of the forms above.

---

bb pr reviewers list

bb pr reviewers list <id>

# List reviewers on PR #42
bb pr reviewers list 42

# List reviewers in a specific repository
bb pr reviewers list 42 -w myworkspace -r myrepo

Human output is a two-column table of display name and account ID. If the pull request has no reviewers, the command prints No reviewers assigned to this pull request. The deprecated username field is never shown, Bitbucket Cloud stopped returning it for GDPR reasons.

--json returns the full envelope:

{
  "workspace": "myworkspace",
  "repoSlug": "myrepo",
  "pullRequestId": 42,
  "count": 1,
  "reviewers": [
    {
      "display_name": "Jane Doe",
      "account_id": "712020:3cfed7e0-0ed6-49fc-bb35-410a00ccee6f",
      "uuid": "{c1cb1bb5-2e32-456e-a373-43978dc12aa1}"
    }
  ]
}

---

bb pr reviewers add

Add a reviewer by nickname, display name, email, @me, account ID or UUID.

bb pr reviewers add <id> <user>

Options

Option	Description
--dry-run	Print the write request instead of sending it (details)

# By nickname or display name
bb pr reviewers add 42 jdoe
bb pr reviewers add 42 "Jane Doe"

# Yourself
bb pr reviewers add 42 @me

# By account ID
bb pr reviewers add 42 "712020:3cfed7e0-0ed6-49fc-bb35-410a00ccee6f"

# By UUID (keep the braces, and quote the argument so the shell leaves them alone)
bb pr reviewers add 42 "{c1cb1bb5-2e32-456e-a373-43978dc12aa1}"

Adding someone who is already a reviewer succeeds and changes nothing.

---

bb pr reviewers remove

Remove a reviewer. Same <user> rules as add.

bb pr reviewers remove <id> <user>

Options

Option	Description
--dry-run	Print the write request instead of sending it (details)

# By nickname
bb pr reviewers remove 42 jdoe

# By account ID
bb pr reviewers remove 42 "712020:3cfed7e0-0ed6-49fc-bb35-410a00ccee6f"

# By UUID
bb pr reviewers remove 42 "{c1cb1bb5-2e32-456e-a373-43978dc12aa1}"

Removing someone who is not a reviewer succeeds and changes nothing.

JSON output for add and remove

Both commands emit the same envelope. reviewer.username echoes the <user> value you passed, whatever form it was in; reviewer.uuid is the resolved UUID.

{
  "success": true,
  "pullRequestId": 42,
  "reviewer": {
    "username": "712020:3cfed7e0-0ed6-49fc-bb35-410a00ccee6f",
    "uuid": "{c1cb1bb5-2e32-456e-a373-43978dc12aa1}"
  },
  "pullRequest": { "id": 42, "title": "Add user authentication" }
}

When the user lookup fails

Both commands resolve <user> before touching the pull request, so a failed lookup never changes the reviewer list. Names and emails fail with the messages described under Identifying users. A bad account ID or UUID fails at Bitbucket’s user endpoint with a 404, carrying whatever message Bitbucket returns. The CLI appends its generic 404 hint, which mentions --workspace and --repo, but for these two commands the wrong value is almost always the <user> argument, not the repository.