Bitbucket CLI Commands Reference

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.

Bitbucket CLI Commands at a Glance

This page is a reference table of the Bitbucket CLI commands exposed by atlassian-cli, grouped by what you manage: repositories, pull requests, pipelines, and permissions. Every command below is copy-paste ready. Keep it open in a tab while you script Bitbucket from the terminal.

Two things apply to every command. First, the base binary is atlassian-cli and the group is bitbucket, which has a shorter alias, bb. Both are interchangeable. Second, the --workspace flag goes immediately after bitbucket and before the subcommand, so it scopes the whole call to one workspace:

# bb is an alias for bitbucket -- these two lines are identical
atlassian-cli bitbucket --workspace myteam repo list
atlassian-cli bb --workspace myteam repo list

How this differs from Atlassian's own CLI: 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 spanning Jira, Confluence, Bitbucket, and Jira Service Management with one consistent flag syntax. If you are comparing it to GitHub's tooling, the companion post a Bitbucket CLI that feels like gh maps the mental model across.

The tables that follow use myteam as the workspace and api-service as the repository slug. Swap in your own values. For the exhaustive, always-current listing see the command reference, and the Bitbucket CLI hub for setup.

Repository Commands

Repository commands cover the full lifecycle: list, inspect, create, update, and delete. The repository slug is a positional argument after the verb.

# List, then inspect a repository
atlassian-cli bitbucket --workspace myteam repo list --limit 10
atlassian-cli bitbucket --workspace myteam repo get api-service

# Create a private repo, update its description, delete an old one
atlassian-cli bitbucket --workspace myteam repo create newrepo --name "New Repo" --private
atlassian-cli bitbucket --workspace myteam repo update api-service --description "Updated description"
atlassian-cli bitbucket --workspace myteam repo delete oldrepo --force

To audit every repository in a workspace at once, for example flagging unused repos, pair repo list --format json with the repo audit runbook.

Pull Request Commands

Pull request commands take the repository slug first, then the PR ID where relevant. This is the busiest group in day-to-day work: opening, reviewing, and merging changes without leaving the terminal.

# Open a pull request from a feature branch into main
atlassian-cli bitbucket --workspace myteam pr create api-service \
  --title "Add feature" \
  --source feature/new \
  --destination main

# Review flow: list open PRs, read one, comment, approve, merge
atlassian-cli bitbucket --workspace myteam pr list api-service --state OPEN --limit 5
atlassian-cli bitbucket --workspace myteam pr get api-service 123
atlassian-cli bitbucket --workspace myteam pr comment api-service 123 --text "Looks good!"
atlassian-cli bitbucket --workspace myteam pr approve api-service 123
atlassian-cli bitbucket --workspace myteam pr merge api-service 123 --strategy merge_commit

Because each verb returns structured output, you can chain these into a review bot or a nightly cleanup. The PR automation runbook shows how to auto-comment on stale pull requests and merge approved ones on a schedule.

Pipeline Commands

Pipeline commands drive Bitbucket Pipelines: list runs, trigger a build on a branch, run a named custom pipeline from bitbucket-pipelines.yml, and stop a run in progress.

# List runs, then trigger the default pipeline on main
atlassian-cli bitbucket --workspace myteam pipeline list api-service
atlassian-cli bitbucket --workspace myteam pipeline trigger api-service --ref-name main

# Trigger a named custom pipeline defined in bitbucket-pipelines.yml
atlassian-cli bitbucket --workspace myteam pipeline trigger api-service \
  --ref-name main --custom-pipeline s3-access-test

# Stop a run that is already going
atlassian-cli bitbucket --workspace myteam pipeline stop api-service {uuid}

Custom pipelines are handy for one-off jobs like a smoke test or a manual deploy step. If you would rather call the Pipelines REST endpoints directly, the Bitbucket API from the CLI post covers raw request patterns.

Permission & Branch Protection Commands

Permission commands govern who can access a repository and what happens on protected branches. Grants take a user UUID and a permission level; branch protection sets a restriction rule against a branch pattern.

# See who has access, then grant write to a user
atlassian-cli bitbucket --workspace myteam permission list api-service
atlassian-cli bitbucket --workspace myteam permission grant api-service \
  --user-uuid {uuid} --permission write

# Require two approvals before a merge to main
atlassian-cli bitbucket --workspace myteam branch protect api-service \
  --pattern "main" --kind restrict_merges --approvals 2
atlassian-cli bitbucket --workspace myteam branch restrictions api-service

The --permission level accepts standard Bitbucket values such as read, write, and admin. The --kind flag on branch protect takes a restriction kind like restrict_merges. Because permissions map to your workspace's own configuration, dry-run any bulk grant before applying it.

Branches, Webhooks & Bulk

Beyond the four core groups, three more sets round out day-to-day repository administration: branch management, webhooks and SSH keys, and bulk operations across many repositories.

Branches

atlassian-cli bitbucket --workspace myteam branch list api-service
atlassian-cli bitbucket --workspace myteam branch create api-service feature/new --from main
atlassian-cli bitbucket --workspace myteam branch delete api-service feature/old --force

Webhooks & SSH keys

atlassian-cli bitbucket --workspace myteam webhook list api-service
atlassian-cli bitbucket --workspace myteam webhook create api-service \
  --url https://example.com/hook --events repo:push
atlassian-cli bitbucket --workspace myteam ssh-key list api-service
atlassian-cli bitbucket --workspace myteam ssh-key add api-service --label deploy --key "ssh-rsa ..."

Bulk operations

Bulk commands apply an action across many repositories or branches. Like all destructive operations in the CLI, they support --dry-run so you preview the blast radius first.

# Preview archiving repos untouched for 180 days
atlassian-cli bitbucket --workspace myteam bulk archive-repos --days 180 --dry-run

# Preview deleting merged branches, keeping one you name
atlassian-cli bitbucket --workspace myteam bulk delete-branches api-service \
  --exclude feature/keep --dry-run

For a repeatable end-of-sprint cleanup that combines these safely, follow the branch cleanup runbook.

Global Flags & Output Formats

Every Bitbucket command accepts the same global flags. These are what make the CLI scriptable: pick a machine format, target a profile, and debug when something breaks.

# JSON for scripting -- pipe to jq
atlassian-cli bitbucket --workspace myteam pr list api-service --format json | jq '.[].id'

# Target a non-default profile
atlassian-cli bitbucket --workspace myteam repo list --profile work

# CSV for a spreadsheet
atlassian-cli bitbucket --workspace myteam repo list --format csv

Set up profiles once with authentication, then reuse them across every workspace. Combining --format json with jq is the foundation of most Bitbucket automation you will write.

FAQ

Related Resources