A gh-Style Bitbucket CLI Workflow

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 gh-Shaped Hole in Bitbucket

If you have ever used GitHub's gh, moving to Bitbucket feels like losing a limb. Typing gh pr create, gh pr list, and gh pr merge becomes muscle memory. On Bitbucket, the reflex hits nothing. A common developer request is short and specific: they want a Bitbucket CLI like gh, and they cannot find one that behaves the way they expect.

The short answer: there is no first-party command that mirrors gh one for one, but you can get the same gh-style workflow today with atlassian-cli. It is an independent, MIT-licensed Rust binary that talks to the Bitbucket Cloud REST API, so listing, creating, reviewing, and merging pull requests all happen from the terminal, without a browser tab in sight. This post maps every gh pr and gh repo verb you already know onto its atlassian-cli equivalent, then shows you how to alias it so it feels like home.

How This Differs From acli

This distinction matters because searching for a Bitbucket CLI surfaces both tools. Atlassian's acli is the vendor-supported option and is the right pick when you need official support guarantees. atlassian-cli is the community alternative built for people who liked how gh felt and want that ergonomics across the whole Atlassian stack from one binary. The rest of this guide is about the second path.

The gh to atlassian-cli Command Map

Here is the translation table. Every command assumes you have authenticated once with atlassian-cli auth login (see the auth guide). The bb alias is a built-in shorthand for bitbucket, so atlassian-cli bb pr list and atlassian-cli bitbucket pr list are identical.

The one structural difference: gh infers the repository from your local git remote, while atlassian-cli asks you for the --workspace and the repository slug explicitly. That is a deliberate trade for scriptability, and the alias section below hides it so you rarely type it by hand.

Your First gh-Style PR Workflow

Let us walk the classic loop: branch, push, open a PR, get it reviewed, merge. Assume your workspace is myteam and the repo slug is api-service.

Open the pull request

You push a branch with plain git, then open the PR through the CLI. This is the direct analog of gh pr create:

# Push your feature branch the normal way
git push -u origin feature/new-endpoint

# Open the PR against main
atlassian-cli bitbucket --workspace myteam pr create api-service \
  --title "Add /v2/orders endpoint" \
  --source feature/new-endpoint \
  --destination main

List and inspect open PRs

The equivalents of gh pr list and gh pr view. Add --format json to any command to pipe it into jq:

# List open PRs (gh pr list)
atlassian-cli bb --workspace myteam pr list api-service --state OPEN --limit 5

# Inspect one PR by id (gh pr view 123)
atlassian-cli bb --workspace myteam pr get api-service 123

# Pull just the titles and authors with jq
atlassian-cli bb --workspace myteam pr list api-service --state OPEN \
  --format json | jq '.[] | {id, title}'

Review, comment, and merge

Approving, commenting, and merging round out the loop. The merge strategy accepts the same values Bitbucket exposes, such as merge_commit:

# Approve the PR (gh pr review --approve)
atlassian-cli bb --workspace myteam pr approve api-service 123

# Leave a review comment (gh pr comment)
atlassian-cli bb --workspace myteam pr comment api-service 123 \
  --text "Ship it once CI is green."

# Merge it (gh pr merge 123)
atlassian-cli bb --workspace myteam pr merge api-service 123 --strategy merge_commit

That is the entire gh-style loop, from open to merge, without opening Bitbucket in a browser once. For scheduled or CI-driven variants of this loop, the Bitbucket PR automation runbook has ready-to-adapt scripts.

Making It Feel Like gh: Aliases and a Wrapper

The friction with the raw commands is repetition: --workspace myteam and the repo slug on every line. gh avoids this by reading your git remote. You can get most of the way there with a tiny shell function that infers the slug from your current git repository and injects your workspace. Drop this in your .zshrc or .bashrc:

# gh-style Bitbucket wrapper: PR verb first, repo slug from the git remote
export BB_WORKSPACE="myteam"

bbpr() {
  # First argument is the PR verb (list, get, create, approve, merge, ...)
  local verb="$1"; shift
  # Extract the repo slug from the origin remote URL
  local slug
  slug=$(git remote get-url origin 2>/dev/null \
    | sed -E 's#.*[/:]([^/]+/)?([^/]+?)(\.git)?$#\2#')
  atlassian-cli bitbucket --workspace "$BB_WORKSPACE" pr "$verb" "$slug" "$@"
}

Because atlassian-cli emits clean JSON with --format json, the same tricks people build around gh port over directly. Pipe PR lists into fzf to pick one interactively, into jq to reshape output, or into a notification script in CI. The command reference lists every output format: table, json, csv, yaml, quiet, and markdown.

Where It Honestly Differs From gh

A gh-style workflow is not a gh clone, and it is worth being clear about the seams so you are not surprised:

• No pr checkout. atlassian-cli is an API client, not a git wrapper. It does not switch branches in your working copy the way gh pr checkout does. You keep using plain git fetch and git switch locally, and reach for atlassian-cli for the server-side actions.
• Explicit workspace and slug. Where gh reads your git remote, atlassian-cli wants --workspace and the repo slug. The wrapper above closes most of that gap.
• One binary, many products. In exchange, the same tool that opens your PR can transition the linked Jira issue or update a Confluence release note. gh is GitHub only; atlassian-cli spans the Atlassian stack.

None of these are dealbreakers for a terminal-first workflow. They are the honest cost of an API-driven tool, and for most Bitbucket users the trade lands firmly in the plus column.

Beyond PRs: Repos, Branches, Pipelines

The gh muscle memory extends past pull requests. Repository and branch management map cleanly, and Bitbucket Pipelines gives you something gh does not cover natively at all:

# Repos: list, inspect, create (gh repo list / view / create)
atlassian-cli bb --workspace myteam repo list --limit 10
atlassian-cli bb --workspace myteam repo get api-service
atlassian-cli bb --workspace myteam repo create newrepo --name "New Repo" --private

# Branches: list, create, protect
atlassian-cli bb --workspace myteam branch list api-service
atlassian-cli bb --workspace myteam branch create api-service feature/new --from main
atlassian-cli bb --workspace myteam branch protect api-service \
  --pattern "main" --kind restrict_merges --approvals 2

# Pipelines: trigger a build straight from the terminal
atlassian-cli bb --workspace myteam pipeline trigger api-service --ref-name main

For cleaning up stale branches and repos in bulk, atlassian-cli ships dry-run-safe bulk commands (for example bb --workspace myteam bulk delete-branches api-service --dry-run). See the branch cleanup runbook for the full pattern, and the Bitbucket CLI hub for the complete command surface.

FAQ

Related Resources