Bitbucket CLI: Automate PRs, Pipelines & Repos

Why Automate Bitbucket from CLI?

Bitbucket's web UI works fine for reviewing a single pull request. It doesn't work well when you need to audit permissions across 200 repositories, trigger pipelines from a CI script, or clean up stale branches across your entire workspace.

A Bitbucket CLI turns these multi-click workflows into single commands. With atlassian-cli, you get full Bitbucket coverage in the same binary that handles Jira, Confluence, and JSM. That means one tool, one config, one authentication flow for your entire Atlassian stack.

Common use cases for a Bitbucket command line tool:

• PR automation. Create, approve, and merge pull requests from scripts. Chain PR creation with Jira issue transitions in a single pipeline.
• Pipeline triggers. Kick off Bitbucket Pipelines from a CI/CD system, watch for completion, and act on the result. No browser needed.
• Repository audits. List all repos in a workspace, check permissions, identify stale repositories, and enforce naming conventions programmatically.
• Branch hygiene. Protect critical branches, delete merged branches in bulk, and enforce approval requirements across repositories.

atlassian-cli supports the bb shorthand alias for all Bitbucket commands. Both atlassian-cli bitbucket and atlassian-cli bb work identically.

Authentication

Bitbucket requires a separate scoped API token from Jira and Confluence. Atlassian deprecated Bitbucket app passwords in favor of scoped API tokens that must be created specifically for Bitbucket with explicit permission scopes.

Basic auth (API token)

Create a scoped Bitbucket token at id.atlassian.com. Click "Create API token with scopes", select Bitbucket, and add the required scopes (read:repository:bitbucket, write:repository:bitbucket, read:pullrequest:bitbucket).

# Set the Bitbucket token (profile-specific)
export ATLASSIAN_CLI_BITBUCKET_TOKEN_WORK=your-bitbucket-scoped-token

# Or use the generic fallback
export BITBUCKET_TOKEN=your-bitbucket-scoped-token

# Verify authentication
atlassian-cli bitbucket whoami

Bearer token auth

For CI/CD pipelines and service accounts, Bearer token authentication avoids exposing email addresses. Configure a Bearer profile:

# Add a Bitbucket Bearer token profile
atlassian-cli auth login \
  --profile bb-ci \
  --bitbucket --bearer \
  --workspace myteam

# Test the connection
atlassian-cli auth test --bitbucket --profile bb-ci

# Use the profile in commands
atlassian-cli bb --workspace myteam repo list --profile bb-ci

The CLI checks environment variables in priority order: ATLASSIAN_CLI_BITBUCKET_TOKEN_{PROFILE} first, then ATLASSIAN_BITBUCKET_TOKEN, then BITBUCKET_TOKEN, and finally falls back to the regular ATLASSIAN_CLI_TOKEN_{PROFILE} token.

Repository Management

Repository operations cover the full lifecycle: listing, creating, inspecting, updating, and deleting repos within a workspace.

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

# Get details for a specific repo
atlassian-cli bitbucket --workspace myteam repo get api-service

# Create a new private repository
atlassian-cli bitbucket --workspace myteam repo create newrepo \
  --name "New Repo" --private

# Update a repo description
atlassian-cli bitbucket --workspace myteam repo update api-service \
  --description "Updated description"

# Delete a repo (requires --force)
atlassian-cli bitbucket --workspace myteam repo delete oldrepo --force

Permissions

Audit and manage who has access to your repositories:

# List permissions for a repository
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

Workspaces and projects

# List workspaces you have access to
atlassian-cli bitbucket workspace list --limit 10

# Get workspace details
atlassian-cli bitbucket workspace get myteam

# List projects in a workspace
atlassian-cli bitbucket --workspace myteam project list

# Create a new project
atlassian-cli bitbucket --workspace myteam project create PROJ \
  --name "My Project" --private

Pull Request Workflows

Pull request commands cover the entire PR lifecycle, from creation through review to merge. This is where the Bitbucket CLI saves the most time in daily development workflows.

Create and list PRs

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

# List open pull requests
atlassian-cli bitbucket --workspace myteam pr list api-service \
  --state OPEN --limit 5

# Get PR details
atlassian-cli bitbucket --workspace myteam pr get api-service 123

Review and merge

# Approve a PR
atlassian-cli bitbucket --workspace myteam pr approve api-service 123

# Merge with squash strategy
atlassian-cli bitbucket --workspace myteam pr merge api-service 123 \
  --strategy squash

# Decline a PR
atlassian-cli bitbucket --workspace myteam pr decline api-service 123

# Add a comment to a PR
atlassian-cli bitbucket --workspace myteam pr comment api-service 123 \
  --text "Looks good!"

# View PR comments
atlassian-cli bitbucket --workspace myteam pr comments api-service 123

The merge --strategy flag supports merge_commit, squash, and fast_forward, matching Bitbucket's merge options. Combined with the pr approve command, you can build a complete review-and-merge workflow in a shell script.

Pipeline Operations

Trigger, monitor, and manage Bitbucket Pipelines directly from the terminal. This is essential for CI/CD automation where you need to programmatically start builds and react to their outcomes.

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

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

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

Pipeline commands pair well with PR workflows. For example, you can trigger a pipeline after creating a PR, wait for it to complete, and then auto-merge if the build passes -- all from a single script.

Webhooks and SSH keys

Automate webhook and deploy key management for repository integrations:

# List webhooks
atlassian-cli bitbucket --workspace myteam webhook list api-service

# Create a webhook for push events
atlassian-cli bitbucket --workspace myteam webhook create api-service \
  --url https://example.com/hook \
  --events repo:push

# Manage SSH deploy keys
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 ..."

Branch Management

Branch commands handle listing, creation, deletion, and protection rules. Branch protection is particularly important for enforcing code review policies across repositories.

List and create branches

# List branches in a repository
atlassian-cli bitbucket --workspace myteam branch list api-service

# Create a feature branch from main
atlassian-cli bitbucket --workspace myteam branch create api-service \
  feature/new --from main

# Delete a merged branch
atlassian-cli bitbucket --workspace myteam branch delete api-service \
  feature/old --force

Branch protection

Enforce review requirements and restrict who can push to critical branches:

# Protect the main branch with 2 required approvals
atlassian-cli bitbucket --workspace myteam branch protect api-service \
  --pattern "main" \
  --kind restrict_merges \
  --approvals 2

# View branch restrictions
atlassian-cli bitbucket --workspace myteam branch restrictions api-service

Bulk branch cleanup

Remove stale branches across repositories. The --dry-run flag previews deletions before executing:

# Preview: list branches that would be deleted
atlassian-cli bitbucket --workspace myteam bulk delete-branches api-service \
  --exclude feature/keep \
  --dry-run

# Archive stale repos (no commits in 180 days)
atlassian-cli bitbucket --workspace myteam bulk archive-repos \
  --days 180 \
  --dry-run

Real-World Workflows

CI/CD pipeline automation

Use Bitbucket CLI commands in GitHub Actions, GitLab CI, or any CI runner to connect your build pipeline with Bitbucket operations:

#!/bin/bash
# Automated PR workflow: create, trigger pipeline, merge on success
set -euo pipefail

WORKSPACE="myteam"
REPO="api-service"
BRANCH="feature/automated-update"

# Create the pull request
PR_OUTPUT=$(atlassian-cli bb --workspace "$WORKSPACE" pr create "$REPO" \
  --title "Automated dependency update" \
  --source "$BRANCH" \
  --destination main \
  --format json)

# Trigger a pipeline on the branch
atlassian-cli bb --workspace "$WORKSPACE" pipeline trigger "$REPO" \
  --ref-name "$BRANCH"

echo "PR created and pipeline triggered."

Repository audit script

Audit all repositories in a workspace for permissions, branch protection, and activity:

#!/bin/bash
# Audit all repos: check permissions and branch protection
set -euo pipefail

WORKSPACE="myteam"

# List all repos as JSON
REPOS=$(atlassian-cli bb --workspace "$WORKSPACE" repo list \
  --format json --limit 100)

# For each repo, check branch restrictions
echo "$REPOS" | jq -r '.[].slug' | while read -r repo; do
  echo "--- $repo ---"

  # Check permissions
  atlassian-cli bb --workspace "$WORKSPACE" permission list "$repo"

  # Check branch protection
  atlassian-cli bb --workspace "$WORKSPACE" branch restrictions "$repo"

  echo ""
done

Commit and diff operations

Inspect commit history and diffs without cloning the repository:

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

# View a commit diff
atlassian-cli bitbucket --workspace myteam commit diff api-service abc123

# Browse files at a specific commit
atlassian-cli bitbucket --workspace myteam commit browse api-service \
  --commit main --path src/

FAQ

Related Resources