Create and Merge Bitbucket Pull Requests from the CLI

atlassian-cli is an independent, community open-source project, not affiliated with, endorsed by, or sponsored by Atlassian, and is not Atlassian's official CLI (acli). Product names are used only to identify compatibility.

The CLI pull request workflow

To open a bitbucket pull request from the command line, run atlassian-cli bitbucket pr create with a repository slug, a title, a source branch, and a destination branch. To ship it, run atlassian-cli bitbucket pr merge with the PR id and a merge strategy. Everything in between, listing open PRs, reading the diff, approving, and commenting, is a single subcommand too.

The value of driving pull requests from the terminal is context. You are already in the repo, on the branch, with the commit fresh in your head. Switching to a browser, waiting for the PR page to render, filling in a form, and clicking through review menus breaks that flow. With atlassian-cli the entire lifecycle stays in the shell where you can script it, alias it, or wire it into a Git hook.

This guide walks the day-to-day workflow for a single PR: create, list, review, and merge. If you instead want an unattended script that batch-approves and merges many PRs on a schedule, that is a different job covered by the Bitbucket PR automation runbook. Here we focus on the interactive commands a developer runs by hand.

Auth and workspace setup

Bitbucket commands need a token stored in a profile and a workspace to target. Authenticate once with auth login, then confirm the credential resolves with whoami:

# Store credentials in a named profile (one time)
atlassian-cli auth login \
  --profile work \
  --base-url https://api.bitbucket.org \
  --email you@example.com \
  --token $BITBUCKET_TOKEN \
  --default

# Confirm the Bitbucket token resolves
atlassian-cli bitbucket whoami

Every Bitbucket command takes a --workspace flag that names the team or account that owns the repository. The repository itself is passed as a positional slug, the short name from the repo URL. If typing bitbucket each time feels long, the bb alias is identical: atlassian-cli bb whoami works exactly the same. See the authentication and profiles guide for token scopes and multi-account setups.

If you work across more than one Bitbucket account, store each under its own profile and add --profile <name> to any command to switch context. A work account and a personal account then never collide, and you avoid the common mistake of opening a PR in the wrong workspace. The profile you marked --default is used whenever you omit the flag, so pick the account you touch most often as the default and reach for --profile only for the exceptions.

Create a Bitbucket pull request

The pr create command needs the repository slug plus three flags: --title, --source (the branch you worked on), and --destination (usually main).

# Open a PR from feature/new into main
atlassian-cli bitbucket --workspace myteam pr create api-service \
  --title "Add retry logic to the S3 client" \
  --source feature/new \
  --destination main

The command returns the new pull request id, which you use for every follow-up action. If the source branch does not exist yet, create it first without leaving the CLI:

# Cut a branch from main, then open the PR against it
atlassian-cli bitbucket --workspace myteam branch create api-service feature/new --from main

Want the raw response so a script can capture the PR id? Add the global --format json flag and pipe it to jq:

# Capture the new PR id into a shell variable
PR_ID=$(atlassian-cli bitbucket --workspace myteam pr create api-service \
  --title "Add retry logic" \
  --source feature/new \
  --destination main \
  --format json | jq '.id')

Because the id is captured programmatically, you can chain creation straight into the review and merge steps below, which is the backbone of the full example later in this post.

List and inspect open PRs

Before creating a duplicate or picking one to review, list what is already open. The pr list command filters by state and caps the result count:

# Show the five most recent open PRs
atlassian-cli bitbucket --workspace myteam pr list api-service --state OPEN --limit 5

# As JSON for scripting or dashboards
atlassian-cli bitbucket --workspace myteam pr list api-service --state OPEN --format json

Once you have an id, pr get shows the full detail: title, description, source and destination branches, author, reviewers, and current approval state.

# Inspect a single pull request
atlassian-cli bitbucket --workspace myteam pr get api-service 123

The --state filter accepts the standard Bitbucket values (OPEN, MERGED, DECLINED, SUPERSEDED), so the same command doubles as an audit tool. Listing MERGED PRs over a sprint, for instance, gives you a quick changelog source without opening the web UI.

Approve, comment, and update

Reviewing a PR is three subcommands: read the existing thread, add your own note, and record an approval. All three take the repo slug and the PR id.

# Read the existing comment thread
atlassian-cli bitbucket --workspace myteam pr comments api-service 123

# Leave a review comment
atlassian-cli bitbucket --workspace myteam pr comment api-service 123 \
  --text "Nice fix. Can you add a test for the timeout path?"

# Record an approval
atlassian-cli bitbucket --workspace myteam pr approve api-service 123

If the title or scope changes mid-review, pr update edits the PR in place instead of forcing you to decline and reopen:

atlassian-cli bitbucket --workspace myteam pr update api-service 123 \
  --title "Add retry logic and timeout handling to the S3 client"

These commands map one to one to the buttons in the Bitbucket review screen, so nothing about the approval model changes. What changes is that a reviewer can approve ten PRs in ten short commands rather than ten page loads.

Merge a pull request

When the PR has the approvals it needs, pr merge completes it. Pass the repo slug, the PR id, and a --strategy flag:

# Merge PR 123 with a merge commit
atlassian-cli bitbucket --workspace myteam pr merge api-service 123 --strategy merge_commit

Merging through the CLI does not bypass your controls. The Bitbucket API still enforces the branch restrictions and required-approval rules configured on the destination branch, so a PR that has not met its approval count is rejected by the server rather than force-merged. If you protect main, that protection holds no matter where the merge is triggered from. You can inspect those rules with branch restrictions api-service before merging.

The --strategy flag accepts the three strategies the Bitbucket Cloud API supports. Pick the one that matches your repository policy:

If the destination has diverged, fast_forward is not possible and the API returns an error, which is the expected safety behaviour rather than a bug. In that case fall back to merge_commit or squash.

A full create-to-merge example

Here is the whole lifecycle stitched together. This is the kind of small script you might keep as a shell function for a repo you ship often.

#!/bin/bash
# Create, self-approve as reviewer, and merge a PR end to end
set -euo pipefail

WS="myteam"
REPO="api-service"
SRC="feature/new"

# 1. Open the PR and capture its id
PR_ID=$(atlassian-cli bitbucket --workspace "$WS" pr create "$REPO" \
  --title "Add retry logic to the S3 client" \
  --source "$SRC" \
  --destination main \
  --format json | jq '.id')

echo "Opened PR #$PR_ID"

# 2. Show it for a final human check
atlassian-cli bitbucket --workspace "$WS" pr get "$REPO" "$PR_ID"

# 3. Record an approval
atlassian-cli bitbucket --workspace "$WS" pr approve "$REPO" "$PR_ID"

# 4. Merge with a squash so main stays linear
atlassian-cli bitbucket --workspace "$WS" pr merge "$REPO" "$PR_ID" --strategy squash

echo "Merged PR #$PR_ID"

Step 2 prints the PR so a person can eyeball it before the script proceeds, keeping a human in the loop. Drop that line and the flow becomes fully non-interactive, which is where it starts to overlap with the automation runbook. For a hardened version with confirmation prompts, reviewer assignment, and error handling across many repositories, follow the Bitbucket PR automation runbook. For everything else the CLI can do with repos, branches, and pipelines, the Bitbucket CLI hub is the reference.

How this differs from acli

atlassian-cli is an independent, community open-source project. It is not Atlassian's official CLI (acli) and is not affiliated with Atlassian. Use the official acli for first-party vendor support; use atlassian-cli if you want a single free Rust binary that spans Jira, Confluence, Bitbucket, and Jira Service Management with one consistent command grammar.

The practical upshot for pull requests: the pr create, pr list, pr approve, and pr merge verbs read the same as their Jira and Confluence counterparts, and the global --format json, --profile, and --workspace flags behave identically everywhere. If you already script Jira from the terminal, the Bitbucket surface needs no new mental model. The full verb list lives in the command reference, and a broader tour of repo, branch, and pipeline commands is in the Bitbucket CLI guide.

FAQ

Related Resources