Automate pull requests, pipelines, branches, and repository management from your terminal. Bearer and Basic auth supported.
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.
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 and workspaces.
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. Filter by project or last update. |
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.
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
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.