A fast, comprehensive command-line interface for Bitbucket Cloud and
Bitbucket Data Center / Server. Inspired by gh
and glab.
Status: early scaffolding. Expect breaking changes.
bb auth— log in with app password / HTTP access token / OAuthbb repo— clone, view, create, fork, list, settings / webhooksbb pr— list, view, create, checkout, diff, review, mergebb pipelines— list, view, logs, run, cancel (Bitbucket Pipelines & Bamboo)bb issue— list, view, create, commentbb browse— open the current repo / PR / pipeline in a browserbb api— raw API passthrough (likegh api)bb completion— shell completions for bash / zsh / fish / powershell
Works against:
- Bitbucket Cloud (
bitbucket.org, REST API 2.0) - Bitbucket Data Center / Server (self-hosted, REST API 1.0)
Pick the method for your platform. See PUBLISHING.md for how releases are built.
# macOS / Linux — Homebrew
brew install hugs7/tap/bitbucket-cli
# Windows — Scoop
scoop bucket add hugs7 https://github.com/hugs7/scoop-bucket
scoop install bb
# Debian / Ubuntu — apt
curl -1sLf 'https://dl.cloudsmith.io/public/hugs7/bitbucket-cli/setup.deb.sh' | sudo -E bash
sudo apt install bitbucket-cli
# Fedora / RHEL — dnf
curl -1sLf 'https://dl.cloudsmith.io/public/hugs7/bitbucket-cli/setup.rpm.sh' | sudo -E bash
sudo dnf install bitbucket-cli
# Alpine — apk
curl -1sLf 'https://dl.cloudsmith.io/public/hugs7/bitbucket-cli/setup.alpine.sh' | sudo -E bash
sudo apk add bitbucket-cliUseful for CI, Docker images, exotic distros, or just trying it quickly:
# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/hugs7/bitbucket-cli/main/scripts/install.sh | sh
# Windows (PowerShell)
irm https://raw.githubusercontent.com/hugs7/bitbucket-cli/main/scripts/install.ps1 | iexDrops the binary into ~/.local/bin/bb and the zsh completion into
~/.zsh/completions/_bb, and adds the necessary fpath snippet to
~/.zshrc (idempotent — re-run any time to upgrade in place):
curl -fsSL https://raw.githubusercontent.com/hugs7/bitbucket-cli/main/scripts/install-mac-zsh.sh | shMake sure ~/.local/bin is on your $PATH.
git clone https://github.com/hugs7/bitbucket-cli
cd bitbucket-cli
go build -o bb ./cmd/bb
./bb --help| Installed via | Update with |
|---|---|
| Homebrew | brew upgrade bitbucket-cli |
| Scoop | scoop update bb |
| apt (Cloudsmith) | sudo apt update && sudo apt upgrade bitbucket-cli |
| dnf (Cloudsmith) | sudo dnf upgrade bitbucket-cli |
| apk (Cloudsmith) | sudo apk upgrade bitbucket-cli |
curl | sh script / direct binary |
bb upgrade |
bb upgrade checks GitHub Releases and atomically replaces the
running binary on Linux, macOS and Windows. Use bb upgrade --check
to peek without installing.
Config lives at ~/.config/bb/config.yml (override with BB_CONFIG).
default_host: bitbucket.org
hosts:
bitbucket.org:
type: cloud
username: your-username
# token stored separately in OS keyring or env BB_TOKEN
bitbucket.mycorp.example:
type: server
api_base: https://bitbucket.mycorp.example/rest/api/1.0Per-repo overrides go in .bb.yml at the repo root.
All interactive entry points share the same navigation: bb, bb ., bb repo,
bb prs, bb pr <url>, and bb repo settings.
- Esc goes back: PR detail → PR list → repository overview → home,
even when you opened the PR list directly with
bb prs. - From the repository overview, p opens PRs and Shift+S opens repository settings. In settings, Esc returns from details to the sidebar, then to the repository overview.
- q or Ctrl+C quits the session rather than reopening a parent screen. Forms, editors, and searches retain their own typing/cancellation shortcuts.
bb prs → C, or bb pr create, opens the creation form. Target suggestions
prefer the closest shared ancestor with the source branch, then the newest
branch-tip commit. Unrelated branches sort alphabetically. Press Tab on the
empty target field to accept the first suggestion, or ↑/↓ to cycle first.
bb pr create -a # --auto-target: infer target from local history
bb pr create -a -y --title "My fix" # non-interactive, repository default reviewers
bb pr create -T release/current -r alice,bob -y
bb pr create -T release/current --no-reviewers -y--auto-target and --target are mutually exclusive. Git does not record a
branch's original parent: this is a history-based inference, not a guarantee.
Ranking uses local heads and the selected Bitbucket remote's tracking refs,
without fetching. Fetch that remote to refresh stale history. The graph walk is
capped at 50,000 commits and three seconds; missing history falls back to names,
and --auto-target fails if no shared ancestor can be found. Non-interactive
creation without either flag retains the repository default target.
Applicable repository/project default reviewers start selected after choosing
source and target. Toggle them, add usernames, or submit a directory search to
add candidates without losing selections. --reviewer replaces defaults;
--no-reviewers explicitly suppresses them. Defaults failing to load aborts
creation rather than silently omitting reviewers. Cloud accepts UUIDs/names;
directory search availability depends on the backend.
When multiple remotes exist, automatic repository detection prefers configured
Bitbucket hosts or recognisable Bitbucket remotes over a GitHub origin. The
creation TUI's optional push also uses that remote and preserves any existing
upstream. Use -R host/PROJ/repo to select an API repository explicitly.
bb repo settings opens the settings TUI. Choose a section and press
Tab, Enter, or →: single-document settings open directly in their
editor, without an extra e step. Esc discards and returns to sections.
Collections keep their item list; in Default reviewers, use arrows
to select a rule and Enter to edit it—no condition IDs or JSON needed.
The prefilled form edits source/target branches, reviewers and required approvals.
On the Reviewers field, press Enter to search by name, Space to toggle a
result, and Enter to return to the form. a adds a rule; d deletes the
selected rule. Ctrl+S reviews changes before an explicit y saves them.
J opens advanced JSON. Inherited rules are read-only; advanced branch
matchers and reviewer groups are preserved when changing other fields.
Opening Merge strategies goes straight to its checklist. Use ↑/↓ to choose, Space to allow/block a strategy, and d to choose the default (which also enables it). Select another default before disabling the current one. Use project settings restores inheritance; changing a strategy creates a repository-only override. Ctrl+S reviews, y saves, n returns to editing, and Esc discards. J remains available for advanced JSON.
Other supported Server/Data Center sections open their existing JSON editor; collections use Enter to start editing an item. m sets minimum approvals, and a/d add/remove or enable/disable. e remains a compatibility shortcut. Every write requires confirmation.
Use Tab to switch between sections and details; background colour indicates focus, with a cursor retained for monochrome terminals. In ordinary detail panels, ↑/↓ scroll, PgUp/PgDn page, and Home/End jump to the top or bottom. Switching panes preserves the scroll position. Edit shortcuts also work directly from the sidebar, without pressing Enter first.
bb repo settings get pull-requests -R PROJ/repo
bb repo settings update pull-requests --minimum-approvals 2 -R PROJ/repo
bb repo settings update merge-strategies --file strategies.json -R PROJ/repo
bb repo settings update default-reviewers --id 4 --file condition.json -R PROJ/repo
bb repo settings update default-branch --file branch.json -R PROJ/repo
bb repo settings update permissions-users --id alice --file permission.json -R PROJ/repoResources include details, default-branch, permissions-users,
permissions-groups, branch-restrictions, access-keys, hooks,
hook-settings, pull-requests, merge-strategies, default-reviewers, and
auto-decline. Run bb repo settings update --help for payloads and supported
operations. JSON updates preserve omitted fields; arrays replace existing arrays.
Use --yes only when the change is already authorised; --file - also needs it.
Hook configurations can contain secrets and require --include-sensitive for
CLI reads; they are excluded from overview dumps.
This is not universal Bitbucket GUI parity: Cloud settings are read-only apart from webhooks; HTTP-token creation, reviewer groups, description templates, named required-build policies and plugin-specific administration still require their supported UI/API. Logs are read-only. Repository admins cannot edit project-inherited reviewer conditions here. Server version and permissions can make individual resources unavailable; errors are shown, not hidden.
The merge dialog's b checkbox is off by default. CLI equivalent:
bb pr merge 123 --bypass-checks -y
bb pr recover-merge-checks -R host/PROJ/repoOnly use this with explicit permission to merge and temporarily change repository-wide checks. It snapshots applicable reviewer minima and enabled merge hooks, saves a private recovery journal, disables checks, merges, then restores and verifies settings before retargeting dependent PRs. Source deletion remains a separate opt-in. Inherited merge hooks restore project inheritance; project settings are never changed.
Other PRs can merge during the temporary window; coordinate with administrators.
Normal errors trigger restoration. Process termination, network failure or
restoration failure can require recover-merge-checks, which restores only the
saved settings and never retries the merge. Journals live in the OS user config
directory under bb/merge-recovery; do not delete them before recovery or publish
their contents. Existing journals block another bypass.
Bypass currently supports the verified Westpac Server approver schema on Linux/WSL/macOS. Unknown schemas, unsupported reviewer matchers and inherited reviewer requirements are refused before changes. Cloud and native Windows bypass are unsupported; normal merges remain available. Recovery reapplies the saved baseline, so coordinate any concurrent admin changes first.
Override any TUI key in the PR browser by adding a keybindings block to your
config. Names use the snake-case form of the internal binding (e.g. merge,
approve, edit_target, diff_search_next); values are comma-separated key
strings as accepted by bubbles/key
(e.g. y, shift+m, ctrl+x).
keybindings:
approve: "y, A"
merge: "g"
copy_link: "Y"
diff_search: "ctrl+f"Unknown names produce a single warning toast at startup; the rest of the map is
still applied. Only single-keystroke bindings are supported today (vim-style
sequences like g m are not — yet).
MIT