{"id":51495948,"url":"https://github.com/daniel-pittman/bitbucket-cli","last_synced_at":"2026-07-07T15:30:29.573Z","repository":{"id":360523807,"uuid":"1145410401","full_name":"daniel-pittman/bitbucket-cli","owner":"daniel-pittman","description":"Lightweight CLI for Bitbucket Cloud - manage pipelines, PRs, and repos from your terminal","archived":false,"fork":false,"pushed_at":"2026-06-28T23:00:14.000Z","size":740,"stargazers_count":2,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"develop","last_synced_at":"2026-06-29T00:21:13.753Z","etag":null,"topics":["atlassian","bash","bitbucket","bitbucket-cloud","cli","developer-tools","devops","git","pipelines","pull-requests"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/daniel-pittman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-29T19:22:10.000Z","updated_at":"2026-06-28T22:59:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/daniel-pittman/bitbucket-cli","commit_stats":null,"previous_names":["daniel-pittman/bitbucket-cli"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/daniel-pittman/bitbucket-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-pittman%2Fbitbucket-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-pittman%2Fbitbucket-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-pittman%2Fbitbucket-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-pittman%2Fbitbucket-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/daniel-pittman","download_url":"https://codeload.github.com/daniel-pittman/bitbucket-cli/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-pittman%2Fbitbucket-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35234127,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-07T02:00:07.222Z","response_time":90,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["atlassian","bash","bitbucket","bitbucket-cloud","cli","developer-tools","devops","git","pipelines","pull-requests"],"created_at":"2026-07-07T15:30:25.878Z","updated_at":"2026-07-07T15:30:29.484Z","avatar_url":"https://github.com/daniel-pittman.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# bb - Bitbucket CLI\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/img/social-preview.png\" alt=\"bb — Bitbucket Cloud CLI\" width=\"720\" /\u003e\n\u003c/p\u003e\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![CI](https://github.com/daniel-pittman/bitbucket-cli/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/daniel-pittman/bitbucket-cli/actions/workflows/ci.yml)\n[![Bash](https://img.shields.io/badge/bash-3.2%2B-1f425f.svg)](https://www.gnu.org/software/bash/)\n[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)\n[![GitHub release](https://img.shields.io/github/v/release/daniel-pittman/bitbucket-cli)](https://github.com/daniel-pittman/bitbucket-cli/releases)\n\nA lightweight command-line interface for Bitbucket Cloud. Wraps the Bitbucket REST API for common operations like managing pipelines, pull requests, and repositories. Ships with a Python [MCP server](#mcp-server-for-claude-code--ai-agents) so any [Claude Code](https://docs.claude.com/en/docs/claude-code) session (or any other MCP-aware client) can drive Bitbucket Cloud as native tools.\n\nThe bash CLI has no dependencies beyond `curl` and `jq`. The MCP server adds Python 3.10+. Works on macOS, Linux, and WSL.\n\n## Features\n\n- **Pipelines**: List, view, watch, trigger, and stop pipeline builds\n- **Pull Requests**: Create, view, approve, unapprove, merge, decline, diff, comment\n- **Repositories**: List repos, view details, list/show branches, list recent commits\n- **Browser Integration**: Quick-open any resource in your browser\n- **MCP server**: 31 tools covering the full surface, plus git-context wrappers (current branch, status, recent commits, uncommitted changes) for agent workflows\n\n## Requirements\n\n- `bash` (3.2+) — works with macOS system bash; bash 4+ also fine\n- `curl` - usually pre-installed on macOS/Linux\n- `jq` - JSON processor ([install instructions](https://jqlang.github.io/jq/download/))\n- Python 3.10+ (only required for the MCP server)\n\n### Installing jq\n\n**macOS** (Homebrew):\n```bash\nbrew install jq\n```\n\n**Ubuntu/Debian**:\n```bash\nsudo apt-get install jq\n```\n\n**Fedora/RHEL**:\n```bash\nsudo dnf install jq\n```\n\n**Windows** (via Chocolatey):\n```bash\nchoco install jq\n```\n\n## Installation\n\n1. Clone this repository:\n   ```bash\n   git clone https://github.com/daniel-pittman/bitbucket-cli.git\n   cd bitbucket-cli\n   ```\n\n2. Make the script executable:\n   ```bash\n   chmod +x bb\n   ```\n\n3. Symlink to your PATH. Pick the directory that's on your PATH and that you own:\n   ```bash\n   # macOS with Homebrew (no sudo needed; resolves to /opt/homebrew on\n   # Apple Silicon, /usr/local on Intel Macs):\n   ln -s \"$(pwd)/bb\" \"$(brew --prefix)/bin/bb\"\n\n   # macOS without Homebrew, or Linux (needs sudo on most setups):\n   sudo ln -s \"$(pwd)/bb\" /usr/local/bin/bb\n   ```\n\n   Or add the directory to your PATH (pick the rc file your shell uses;\n   macOS defaults to zsh since Catalina):\n   ```bash\n   # bash:\n   echo 'export PATH=\"$PATH:/path/to/bitbucket-cli\"' \u003e\u003e ~/.bashrc\n   # zsh (default on macOS):\n   echo 'export PATH=\"$PATH:/path/to/bitbucket-cli\"' \u003e\u003e ~/.zshrc\n   ```\n\n## Configuration\n\nCreate a config file at `~/.config/bb/config`:\n\n```bash\nmkdir -p ~/.config/bb\ncat \u003e ~/.config/bb/config \u003c\u003cEOF\nBB_USER=your-email@example.com\nBB_TOKEN=your-api-token\nBB_WORKSPACE=your-workspace   # optional — see \"How the workspace is resolved\"\nEOF\n```\n\n`BB_USER` and `BB_TOKEN` are required. `BB_WORKSPACE` is **optional**: when\nyou run `bb` inside a Bitbucket git checkout, the workspace is auto-detected\nfrom the `origin` remote, so you only need `BB_WORKSPACE` as a fallback for\ncommands run outside a repo (e.g. `bb repos` from an arbitrary directory).\n\n### How the workspace is resolved\n\nFor any command that needs a workspace, `bb` resolves it in this order\n(highest priority first):\n\n1. **`-w/--workspace \u003cname\u003e` flag** — explicit, per-invocation override.\n2. **`workspace/slug` argument** — e.g. `bb pipelines acme/widget` targets the\n   `acme` workspace regardless of git context or config.\n3. **git `origin` auto-detect** — when you're inside a Bitbucket checkout, the\n   workspace comes from the remote URL. This is why `cd`-ing into any repo and\n   running `bb prs` / `bb pipelines` Just Works across multiple workspaces.\n4. **`BB_WORKSPACE`** — your configured default, used when none of the above\n   apply (notably for repo-less commands like `bb repos` run outside a checkout).\n5. If none resolve a workspace, the command fails with a message naming all\n   three ways to supply one.\n\nThis mirrors the MCP server's `_resolve_repo` behavior, so the bash CLI and the\nPython tools agree on which workspace a given invocation targets.\n\n### Getting an API Token\n\n1. Go to [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)\n2. Click \"Create API token\"\n3. Copy the token and set it as `BB_TOKEN`\n4. Set `BB_USER` to your Bitbucket account email address\n\n### Required Bitbucket Permissions\n\nYour Bitbucket account needs these workspace permissions:\n\n| Feature | Required Permission |\n|---------|---------------------|\n| View pipelines, PRs, repos | **Read** access to repositories (`read:repository:bitbucket`) |\n| Trigger/stop pipelines | **Read + Write** access to Pipelines (`read:pipeline:bitbucket`, `write:pipeline:bitbucket`) |\n| Create/approve/merge PRs | **Read + Write** access to Pull Requests (`read:pullrequest:bitbucket`, `write:pullrequest:bitbucket`) |\n| List workspaces (`bb workspaces`) | `read:workspace:bitbucket` (new in v1.2.0 — Atlassian API token scope, opt-in when creating the token) |\n| List projects (`bb projects`) | `read:project:bitbucket` (Atlassian API token scope, opt-in when creating the token). Verified against the live 403 envelope: the missing scope is named under `error.detail.required`. |\n| Create a repository (`bb repo-create`) | **Admin** access to repositories (`admin:repository:bitbucket`). `write:repository:bitbucket` alone is not sufficient. |\n| Update a repository (`bb repo-update`, e.g. move its project) | **Admin** access to repositories (`admin:repository:bitbucket`). `write:repository:bitbucket` alone is not sufficient (same scope as `bb repo-create`). |\n| Read Pipelines status (`bb pipelines-status`) | **Read** access to Pipelines (`read:pipeline:bitbucket`). |\n| Enable/disable Pipelines (`bb pipelines-enable`, `bb pipelines-disable`) | **Admin** access to Pipelines (`admin:pipeline:bitbucket`). `write:pipeline:bitbucket` alone is not sufficient. |\n| List deployment environments (`bb environments`) | **Read** access to Pipelines (`read:pipeline:bitbucket`). |\n| Create/delete deployment environments (`bb environment-create`, `bb environment-delete`) | **Admin** access to Pipelines (`admin:pipeline:bitbucket`). `write:pipeline:bitbucket` alone is not sufficient. |\n| Set or delete pipeline variables, any scope (`bb vars set`, `bb vars delete`, with `--workspace` / `--deployment \u003cenv\u003e`) | **Admin** access to Pipelines (`admin:pipeline:bitbucket`). `write:pipeline:bitbucket` alone is not sufficient. This one scope covers set and delete at all three variable scopes (repo, workspace, deployment-environment); verified against the live 403 envelope. |\n\nNote: Atlassian API tokens inherit your account's workspace permissions. If you can perform an action in the Bitbucket UI, the CLI can do it too — provided the token carries the scope. The cross-workspace listing endpoints (`/2.0/workspaces`, `/2.0/repositories?role=member`) were removed under Atlassian's [CHANGE-2770](https://developer.atlassian.com/cloud/bitbucket/changelog/) on 2026-04-14; `bb workspaces` uses the replacement `/2.0/user/workspaces` endpoint (CHANGE-3022) which requires the `read:workspace:bitbucket` scope. Rotating the token to add it leaves existing tokens unchanged.\n\nThe `bb repo-create` and `bb vars set` admin scopes are the most common to be missing, because most day-to-day tokens are scoped read + write only. A token's scopes are fixed at creation: adding a scope does not apply to an already-issued token. To use these two commands you must create a new token (or rotate the existing one) with the admin scope included. A token without the scope returns a 403 whose body names the exact missing scope under `error.detail.required`, so the failure is self-diagnosing.\n\n### Environment Variables\n\nYou can also set configuration via environment variables:\n\n```bash\nexport BB_USER=\"your-email@example.com\"\nexport BB_TOKEN=\"your-api-token\"\nexport BB_WORKSPACE=\"your-workspace\"\n```\n\n## Usage\n\n```\nbb \u003ccommand\u003e [options]\n```\n\n### Pipelines\n\n```bash\nbb pipelines [repo] [count]           # List recent pipelines (default: 10)\nbb pipeline [repo] \u003cnumber\u003e           # Show pipeline details and steps\nbb watch [repo] [number] [interval]   # Poll pipeline until done (default: 15s)\nbb logs [repo] \u003cnumber\u003e [step]        # Show step logs\nbb trigger [repo] [branch] [pattern]  # Trigger a pipeline run\nbb stop [repo] \u003cnumber\u003e               # Stop a running pipeline\nbb approve [repo] \u003cnumber\u003e            # Open pipeline in browser (manual steps require UI)\nbb pipelines-status [repo]            # Show whether Pipelines (CI) is enabled\nbb pipelines-enable [repo]            # Enable Pipelines (CI) on a repo\nbb pipelines-disable [repo]           # Disable Pipelines (CI) on a repo\n```\n\nPipelines must be **enabled** on a repo before pipeline variables, custom pipelines, or builds work at all. `bb pipelines-status` reports the current state (it reads as \"disabled (never configured)\" when Pipelines has never been set up, which the API signals with a 404). `bb pipelines-enable` / `bb pipelines-disable` toggle it and need `admin:pipeline:bitbucket` scope.\n\n### Pull Requests\n\n```bash\nbb prs [repo] [state]                 # List PRs (default: OPEN)\nbb pr [repo] \u003cid\u003e                     # View PR details\nbb pr-create [repo] \u003ctitle\u003e [dest]    # Create PR from current branch\nbb pr-approve [repo] \u003cid\u003e             # Approve a PR\nbb pr-merge [repo] \u003cid\u003e [strategy]    # Merge a PR (merge_commit|squash|fast_forward)\nbb pr-decline [repo] \u003cid\u003e             # Decline a PR\nbb pr-diff [repo] \u003cid\u003e                # Show PR diff\nbb pr-comments [repo] \u003cid\u003e            # Show PR comments\n```\n\n### Branches \u0026 Repositories\n\n```bash\nbb branches [repo]                    # List branches\nbb projects [workspace]               # List workspace projects\nbb repos                              # List workspace repos\nbb repo [repo]                        # Show repo details\nbb repo-create \u003cname\u003e [opts]          # Create a repo (default PRIVATE)\nbb repo-update [repo] \u003copts\u003e          # Update a repo (move project, change description)\nbb downloads [repo]                   # List repo downloads\nbb environments [repo]                # List deployment environments\nbb environment-create [repo] \u003cname\u003e [--type T]  # Create a deployment environment\nbb environment-delete [repo] \u003cname\u003e   # Delete a deployment environment\nbb vars [scope] [repo]                # List pipeline variables (repo|workspace|deployment)\nbb vars set [scope] [repo] \u003cKEY\u003e [opts]  # Create or update a pipeline variable\nbb vars delete [scope] [repo] \u003cKEY\u003e   # Delete a pipeline variable (destructive)\n```\n\n`bb environments` lists a repo's deployment environments (the named targets a pipeline deploys to: Test / Staging / Production). `bb environment-create \u003cname\u003e [--type Test|Staging|Production]` adds one (default type `Test`); `bb environment-delete \u003cname\u003e` removes it by name. Each environment carries its own deployment variables, managed via `bb vars [set] --deployment \u003cenv\u003e`. Create and delete need `admin:pipeline:bitbucket` scope.\n\n`bb projects` lists a workspace's projects (KEY and NAME). The KEY is what `--project` expects on `bb repo-create` and `bb repo-update`. The workspace defaults to the resolved one (`-w` / git origin / `BB_WORKSPACE`); pass an explicit `[workspace]` to list another's. Needs `read:project:bitbucket` scope. See [Required Bitbucket Permissions](#required-bitbucket-permissions).\n\n```bash\nbb projects                # projects in the resolved workspace\nbb projects acme           # projects in workspace \"acme\"\n```\n\n`bb repo-create` defaults to a **private** repo so a forgotten flag never publishes one. Flags: `--public` / `--private`, `--project KEY` (required on workspaces that use projects), `--description TEXT`.\n\n```bash\nbb repo-create widget-service                          # private, default project\nbb repo-create widget-service --project WID            # private, in project WID\nbb repo-create docs-site --public --description \"Docs\" # public\n```\n\n`bb repo-update` changes an existing repo's settings. The dominant use is moving a repo between projects (`bb repo-create` takes a project but nothing else could change it afterward). At least one of `--project KEY` / `--description TEXT` is required; `[repo]` accepts the same shapes as every other repo command (bare slug, `ws/slug`, or omitted to auto-detect from the git origin).\n\n```bash\nbb repo-update widget-service --project WID            # move into project WID\nbb repo-update acme/widget-service --description \"...\"  # change description\nbb repo-update --project WID                            # current checkout, move project\n```\n\nBoth `bb repo-create` and `bb repo-update` need `admin:repository:bitbucket` scope on the token. A read/write-only token must be rotated to add it (adding a scope does not apply to an already-issued token). See [Required Bitbucket Permissions](#required-bitbucket-permissions).\n\n`bb vars`, `bb vars set`, and `bb vars delete` operate at three scopes, selected by a flag (default is repo):\n\n- repo (default): no flag.\n- workspace: `--workspace` (no repo argument; variables are shared across the workspace).\n- deployment-environment: `--deployment \u003cenv\u003e`. `\u003cenv\u003e` is the environment NAME or slug (for example `Development` or `production`), which the command resolves to its environment UUID by listing the repo's environments first. An unknown name fails with the list of available environments and writes nothing.\n\nThe scope endpoints are `pipelines_config` (repo, underscore), `pipelines-config` (workspace, hyphen), and `deployments_config/environments/{uuid}` (deployment); the hyphen-vs-underscore difference is a Bitbucket API quirk, handled for you.\n\n`bb vars set` creates the variable if its key is new at that scope, or updates the existing one. Provide the value via **exactly one** of `--value`, `--value-file`, or `--value-env`. For secrets prefer `--value-file` or `--value-env` so the secret never appears in `argv` / the process list / shell history, and pass `--secured` so Bitbucket masks it. The command never echoes a value back, at any scope.\n\n```bash\n# Repo scope (default)\nbb vars set widget-service AWS_REGION --value us-east-1            # non-secret\nbb vars set widget-service AWS_SECRET --secured --value-file ./secret.txt\nbb vars set widget-service AWS_KEY --secured --value-env AWS_KEY   # read from env\n\n# Workspace scope (shared across the workspace; no repo argument)\nbb vars --workspace\nbb vars set --workspace DOCKERHUB_TOKEN --secured --value-env DOCKERHUB_TOKEN\n\n# Deployment-environment scope (env name resolves to its UUID)\nbb vars --deployment Production widget-service\nbb vars set --deployment Production widget-service DB_URL --secured --value-file ./db_url.txt\n```\n\n`bb vars delete \u003cKEY\u003e` removes a variable by key at the chosen scope (it resolves the key to its UUID first, walking all pages). A key that does not exist at the scope fails with a clean not-found error and issues no delete. This is destructive (a secured value can't be recovered after deletion), so confirm the key and scope before running it.\n\n```bash\nbb vars delete widget-service AWS_ACCESS_KEY_ID            # repo scope\nbb vars delete --workspace DOCKERHUB_TOKEN                 # workspace scope\nbb vars delete --deployment Production widget-service DB_URL  # deployment scope\n```\n\nAll three scopes, for `bb vars`, `bb vars set`, and `bb vars delete`, need `admin:pipeline:bitbucket` scope on the token (`write:pipeline:bitbucket` alone is not enough). A read/write-only token must be rotated to add it. See [Required Bitbucket Permissions](#required-bitbucket-permissions).\n\n### Utilities\n\n```bash\nbb open [repo] [section]              # Open in browser (pr|pipelines|branches|settings|commits)\nbb help                               # Show help\n```\n\n### Global Flags\n\n```bash\n-w, --workspace \u003cname\u003e                # Override workspace for this command\n```\n\n### Auto-Detection\n\nWhen inside a git repository with a Bitbucket remote, the `[repo]` argument is optional — **both the repo slug AND the workspace** are auto-detected from the `origin` remote URL. This is what lets you `cd` between repos in different workspaces and have commands target the right one without a `-w` flag. To override, pass `-w \u003cworkspace\u003e`, a `workspace/slug` argument, or set `BB_WORKSPACE` as a default (see [How the workspace is resolved](#how-the-workspace-is-resolved)).\n\n## Examples\n\n```bash\n# Watch the latest pipeline on current repo\nbb watch\n\n# List open PRs\nbb prs\n\n# Create a PR from current branch to main\nbb pr-create \"Add new feature\"\n\n# Trigger a custom pipeline with variables\nbb trigger my-repo main manual-deploy-prod LAMBDA_NAMES=mci\n\n# View pipeline logs for step 1\nbb logs my-repo 42 1\n\n# Open repo settings in browser\nbb open my-repo settings\n```\n\n## MCP server (for Claude Code / AI agents)\n\nA Python [Model Context Protocol](https://modelcontextprotocol.io/) server (`mcp_server.py`) ships as a peer to the `bb` bash script. Both implement the **same Bitbucket Cloud REST contract** independently — the MCP server does not shell out to `bb`; it speaks HTTP directly via Python stdlib (no `requests` etc.). Any [Claude Code](https://docs.claude.com/en/docs/claude-code) session — or any other MCP-aware client — can drive Bitbucket Cloud as native tools without invoking the CLI.\n\n### What it exposes\n\n41 tools covering pipelines, pull requests, workspaces, projects, repos, branches, commits, pipeline config + variables, deployment environments, and git-context helpers:\n\n| Category | Tools |\n|---|---|\n| Pipelines (read) | `pipelines_list`, `pipeline_show`, `pipeline_steps`, `pipeline_logs`, `pipelines_config_show` |\n| Pipelines (write) | `pipeline_trigger`, `pipeline_stop`, `pipelines_config_set` (enable/disable; needs `admin:pipeline:bitbucket`) |\n| Pull requests (read) | `prs_list`, `pr_show`, `pr_activity`, `pr_diff`, `pr_comments_list` |\n| Pull requests (write) | `pr_create`, `pr_approve`, `pr_unapprove`, `pr_merge`, `pr_decline`, `pr_comment_add` |\n| Workspaces / projects | `workspaces_list` (needs `read:workspace:bitbucket` scope), `projects_list` (needs `read:project:bitbucket` scope) — see [Required Bitbucket Permissions](#required-bitbucket-permissions) |\n| Repos / metadata | `repos_list`, `repo_show`, `repo_create`, `repo_update`, `branches_list`, `branch_show`, `commits_list`, `vars_list`, `vars_set`, `vars_delete`, `downloads_list` |\n| Deployment environments | `environments_list`, `environment_create`, `environment_delete` (create/delete need `admin:pipeline:bitbucket`) |\n| Git context | `git_current_branch`, `git_status`, `git_remote_repo`, `git_recent_commits`, `git_uncommitted_changes` |\n| Meta | `whoami` (see note below) |\n\nNote on `whoami`: resolves config + git context + a workspace-reachability probe (single low-cost `GET /repositories/{workspace}?pagelen=1`, 10 s timeout). Never echoes `BB_TOKEN`. The probe requires `repository:read` scope — a workspace-scoped token granting only `pipelines:read` or `pullrequest:read` will report `auth.ok=False` even though pipeline/PR tools still work, so treat the probe as a scope hint rather than a global credential verdict.\n\nEvery tool that takes a repo argument supports auto-detection (omit `repo` to resolve from the current git checkout's `origin` remote — or from `BB_DEFAULT_REPO_PATH` if set; see [Environment overrides](#environment-overrides) below) and workspace override (`workspace/repo` shape).\n\n### MCP server requirements\n\n- Python 3.10+ available on PATH (the bash CLI doesn't need Python — only the MCP server does).\n- The same `~/.config/bb/config` (or `BB_USER` / `BB_TOKEN` / `BB_WORKSPACE` env vars) as the CLI — see [Configuration](#configuration) above.\n\n### MCP server install\n\n```bash\n# 1. Make sure bb itself is installed and configured (see Configuration above).\n\n# 2. Register the MCP server with Claude Code (user scope = all sessions on this machine):\nclaude mcp add --scope user bitbucket \\\n    -- python3 /absolute/path/to/bitbucket-cli/mcp_server.py  # ← replace with your clone path\n\n# `python3` is intentionally bare — `claude mcp add` inherits PATH, so a\n# Homebrew or pyenv Python 3.10+ resolves naturally. Do NOT hardcode\n# /usr/bin/python3 on macOS: Apple's bundled Python at that path is 3.9,\n# which is below the MCP server's 3.10 minimum. The `--` separator before\n# `python3` keeps the command robust if you later add `--env` flags\n# (see \"Multiple workspaces\" below).\n\n# 3. On first invocation, the server self-bootstraps a durable venv at\n#    $XDG_DATA_HOME/bitbucket-cli/venv (default: ~/.local/share/bitbucket-cli/venv)\n#    and installs the `mcp` package into it. Subsequent launches reuse the venv.\n#\n#    To force a clean rebuild:\n#      rm -rf \"${XDG_DATA_HOME:-$HOME/.local/share}/bitbucket-cli/venv\"\n#    and relaunch the MCP server.\n\n# 4. Verify the connection (handshake only — does NOT validate credentials):\nclaude mcp list\n# Should show: bitbucket: ... - ✓ Connected\n#\n# First invocation may briefly show \"✗ Failed to connect\" while the venv\n# bootstraps (pip-installs `mcp`, 5-30 s depending on network). Retry once.\n\n# 5. Verify credentials in a Claude Code session by asking it to run the\n#    `whoami` tool — `Connected` above only confirms the stdio handshake;\n#    `whoami` confirms BB_USER/BB_TOKEN/BB_WORKSPACE actually resolve AND\n#    the token reaches your configured workspace.\n```\n\n**Multiple workspaces:** to register more than one server (e.g. `bitbucket-work` and `bitbucket-personal` pointing at different workspaces), use `--env` flags per registration so each server entry carries its own credentials:\n\n```bash\nclaude mcp add --scope user bitbucket-work \\\n    --env BB_USER=you@work.com \\\n    --env BB_TOKEN=... \\\n    --env BB_WORKSPACE=acme \\\n    -- python3 /absolute/path/to/bitbucket-cli/mcp_server.py  # ← replace with your clone path\n```\n\n### Other MCP clients\n\n`mcp_server.py` is a stdio MCP server, so any client that speaks MCP-over-stdio can use it. The command is `python3 /absolute/path/to/bitbucket-cli/mcp_server.py` — same Python-version constraint as above. Credentials come from `~/.config/bb/config` or environment variables; clients that strip `HOME` from the subprocess environment need to pass `BB_USER` / `BB_TOKEN` / `BB_WORKSPACE` explicitly instead.\n\n### Environment overrides\n\n| Variable | Purpose |\n|---|---|\n| `BB_API_BASE` | Override the Bitbucket REST base URL (default `https://api.bitbucket.org/2.0`). Useful for a test / proxied / staging mirror. |\n| `BB_DEFAULT_REPO_PATH` | Default working directory for repo auto-detection (when a Bitbucket tool is called with `repo=\"\"`) AND for the `git_*` tools' default `path=\"\"` resolution. Defaults to the MCP server's launch cwd. |\n| `XDG_DATA_HOME` | Standard XDG override for the data root. The venv lives at `$XDG_DATA_HOME/bitbucket-cli/venv` (default `~/.local/share/bitbucket-cli/venv`). |\n\n### Optional: install the bundled `bitbucket` agent for delegated use\n\nThe MCP server exposes the *tools*; the bundled **agent** (`agents/bitbucket.md` in this repo) is the *behavioral layer* that makes a Claude Code session use those tools intelligently — propose-first protocol for destructive ops (`pr_merge`, `pr_decline`, `pipeline_stop`, `pr_unapprove`), resolve-git-context-first before any Bitbucket call, show-diffs-before-merge discipline, bash/Python parity rule for delegated CLI maintenance, and the per-workspace conventions block for tracking each workspace's defaults.\n\nThe bundled `agents/bitbucket.md` is a **deliberately-generic template** — it ships with placeholder examples (`acme/widget-service`, fictional reviewers, generic custom-pipeline patterns like `deploy-prod`) and an explicitly-blank \"Per-workspace conventions\" section at the bottom. After copying it to `~/.claude/agents/bitbucket.md`, personalize your local copy with your default workspace, required reviewers, custom pipeline patterns, branch naming conventions, and any other non-generic context. **Anything you contribute back to this repo via PR should be re-genericized first** — real workspace slugs, real ticket titles, real reviewer handles, and project-specific custom-pipeline patterns belong only in your personal `~/.claude/agents/` copy, never in the upstream-tracked version.\n\nThe agent is a single Markdown file with frontmatter. To install:\n\n```bash\n# 1. Copy the agent definition into user-scope agents.\nmkdir -p ~/.claude/agents\ncp agents/bitbucket.md ~/.claude/agents/bitbucket.md\n\n# 2. Populate the \"Per-workspace conventions\" section using bb itself —\n#    don't type defaults from memory, let the CLI discover them:\n#      bb workspaces                # which workspaces you belong to\n#      bb -w \u003cws\u003e repos             # what's in each\n#      bb repo \u003cws\u003e/\u003crepo\u003e          # → Main branch (verify PR base; GitFlow repos target develop)\n#      bb pipelines \u003cws\u003e/\u003crepo\u003e     # → TRIGGER column = custom pipelines\n#      bb branches \u003cws\u003e/\u003crepo\u003e      # → branch-naming convention\n#      bb vars \u003cws\u003e/\u003crepo\u003e          # → SECURED=true = sensitive vars to mask\n#    Add one block per workspace (the template at the bottom of the agent\n#    file shows the shape). The bundled agent can run this survey for you.\n\n# 3. Newly-started Claude Code sessions pick up the agent automatically.\n#    Existing sessions need a restart. In any new session you can then\n#    delegate to it:\n#\n#    \"Use the bitbucket agent to merge PR 42\"\n#    \"Have the bitbucket agent watch pipeline 142\"\n#    \"Ask the bitbucket agent to trigger a deploy-prod run on main\"\n```\n\nThe agent description tells Claude Code's orchestrator when to delegate to it automatically (e.g. when the user mentions Bitbucket pipeline / PR / repo operations). You don't have to invoke it by name.\n\nWhat the agent enforces on top of the raw tools:\n\nThe MCP tools already do per-call auto-detection on their own (source-branch auto-detect on `pr_create`, repo auto-detect on every Bitbucket tool given `repo=\"\"`) — the agent doesn't re-implement those. What the agent adds:\n\n| Behavior | Raw MCP tools | With bundled `bitbucket` subagent |\n|---|---|---|\n| **Destructive ops** (`pr_merge`, `pr_decline`, `pipeline_stop`, `pr_unapprove`) | Fired immediately when invoked | Propose-first: show diff / activity / current state, confirm with user, then act |\n| **Pipeline failure investigation** | Caller must navigate `pipeline_show` → `pipeline_steps` → `pipeline_logs` manually | Triages in that order, surfaces the relevant log tail (last ~50 lines around the failure) instead of dumping the whole stream |\n| **Avoiding redundant probes** | Caller may re-fetch `git_current_branch` / `git_remote_repo` per call even when the tool would auto-detect | Lets tool-level auto-detect carry the call (passes `repo=\"\"` and omits `source_branch=` instead of pre-fetching git context just to echo it back) |\n| **`bb`-CLI maintenance** (delegated) | Re-discovers the parity rule, naming conventions, redaction patterns per session | Owns the design → implement → test → docs → PR cycle with the rules already baked in |\n| **Per-workspace conventions** | Re-discovered each session | Reads (or bb-discovers and proposes) the agent file's \"Per-workspace conventions\" block for the active workspace before any write op |\n\n### Security\n\n- `BB_TOKEN` is never echoed (`whoami`, error envelopes, log lines).\n- URL credentials (`https://user:token@host/...`) and signed-URL query parameters (AWS / Azure / GCP / bearer / access_token / api_key) are stripped from every error message.\n- Cross-host `Authorization` headers are stripped on redirect so the Bitbucket Basic header never reaches S3 when fetching pipeline logs.\n- Pipeline variable values are masked as `KEY=***` when echoed back.\n\nThe agent file is genuinely portable — strip the example \"Per-workspace conventions\" section and you have a clean template that works for any Bitbucket Cloud workspace.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaniel-pittman%2Fbitbucket-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdaniel-pittman%2Fbitbucket-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaniel-pittman%2Fbitbucket-cli/lists"}