Using the Bitbucket API from the Command Line

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 Bitbucket API, task-first

You can drive the Bitbucket API from your terminal without writing a single curl request. Instead of building URLs, adding an Authorization header, following page links, and parsing JSON by hand, you run a named command like bitbucket pr list or bitbucket pipeline trigger and get the result back in the format you asked for.

This post is deliberately task-first. It is not a field-by-field reference of every Bitbucket REST endpoint. It walks through the operations engineers actually reach for -- listing repositories, opening and merging pull requests, kicking off pipelines, and auditing permissions -- and shows the exact atlassian-cli command for each. Every command below is copy-pasteable and verified against the command reference.

Under the hood, atlassian-cli talks to the same Bitbucket Cloud REST API you would hit manually. The difference is that pagination, authentication, rate-limit backoff, and output formatting are already handled. That means a one-liner in your shell replaces a small script, and the same command works interactively or inside CI.

Authenticate once

Bitbucket Cloud is authenticated separately from Jira and Confluence, so you pass the --bitbucket flag at login. There are two token flows. Pick the one that matches your account.

API token (Basic auth)

Create an Atlassian API token scoped to Bitbucket and use it with your account email. Good for your personal account:

# Log in with an API token (Basic auth)
atlassian-cli auth login \
  --profile work \
  --bitbucket \
  --email you@company.com \
  --token $BITBUCKET_TOKEN

Access token (Bearer auth)

Access tokens are scoped to a repository, project, or workspace, which makes them ideal for CI where you want the minimum permissions. Bearer auth does not need --email:

# Log in with a scoped access token (Bearer auth)
atlassian-cli auth login \
  --profile bb-ci \
  --bitbucket --bearer \
  --token $BITBUCKET_TOKEN

# Confirm the credentials resolve
atlassian-cli auth test --bitbucket --profile bb-ci
atlassian-cli bitbucket whoami --profile bb-ci

One convenience worth noting: bb is an alias for bitbucket, so atlassian-cli bb whoami and atlassian-cli bitbucket whoami are identical. Every example below works with either.

Reading repos, branches, and commits

Most Bitbucket API work starts with reading state. The workspace slug is supplied with --workspace (or saved into the profile at login), and the repository slug is a positional argument. Start with the repositories in a workspace:

# List repositories in a workspace
atlassian-cli bitbucket --workspace myteam repo list --limit 10

# Get one repository's details
atlassian-cli bitbucket --workspace myteam repo get api-service

Add --format json (or -f json) to any command and pipe it to jq. The CLI paginates the underlying API for you, so the JSON already contains the full result set -- you are not looking at just the first page:

# Every repo slug in the workspace, one per line
atlassian-cli bitbucket --workspace myteam repo list \
  --format json | jq '.[].slug'

# List branches, then recent commits on main
atlassian-cli bitbucket --workspace myteam branch list api-service
atlassian-cli bitbucket --workspace myteam commit list api-service --branch main

Commit inspection is useful for release notes and audits. You can diff a single commit or browse a path at a given ref:

# Show the diff for a commit
atlassian-cli bitbucket --workspace myteam commit diff api-service abc123

# Browse a directory at a ref
atlassian-cli bitbucket --workspace myteam commit browse api-service --commit main --path src/

Because output is just JSON, CSV, or YAML on request, these commands slot into whatever you already use. Pipe JSON into jq, write CSV straight to a file for a spreadsheet, or use --format quiet in CI to gate on an exit code.

Pull request tasks

Pull requests are where a CLI over the Bitbucket API pays off the most, because a review cycle is a sequence of small API calls. List the open PRs on a repo, then act on one by its numeric ID:

# Open pull requests on a repo
atlassian-cli bitbucket --workspace myteam pr list api-service --state OPEN --limit 5

# Full detail for PR #123
atlassian-cli bitbucket --workspace myteam pr get api-service 123

Opening a pull request is a single command. You supply the title, the source branch, and the destination branch:

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

Reviewing, commenting, approving, and merging are each one command. The merge strategy is explicit, so a script never guesses:

# Leave a review comment
atlassian-cli bitbucket --workspace myteam pr comment api-service 123 \
  --text "Looks good, one nit on error handling."

# Approve, then merge with a merge commit
atlassian-cli bitbucket --workspace myteam pr approve api-service 123
atlassian-cli bitbucket --workspace myteam pr merge api-service 123 --strategy merge_commit

Combine listing with --format json to build lightweight review dashboards. For example, count open PRs per repository, or find PRs that have been open a while, without touching the web UI:

# IDs of every open PR on a repo
atlassian-cli bitbucket --workspace myteam pr list api-service \
  --state OPEN --format json | jq '.[].id'

For a full merge-queue style script -- filtering PRs, checking approvals, and merging the ones that qualify -- see the Bitbucket PR automation runbook.

Triggering pipelines and CI

The Bitbucket API can start a Pipelines run, which means your CI is scriptable from anywhere a terminal reaches. Trigger a run on a branch, or run a named custom pipeline defined in bitbucket-pipelines.yml:

# Trigger the default pipeline on main
atlassian-cli bitbucket --workspace myteam pipeline trigger api-service --ref-name main

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

List recent runs to check status, and stop a run by its UUID if you started the wrong thing:

# See recent pipeline runs
atlassian-cli bitbucket --workspace myteam pipeline list api-service

# Stop a running pipeline
atlassian-cli bitbucket --workspace myteam pipeline stop api-service {uuid}

This is handy for chaining. A deploy script can trigger a pipeline, and a scheduled job can trigger a nightly custom pipeline against a fixed ref. Because the CLI returns structured output, you can capture the run identifier from JSON and follow up programmatically.

Permissions, webhooks, and audit

Administrative tasks map cleanly to commands too. Review who has access to a repository, grant a permission, or manage the webhooks and SSH keys that wire Bitbucket into the rest of your toolchain:

# Who can access this repo, and at what level
atlassian-cli bitbucket --workspace myteam permission list api-service

# Grant write access to a user
atlassian-cli bitbucket --workspace myteam permission grant api-service \
  --user-uuid {uuid} --permission write

# Manage webhooks
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

Branch protection is a common governance requirement. Restrict merges on main and require approvals in one command:

# Require 2 approvals and restrict merges on main
atlassian-cli bitbucket --workspace myteam branch protect api-service \
  --pattern "main" --kind restrict_merges --approvals 2

# Review existing restrictions
atlassian-cli bitbucket --workspace myteam branch restrictions api-service

For workspace-wide housekeeping there are bulk commands, each with a --dry-run flag so you can preview the blast radius before anything changes:

# Preview which repos would be archived (untouched by --dry-run)
atlassian-cli bitbucket --workspace myteam bulk archive-repos --days 180 --dry-run

# Preview stale branch cleanup, keeping one branch
atlassian-cli bitbucket --workspace myteam bulk delete-branches api-service \
  --exclude feature/keep --dry-run

To turn permission and branch data into a shareable inventory, the repository audit runbook walks through exporting it across a whole workspace.

CLI vs raw REST

There is nothing wrong with hitting the Bitbucket REST API directly with curl. For a one-off call against an endpoint the CLI does not wrap, it is the right tool. The trade-off shows up the moment a task repeats or needs pagination, auth handling, and parsing. Here is the same set of jobs, both ways:

A useful rule of thumb: reach for the CLI when a task is repeatable, needs to run in CI, or would otherwise become a small script. Reach for raw REST when you need an endpoint the CLI does not cover yet. The two coexist -- you can pipe the CLI's JSON output into the same jq filters you already wrote for curl. If you want the endpoint-level details behind these commands, the Bitbucket REST API guide covers the raw HTTP surface, and the Bitbucket CLI commands reference lists every subcommand.

FAQ

Related Resources