bb: what it takes to build gh for Bitbucket
- Objective
- A loopback OAuth dance, a file lock around rotating refresh tokens, byte-offset log tailing, and the surprising amount of work hiding in "brew install". The inside story of bb.
- Date
- · 4 min read
- Apparatus
- goclibitbucketclaude-codeshipped
- Experiment
- EXP-004 · bb
- Observer
- RC · Berlin
This is the story behind bb, my Bitbucket Cloud CLI.
GitHub has gh. You create a PR, watch CI and check out a teammate’s branch without leaving your terminal. For years Bitbucket Cloud had nothing that felt the same, so every pull request meant a trip to the browser. I wanted to know how much of gh’s magic comes from its design and how much from GitHub itself.
The answer: nearly all of it is design. And design turns out to be a lot of small, careful decisions.
bb pr create --title "Fix login bug" --base main
bb pipeline watch --notify
bb status
Copy the grammar, not just the features
bb is laid out like gh on purpose: a cmd/ entry point, a pkg/cmd/ tree with one package per noun, and a shared Factory carrying I/O streams, the HTTP client, config and the current workspace into every command. The command framework is Cobra, and there are 22 top-level groups: pr, repo, pipeline, issue, branch and so on.
Copying gh’s grammar (bb <noun> <verb> --flags) is the kindest thing you can do for users. Anyone who knows gh already knows bb.
Logging in: a tiny web server on your laptop
“Login with your browser” looks like magic. Here’s the trick:
bbstarts a web server on127.0.0.1on a random free port.- It opens Bitbucket’s authorize page, with that loopback address as the redirect and a random
statevalue to prevent CSRF. - You click Grant access, and Bitbucket redirects your browser to
127.0.0.1:<port>/callback?code=…, which isbbitself. bbchecks thatstatematches, swaps the code for tokens and shuts the server down. It gives up after five minutes.
For CI there’s no browser, so bb auth login --with-token reads a token from stdin. There is a --token flag, but it prints a warning, because anything you type as an argument lands in your shell history.
The race condition you only find in docs
Bitbucket rotates refresh tokens: every refresh returns a new refresh token and invalidates the old one. Picture two bb commands running at once, say one in your editor and one in a terminal. Both notice the access token expired and both refresh. One wins, and the other just burned a now-invalid token. You’re logged out for no visible reason.
The fix is a file lock (gofrs/flock) around the entire read → refresh → write cycle. The token file itself is written atomically: a temp file with a random name, then a rename, with 0600 permissions. There’s a test that fires ten goroutines at the refresh path at once to prove it holds.
Watching a pipeline without a streaming API
bb pipeline watch feels live, but Bitbucket has no streaming log API. It’s polling, done politely:
- It polls every 10 seconds by default and never faster than 5.
- It tracks a byte offset per step, so each poll fetches only the new part of the log instead of the whole thing again.
- It warns you as you get closer to Bitbucket’s 1,000-requests-per-hour limit.
- A 429 response triggers exponential backoff (2 s → 30 s, three tries) in the HTTP transport, so no command has to think about it.
--notify then pops a real desktop notification when the pipeline finishes: AppleScript on macOS, notify-send on Linux and a PowerShell balloon tip on Windows. It’s three OSes and three completely different mechanisms, all fire-and-forget.
Small conveniences that add up
- PR descriptions write themselves. Without
--body,bbuses your repo’s PR template. If there isn’t one, it runsgit log base..HEAD: one commit becomes the body, and several become a## Changeslist. If your branch name contains a Jira key likePROJ-123, it addsRelated: PROJ-123. - It knows where you are. It parses your git remote (SSH or HTTPS), so most commands need no
--workspace. bb statusis a personal dashboard across your repos: open PRs, issues and pipeline failures from the last day. It fans out five requests at a time so it doesn’t eat your rate limit.- Extensions work like
gh extension: git repos that become new top-level commands.
The part nobody sees: distribution
Writing the CLI was half the work. The other half was making brew install just work.
GoReleaser builds static binaries for macOS, Linux and Windows, and merges the macOS Intel and ARM builds into one universal binary. It produces .tar.gz and .zip archives with shell completions, .deb and .rpm packages that install those completions system-wide, a Homebrew cask in my tap, a Scoop manifest in my bucket and a checksum file. A curl installer covers everything else. Pushing a v* tag runs the whole thing.
Users judge a CLI in the first thirty seconds, and most of those seconds are installation.
Built with an agent, honestly
I built bb with Claude Code, and I’m not shy about it. The repo keeps the brainstorms and plans, a CLAUDE.md, and a note that the whole thing took about 35 conversation turns and roughly $30–45 of model time. My job was the part agents can’t do for you: deciding what gh-like should mean, noticing the refresh-token race, insisting on the file lock and the tests, and caring about the install experience.
That’s the part I find most interesting about building software in 2026. The typing got cheap. Taste and judgement didn’t.
What’s still rough
- No PKCE in the OAuth flow yet. My own code comment says I couldn’t confirm Bitbucket supports it.
- Tokens live in a
0600JSON file, not the OS keychain. - No signed releases, only checksums.
--draftdoes nothing, because Bitbucket’s API has no draft PRs.
If you live in Bitbucket, give it a try: brew install chandrasekar-r/tap/bb. The source is at github.com/chandrasekar-r/bitbucket-cli.