Atlassian Bitbucket Cloud by @altf1be

Full CRUD on repos, PRs, pipelines, issues, snippets, workspaces, branches, deployments, and more via Bitbucket REST API 2.0.

Setup

1. Create an API Token at https://id.atlassian.com/manage-profile/security/api-tokens (select the scopes you need).
2. Set environment variables (or create .env in {baseDir}):

# Required
BITBUCKET_EMAIL=you@example.com
BITBUCKET_API_TOKEN=your-api-token

# Optional
BITBUCKET_WORKSPACE=your-default-workspace
BITBUCKET_MAX_RESULTS=50

# Legacy (supported until June 9, 2026)
# BITBUCKET_USERNAME=your-username
# BITBUCKET_APP_PASSWORD=your-app-password

3. Install dependencies: cd {baseDir} && npm install

Common Options

Most commands accept these shared flags:

Commands

1. Repositories (26 commands)

CRUD on repositories, forks, watchers, webhooks, override settings, and permissions.

# List repos in a workspace
bitbucket repo-list -w myworkspace

# Get repo details
bitbucket repo-get -w myworkspace -r my-repo

# Create a new private repo
bitbucket repo-create -w myworkspace -r new-repo --is-private true --scm git

# Fork a repo
bitbucket repo-fork-create -w myworkspace -r upstream-repo --data '{"name":"my-fork"}'

# Create a webhook
bitbucket hook-create -w myworkspace -r my-repo --url https://example.com/hook --events repo:push

# Delete a repo (requires --confirm)
bitbucket repo-delete -w myworkspace -r old-repo --confirm

2. Pull Requests (36 commands)

Full lifecycle management of pull requests: create, review, approve, merge, comment, tasks, and default reviewers.

# List open PRs
bitbucket pr-list -w myworkspace -r my-repo -q 'state="OPEN"'

# Create a PR
bitbucket pr-create -w myworkspace -r my-repo --title "Add feature" \
  --source feature-branch --destination main

# Approve a PR
bitbucket pr-approve -w myworkspace -r my-repo --pr-id 42

# Merge a PR
bitbucket pr-merge -w myworkspace -r my-repo --pr-id 42 --merge-strategy squash

# Add a comment
bitbucket pr-comment-create -w myworkspace -r my-repo --pr-id 42 \
  --body "Looks good to me!"

# Create a task on a PR
bitbucket pr-task-create -w myworkspace -r my-repo --pr-id 42 \
  --data '{"content":{"raw":"Fix the typo on line 10"}}'

# Find PRs for a commit
bitbucket pr-for-commit -w myworkspace -r my-repo --commit abc123

3. Commits (16 commands)

Read commit details, approve/unapprove commits, manage commit comments, list diffs and patches.

# Get commit details
bitbucket commit-get -w myworkspace -r my-repo --commit abc123def

# List recent commits
bitbucket commit-list -w myworkspace -r my-repo --pagelen 10

# Get diff between two refs
bitbucket diff -w myworkspace -r my-repo --spec "main..feature-branch"

# Approve a commit
bitbucket commit-approve -w myworkspace -r my-repo --commit abc123def

# Comment on a commit
bitbucket commit-comment-create -w myworkspace -r my-repo --commit abc123def \
  --body "This needs a test."

4. Branches & Tags (9 commands)

List, create, get, and delete branches and tags.

# List branches
bitbucket branch-list -w myworkspace -r my-repo

# Create a branch
bitbucket branch-create -w myworkspace -r my-repo --name feature/new \
  --target main

# Create a tag
bitbucket tag-create -w myworkspace -r my-repo --name v1.0.0 --target main

# Delete a branch (requires --confirm)
bitbucket branch-delete -w myworkspace -r my-repo --name old-branch --confirm

5. Branch Restrictions (5 commands)

Manage branch permission restrictions (push, merge, delete controls).

# List restrictions
bitbucket restriction-list -w myworkspace -r my-repo

# Prevent force-push to main
bitbucket restriction-create -w myworkspace -r my-repo \
  --data '{"kind":"force","pattern":"main"}'

# Delete a restriction (requires --confirm)
bitbucket restriction-delete -w myworkspace -r my-repo --id 123 --confirm

6. Branching Model (7 commands)

Get and configure the branching model (Git Flow style) at the repo and project level.

# Get effective branching model
bitbucket branching-model-effective -w myworkspace -r my-repo

# Update branching model settings
bitbucket branching-model-settings-update -w myworkspace -r my-repo \
  --data '{"development":{"name":"develop"},"production":{"name":"main"}}'

7. Pipelines (68 commands)

Full pipeline lifecycle: run, stop, inspect steps/logs, manage variables, schedules, SSH keys, known hosts, caches, runners, OIDC, and workspace/team/user-level pipeline variables.

# Trigger a pipeline on main
bitbucket pipeline-create -w myworkspace -r my-repo \
  --data '{"target":{"ref_type":"branch","type":"pipeline_ref_target","ref_name":"main"}}'

# List recent pipelines
bitbucket pipeline-list -w myworkspace -r my-repo --pagelen 5

# Get step logs
bitbucket pipeline-step-log -w myworkspace -r my-repo \
  --pipeline-uuid {uuid} --step-uuid {uuid}

# Stop a running pipeline
bitbucket pipeline-stop -w myworkspace -r my-repo --pipeline-uuid {uuid}

# Create a repo pipeline variable (secured)
bitbucket pipeline-var-create -w myworkspace -r my-repo \
  --key API_KEY --value secret123 --secured true

# Create a workspace-level variable
bitbucket ws-pipeline-var-create -w myworkspace \
  --key DEPLOY_TOKEN --value tok_abc --secured true

# Schedule a pipeline
bitbucket pipeline-schedule-create -w myworkspace -r my-repo \
  --data '{"cron_pattern":"0 0 * * *","target":{"ref_type":"branch","ref_name":"main"}}'

8. Deployments (16 commands)

Manage deploy keys and deployment environments.

# List deployment environments
bitbucket environment-list -w myworkspace -r my-repo

# Create a staging environment
bitbucket environment-create -w myworkspace -r my-repo \
  --data '{"name":"Staging","environment_type":{"name":"Staging"}}'

# Add a deploy key
bitbucket deploy-key-create -w myworkspace -r my-repo \
  --key "ssh-rsa AAAA..." --label "CI deploy key"

# Delete an environment (requires --confirm)
bitbucket environment-delete -w myworkspace -r my-repo \
  --environment-uuid {uuid} --confirm

9. Commit Statuses (4 commands)

Create and manage build statuses on commits.

# Report a build status
bitbucket status-create -w myworkspace -r my-repo --commit abc123 \
  --state SUCCESSFUL --key build-42 --url https://ci.example.com/42

# List statuses on a commit
bitbucket status-list -w myworkspace -r my-repo --commit abc123

10. Issue Tracker (33 commands)

Full issue management: CRUD, comments, attachments, changes, voting, watching, import/export, components, milestones, and versions.

# List open bugs
bitbucket issue-list -w myworkspace -r my-repo -q 'kind="bug" AND state="open"'

# Create an issue
bitbucket issue-create -w myworkspace -r my-repo \
  --title "Login broken" --kind bug --priority critical

# Comment on an issue
bitbucket issue-comment-create -w myworkspace -r my-repo --issue-id 7 \
  --body "Reproduced on Chrome 120."

# Upload an attachment
bitbucket issue-attachment-upload -w myworkspace -r my-repo --issue-id 7 \
  --file ./screenshot.png

# Export all issues
bitbucket issue-export -w myworkspace -r my-repo

# List milestones
bitbucket milestone-list -w myworkspace -r my-repo

11. Snippets (25 commands)

Create and manage code snippets, their revisions, files, diffs, comments, commits, and watchers.

# List your snippets
bitbucket snippet-list

# Create a snippet
bitbucket snippet-create --title "Bash helper" --is-private true \
  --file ./helper.sh

# List workspace snippets
bitbucket snippet-ws-list -w myworkspace

# Get a specific file from a snippet
bitbucket snippet-file -w myworkspace --snippet-id abc123 --filename helper.sh

# Delete a snippet (requires --confirm)
bitbucket snippet-delete -w myworkspace --snippet-id abc123 --confirm

12. Workspaces (17 commands)

List workspaces, manage hooks, members, permissions, and list user PRs.

# List workspaces
bitbucket workspace-list

# Get workspace details
bitbucket workspace-get -w myworkspace

# List workspace members
bitbucket workspace-member-list -w myworkspace

# List my open PRs across the workspace
bitbucket workspace-user-prs -w myworkspace -q 'state="OPEN"'

# Create a workspace webhook
bitbucket workspace-hook-create -w myworkspace \
  --url https://example.com/hook --events repo:push,pullrequest:created

13. Projects (16 commands)

CRUD on projects, default reviewers, and group/user permissions at the project level.

# Create a project
bitbucket project-create -w myworkspace --key PROJ --name "My Project"

# List project default reviewers
bitbucket project-default-reviewer-list -w myworkspace --project-key PROJ

# Add a default reviewer to a project
bitbucket project-default-reviewer-add -w myworkspace --project-key PROJ \
  --user-uuid {uuid}

# Delete a project (requires --confirm)
bitbucket project-delete -w myworkspace --project-key PROJ --confirm

14. Users (4 commands)

Get current user info, list emails, and look up other users.

# Get current user info
bitbucket user-get-current

# List your emails
bitbucket user-emails

# Look up another user
bitbucket user-get --user-uuid {uuid}

15. SSH Keys (5 commands)

Manage SSH keys on your Bitbucket account.

# List SSH keys
bitbucket ssh-key-list

# Add an SSH key
bitbucket ssh-key-create --key "ssh-ed25519 AAAA..." --label "work laptop"

# Delete an SSH key (requires --confirm)
bitbucket ssh-key-delete --key-id 123 --confirm

16. GPG Keys (4 commands)

Manage GPG keys for commit signature verification.

# List GPG keys
bitbucket gpg-key-list

# Add a GPG key
bitbucket gpg-key-create --key "-----BEGIN PGP PUBLIC KEY BLOCK-----..."

# Delete a GPG key (requires --confirm)
bitbucket gpg-key-delete --key-id abc123 --confirm

17. Source / File Browsing (4 commands)

Browse repository source files and commit new files.

# List files at root
bitbucket src-root -w myworkspace -r my-repo

# Get file contents
bitbucket src-get -w myworkspace -r my-repo --path src/index.js

# Get file history
bitbucket src-history -w myworkspace -r my-repo --path README.md

# Create/update a file
bitbucket src-create -w myworkspace -r my-repo \
  --path config.yml --message "Add config" --file ./config.yml

18. Downloads (4 commands)

Manage repository download artifacts.

# List downloads
bitbucket download-list -w myworkspace -r my-repo

# Upload an artifact
bitbucket download-upload -w myworkspace -r my-repo --file ./release-v1.0.zip

# Delete a download (requires --confirm)
bitbucket download-delete -w myworkspace -r my-repo --filename release-v1.0.zip --confirm

19. Webhooks (2 commands)

Discover available webhook event types.

# List webhook event subjects
bitbucket webhook-events

# List event types for a subject
bitbucket webhook-event-types --subject repository

20. Search (3 commands)

Search code, accounts, and teams.

# Search code
bitbucket search-code -w myworkspace --search-query "import express"

# Search for an account
bitbucket search-account --search-query "john"

21. Reports (9 commands)

Manage commit reports and annotations (code quality, security, etc.).

# Create a code quality report
bitbucket report-create -w myworkspace -r my-repo --commit abc123 \
  --report-id lint-report --title "ESLint" --report-type BUG \
  --data '{"result":"PASSED"}'

# Add annotations to a report
bitbucket report-annotation-bulk-create -w myworkspace -r my-repo \
  --commit abc123 --report-id lint-report \
  --data '[{"path":"src/app.js","line":42,"message":"Unused variable","severity":"MEDIUM"}]'

# List reports on a commit
bitbucket report-list -w myworkspace -r my-repo --commit abc123

22. Properties (12 commands)

Get, set, and delete application properties on commits, repos, PRs, and users.

# Set a repo property
bitbucket repo-property-update -w myworkspace -r my-repo \
  --app-key myapp --property-name env --data '{"tier":"production"}'

# Get a repo property
bitbucket repo-property-get -w myworkspace -r my-repo \
  --app-key myapp --property-name env

# Delete a PR property (requires --confirm)
bitbucket pr-property-delete -w myworkspace -r my-repo --pr-id 42 \
  --app-key myapp --property-name review-status --confirm

23. Addon (10 commands)

Manage Bitbucket Connect addon lifecycle, linkers, and linker values.

# List addon linkers
bitbucket addon-linkers

# Create a linker value
bitbucket addon-linker-value-create --linker-key my-linker \
  --data '{"key":"issue-42","href":"https://tracker.example.com/42"}'

# Delete a linker value (requires --confirm)
bitbucket addon-linker-value-delete --linker-key my-linker --value-id 42 --confirm

Security

• Auth method: Basic auth with App Passwords (BITBUCKET_USERNAME + BITBUCKET_APP_PASSWORD)
• No secrets or tokens printed to stdout
• All delete operations require explicit --confirm flag
• Path traversal prevention for file uploads (safePath())
• Built-in rate limiting with exponential backoff retry (3 attempts)
• File size validation before upload
• Lazy config validation (only checked when a command runs)

Dependencies

• commander — CLI framework
• dotenv — environment variable loading
• Node.js built-in fetch (requires Node >= 18)

Author

Abdelkrim BOUJRAF — ALT-F1 SRL, Brussels X: @altf1be