Automate pull requests, pipelines, branches, and repository management from your terminal. Bearer and Basic auth supported.
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 CLI (atlassian-cli bitbucket, aliased as bb) is a command-line tool for Bitbucket Cloud. It covers the full repo + PR workflow, list/create/update repositories, manage branches and branch protection, open/approve/merge pull requests, trigger pipelines, rotate SSH keys, administer webhooks, and browse commits. Output formats (JSON, CSV, YAML, table) make it drop-in for CI pipelines and audits.
It ships as part of atlassian-cli, one open-source Rust binary that also handles Jira, Confluence, and Jira Service Management. Install via Homebrew or Cargo, then authenticate with either a Bitbucket API token (Basic auth, personal account) or a workspace / repository access token (Bearer auth, CI-scoped). See the auth guide for both flows.
If you already reach for GitHub's gh CLI, this gives Bitbucket Cloud the same terminal-native flow: open a pull request, approve and merge it, trigger a pipeline, or spin up a repository without leaving your shell or opening a browser tab. The Bitbucket CLI guide walks through setup and the everyday commands end to end.
main across all repos, audit current branch restrictions. See the branch cleanup runbook.Full control over your Bitbucket Cloud workspace
List, create, update, and delete repositories. Bulk archive stale repos with dry-run. Full CRUD for projects, plus workspace listing.
Create, approve, merge, and decline PRs. Add reviewers, post comments, and choose merge strategies (squash, merge commit, fast-forward).
List, trigger, and stop pipelines. View build logs. Trigger specific branches or custom pipelines by ref name.
Set branch restrictions, require minimum approvals, restrict merge strategies. List and manage branch protection rules.
Scoped API tokens with Bearer auth or classic Basic auth. Profile-specific Bitbucket tokens. Environment variable fallback chain.
Create, list, and delete webhooks. Subscribe to repo:push, pullrequest:created, and other events. Manage SSH deploy keys.
Production-ready scripts for Bitbucket automation
# List open pull requests as JSON
atlassian-cli bitbucket --workspace myteam \
pr list api-service \
--state OPEN --format json
# Approve and merge with squash strategy
atlassian-cli bitbucket --workspace myteam \
pr approve api-service 42
atlassian-cli bitbucket --workspace myteam \
pr merge api-service 42 \
--strategy merge_commit
# Create a new pull request
atlassian-cli bitbucket --workspace myteam \
pr create api-service \
--title "Add feature" \
--source feature/new \
--destination main# List all branches in a repo
atlassian-cli bitbucket --workspace myteam \
branch list api-service
# Delete a merged feature branch
atlassian-cli bitbucket --workspace myteam \
branch delete api-service feature/old --force
# Bulk delete merged branches (dry-run first)
atlassian-cli bitbucket --workspace myteam \
bulk delete-branches api-service \
--exclude feature/keep --dry-run
# Protect main branch with 2 approvals
atlassian-cli bitbucket --workspace myteam \
branch protect api-service \
--pattern "main" \
--kind restrict_merges --approvals 2# List all repos in a workspace
atlassian-cli bitbucket --workspace myteam \
repo list --format json
# Get repo details
atlassian-cli bitbucket --workspace myteam \
repo get api-service
# List repo permissions
atlassian-cli bitbucket --workspace myteam \
permission list api-service
# Bulk archive repos inactive for 180 days
atlassian-cli bitbucket --workspace myteam \
bulk archive-repos --days 180 --dry-run
# Check current user identity
atlassian-cli bitbucket whoamiInstall and authenticate in under a minute
# Install via Homebrew
brew install omar16100/atlassian-cli/atlassian-cli
# Basic auth (email + API token)
atlassian-cli auth login \
--profile bb-work \
--base-url https://your-domain.atlassian.net \
--email you@company.com
# Bearer token auth (scoped Bitbucket token)
atlassian-cli auth login \
--profile bb-ci \
--bitbucket --bearer \
--workspace myteam
# Verify authentication
atlassian-cli bitbucket whoami --profile bb-ci
# List repos in your workspace
atlassian-cli bitbucket --workspace myteam \
repo list --limit 10Each group links to the full command reference.
| Group | Covers |
|---|---|
bb repo |
List, get, create, update, delete repositories. List accepts --limit. |
bb branch |
Branch CRUD plus branch protection (approvals, merge restrictions, required checks). |
bb pr |
List, get, create, approve, merge, comment on pull requests. Machine-readable output for CI gating. |
bb pipeline |
Trigger, list, stop pipelines. Useful for cross-service orchestration. |
bb webhook / bb ssh-key |
Webhook management and deploy-key lifecycle. |
bb workspace / bb project |
Workspace and project-level inventory and admin. |
bb permission / bb commit |
Repo permission admin and commit/diff browsing. |
bb bulk archive-repos / delete-branches |
Bulk operations with dry-run previews and filters (by age, by pattern). |
Full flag list and output schemas are in the command reference. For auth (bearer vs. basic), see the Bitbucket authentication section.
The handful you reach for daily. Every flag is verified against the command reference.
Prefix each with atlassian-cli (bb is the built-in alias for bitbucket). Where a repository is involved, add --workspace <name>, for example atlassian-cli bb --workspace myteam pr list api-service.
| Command | What it does |
|---|---|
bb repo list |
List every repository in the workspace. |
bb repo get <repo> |
Show a single repository's details. |
bb pr list <repo> --state OPEN |
List open pull requests (add --format json for CI). |
bb pr create <repo> --title … --source … --destination … |
Open a pull request between two branches. |
bb pr approve <repo> <id> |
Approve a pull request. |
bb pr merge <repo> <id> --strategy merge_commit |
Merge a pull request with a chosen strategy. |
bb branch protect <repo> --pattern "main" --kind restrict_merges --approvals 2 |
Require approvals before merging into a branch. |
bb pipeline trigger <repo> --ref-name main |
Start a pipeline on a branch (add --custom-pipeline <name> for a named pipeline). |
bb bulk delete-branches <repo> --dry-run |
Preview a stale-branch cleanup before deleting. |
bb whoami |
Show the authenticated Bitbucket account. |
Map a job to the exact command.
bb --workspace myteam pr create api-service --title "Ship it" --source feature/x --destination main. Full example in the PR automation runbook.bb --workspace myteam pr approve api-service 42 then bb --workspace myteam pr merge api-service 42 --strategy merge_commit.bb --workspace myteam pipeline trigger api-service --ref-name main --custom-pipeline <name>.main, bb --workspace myteam branch protect api-service --pattern "main" --kind restrict_merges --approvals 2. See the branch cleanup runbook.bb --workspace myteam bulk delete-branches api-service --exclude feature/keep --dry-run.bb --workspace myteam permission list api-service. The repo audit runbook scripts a full workspace sweep.bb whoami --profile bb-ci.Basic auth uses an Atlassian API token scoped to Bitbucket, it authenticates as your account and needs your email. Good for personal day-to-day work. Bearer auth uses a repository/workspace/project access token, it's scoped to a specific resource and doesn't need an email, so it's the right choice for CI. App passwords are deprecated (creation ended Sep 9, 2025; existing app passwords stop working Jun 9, 2026). Full setup in the auth guide.
bb instead of bitbucket?Yes. bb is the built-in visible alias. atlassian-cli bb pr list myteam api-service is identical to atlassian-cli bitbucket pr list myteam api-service.
Create a workspace access token with pullrequest:write scope, export it as BITBUCKET_TOKEN in your pipeline, then run atlassian-cli auth login --profile ci --bitbucket --bearer --token $BITBUCKET_TOKEN once in a setup step. Subsequent bb pr approve and bb pr merge calls use that profile. The PR automation runbook has a full example.
Yes. atlassian-cli bb --workspace myteam bulk delete-branches api-service --exclude feature/keep --dry-run prints the list of branches that would go, filtered by your exclusion patterns. Remove --dry-run once it looks right. The branch cleanup runbook walks through a production version.
Current focus is Bitbucket Cloud. Bitbucket Data Center has a different REST API surface, check the GitHub repo for any DC-specific work.
Yes, MIT licensed. Bitbucket Cloud itself has a free tier for small teams; the CLI works with any plan.
Guides, runbooks, and more
Step-by-step walkthrough: install, authenticate, and run your first PR, pipeline, and branch commands.
Tutorials, release notes, and automation tips for Bitbucket and the full Atlassian stack.
Complete command reference for all Bitbucket subcommands, flags, and output formats.
Production-ready shell scripts for PR automation, branch cleanup, and repo audits.
Automating Bitbucket from the command line
atlassian-cli is a Bitbucket CLI for pull requests, pipelines, branches, repositories and permissions. After authenticating, run commands like atlassian-cli bitbucket --workspace myteam pr list api-service. See the full Bitbucket command reference.
Yes, including named custom pipelines: atlassian-cli bitbucket --workspace myteam pipeline trigger api-service --ref-name main --custom-pipeline <name>. Custom pipeline triggers landed in version 0.4.
No. atlassian-cli is an independent, open-source tool and is not affiliated with, endorsed by, or maintained by Atlassian. Atlassian ships its own separate official CLI (acli).
Yes. atlassian-cli is free and open source under the MIT License. Get it on the install page or GitHub.