Installation

There are two ways to install bb:

• Standalone binary: one self-contained executable per platform, attached to each GitHub Release since v2.2.0. Needs no Bun, Node.js or npm.
• Package manager: the npm package, which runs on the Bun runtime.

Either way, bb needs Git to detect the workspace and repository of the current directory.

Standalone binary

Install script

The install script picks the binary for your platform, checks it against the release’s SHA256SUMS and installs it:

Linux and macOS

curl -fsSL https://github.com/0pilatos0/bitbucket-cli/releases/latest/download/install.sh | sh

Installs to ~/.local/bin/bb. Add that folder to your PATH if the script says it is missing.

Windows

irm https://github.com/0pilatos0/bitbucket-cli/releases/latest/download/install.ps1 | iex

Installs to %LOCALAPPDATA%\Programs\bb\bb.exe and adds that folder to your user PATH, for the current terminal and new ones.

Run the script again to update. These environment variables change what it does:

Variable	Effect
BB_VERSION	Install this version, e.g. 2.2.0, instead of the latest release
BB_INSTALL_DIR	Install into this folder. On Windows, PATH is then left to you
BB_RELEASES_URL	Download from a mirror of https://github.com/0pilatos0/bitbucket-cli/releases

For example, to install for all users:

curl -fsSL https://github.com/0pilatos0/bitbucket-cli/releases/latest/download/install.sh | sudo env BB_INSTALL_DIR=/usr/local/bin sh

Manual download

Platform	Binary	Archive
Linux x64	bb-linux-x64	bb-linux-x64.tar.gz
Linux arm64	bb-linux-arm64	bb-linux-arm64.tar.gz
macOS Intel	bb-darwin-x64	bb-darwin-x64.tar.gz
macOS Apple silicon	bb-darwin-arm64	bb-darwin-arm64.tar.gz
Windows x64	bb-windows-x64.exe	bb-windows-x64.zip

The archives hold the same binary, named bb (bb.exe on Windows), plus the license, and are less than half the download. Releases before they were added only have the raw binaries.

Each release also ships SHA256SUMS covering binaries and archives. Download the binary and the checksums, verify, then put the binary on your PATH:

Linux

asset=bb-linux-x64  # or bb-linux-arm64
base=https://github.com/0pilatos0/bitbucket-cli/releases/latest/download
curl -fsSLO "$base/$asset"
curl -fsSLO "$base/SHA256SUMS"
sha256sum --check --ignore-missing SHA256SUMS
chmod +x "$asset"
sudo mv "$asset" /usr/local/bin/bb

macOS

asset=bb-darwin-arm64  # or bb-darwin-x64
base=https://github.com/0pilatos0/bitbucket-cli/releases/latest/download
curl -fsSLO "$base/$asset"
curl -fsSLO "$base/SHA256SUMS"
shasum -a 256 --check --ignore-missing SHA256SUMS
chmod +x "$asset"
sudo mv "$asset" /usr/local/bin/bb

Windows

$base = "https://github.com/0pilatos0/bitbucket-cli/releases/latest/download"
Invoke-WebRequest "$base/bb-windows-x64.exe" -OutFile bb-windows-x64.exe
Invoke-WebRequest "$base/SHA256SUMS" -OutFile SHA256SUMS
$expected = (Select-String -Path SHA256SUMS -SimpleMatch "bb-windows-x64.exe").Line.Split(" ")[0]
if ((Get-FileHash bb-windows-x64.exe -Algorithm SHA256).Hash -ne $expected) { throw "checksum mismatch" }
Move-Item bb-windows-x64.exe bb.exe

Move bb.exe to a folder on your PATH.

To pin a version, replace latest/download with download/v<version>.

Verify provenance

Every binary and archive carries a build provenance attestation that proves it was built by this repository’s release workflow. Check it with the GitHub CLI:

gh attestation verify bb-linux-x64 --repo 0pilatos0/bitbucket-cli

Note

The Linux binaries need glibc. On musl-based images such as Alpine, use the npm package with Bun instead.

The macOS binaries are not notarized. curl downloads run as-is; if you downloaded one through a browser, clear the quarantine flag first: xattr -d com.apple.quarantine bb.

Package manager

The npm package runs on the Bun runtime 1.1.30 or newer, not Node.js. Install Bun if bun --version fails:

curl -fsSL https://bun.sh/install | bash

On Windows, --jq requires Bun 1.4.2 or newer. With Bun 1.3.14, it can print the result and then fail to exit.

For other platforms and install methods, see bun.sh. Then install the CLI with any package manager:

Caution

npm and pnpm install bb without Bun. If Bun is missing, bb fails before it starts with an error that bun was not found, such as env: bun: No such file or directory. See Troubleshooting for the other forms. Install Bun, or use the standalone binary.

npm

npm install -g @pilatos/bitbucket-cli

pnpm

pnpm add -g @pilatos/bitbucket-cli

Bun

bun install -g @pilatos/bitbucket-cli

Build from source

# Clone the repository
git clone https://github.com/0pilatos0/bitbucket-cli.git
cd bitbucket-cli

# Install dependencies
bun install

# Build
bun run build

# Link globally
bun link

Verify installation

bb --version

Update

Update bb the same way you installed it.

• Standalone binary: repeat the download steps and replace the old binary. They fetch the latest release.

• Package manager: install the latest version with the package manager you used: npm install -g @pilatos/bitbucket-cli@latest, pnpm add -g @pilatos/bitbucket-cli@latest, or bun install -g @pilatos/bitbucket-cli@latest.

• Built from source: pull and rebuild in your clone. The bun link from the first install still points at it.

  git pull
  bun install
  bun run build

Run bb --version to confirm the new version.

Uninstall

Sign out and remove shell completion first, while bb is still installed:

bb auth logout           # revokes an OAuth token and deletes stored credentials
bb completion uninstall  # only if you installed completion

bb auth logout does not revoke API tokens. Delete those in your Bitbucket API token settings.

Then remove the CLI:

• Standalone binary: delete the binary, for example sudo rm /usr/local/bin/bb, or bb.exe on Windows.
• Package manager: npm uninstall -g @pilatos/bitbucket-cli, pnpm remove -g @pilatos/bitbucket-cli, or bun remove -g @pilatos/bitbucket-cli.
• Built from source: run bun unlink in your clone, then delete the clone.

Finally, delete the configuration directory, which holds your settings and aliases: ~/.config/bb on macOS and Linux, %APPDATA%\bb on Windows.

Next steps

Authenticate with your Bitbucket account.

Then install shell completion so your shell can complete bb subcommands and flags.