bb-bash — Bitbucket Cloud CLI para Agentes IA
restarter/bb-bash
CLI Bitbucket zero-config para agentes IA — gerenciar PRs direto do terminal
Ver no GitHubCLI bash single-file para Bitbucket Cloud, otimizado para agentes de código IA. Detecta repositório automaticamente, gerencia pull requests (criar, revisar, aprovar, mesclar) via terminal ou chat, sem configuração por projeto. Inclui snippets para Claude Code, Rules, Skills e integração nativa com agentes IA populares.
Instalação
npx convez-ai restarter/bb-bash1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automação de fluxo de pull requests em projetos Bitbucket
- Integração com agentes IA (Claude Code, Cursor, Copilot) para revisão de código
- Comentários inline e aprovação/rejeição de PRs sem sair do editor
- CI/CD e DevOps — gerenciar PRs programaticamente em pipelines
Veredito

Ferramenta bem pensada para quem usa Bitbucket Cloud com agentes IA. Zero-config e single-file tornam instalação trivial; integração nativa (Rules, Skills, snippets) elimina wiring manual. Público específico (Bitbucket + IA agents) mas execução sólida.
README
A tradução para o português deste README ainda está na fila.
bb-bash (bbb)
Bitbucket Cloud CLI built for AI coding agents — single-file bash with zero-config repo auto-detect and inline PR review, plus
CLAUDE.mdsnippet, Rule, and Skill bundled out of the box.
bbb (the binary) wraps the Bitbucket Cloud REST API 2.0 so you and your AI agent can drive PR review, inline comments, approve, decline, merge, and create — all from chat or terminal, without leaving your editor. cd into any Bitbucket-Cloud-backed repo and run bbb pr list — workspace/repo are auto-detected from git remote, no per-project setup. No build step, no package manager: one bash script, two dependencies (curl, jq).
The drop-in artifacts (CLAUDE.md / AGENTS.md snippets + Claude Code Rule + Claude Code Skill) teach the AI agents you already use (Claude Code, Cursor, Copilot Chat, Codex, Aider, …) how to call bbb — no manual wiring. See For AI agents for what each artifact does.
Install
curl --proto '=https' --tlsv1.2 -fsSL \
https://raw.githubusercontent.com/restarter/bb-bash/main/scripts/install.sh | bash
Re-run the same command to update; your .env is never touched.
Manual install, env-var overrides, and security-inspection one-liner: see docs/installation.md.
Setup
1. Create a Bitbucket API token
Go to https://id.atlassian.com/manage-profile/security/api-tokens. Required scopes:
read:repository:bitbucketread:pullrequest:bitbucketwrite:pullrequest:bitbucketread:pipeline:bitbucket— optional, only forbbb pr checksto show Bitbucket Pipelines; gracefully omitted otherwise
2. Configure credentials
Edit ~/.local/share/bb-bash/.env:
BB_BASH_EMAIL="you@example.com"
BB_BASH_TOKEN="<api-token>"
Workspace/repo are auto-detected from git remote. Override with BB_BASH_WORKSPACE + BB_BASH_REPO (outside a git repo) or BB_BASH_REMOTE=<name> to pick a specific remote.
For AI agents
Run bbb install-agent inside your project — or with --global for every project at once — to drop integration artifacts so the AI agents you already use (Claude Code, Cursor, Copilot Chat, Codex, Aider, …) know how to call bbb without extra prompting.
Flags
| Flag | Purpose |
|---|---|
--rule / --skill / --claude / --agents | Pick the artifact(s) to install — see the table below |
--global | Install into ~/.claude/ instead of the current project; Claude Code auto-loads from there in every project. Works with --rule / --skill / --claude. --agents is project-only — no widely-adopted global path for AGENTS.md. |
--dry-run | Preview the writes without touching disk |
--force | Overwrite an existing artifact (default is skip-if-exists) |
Pin to a release tag for reproducibility: BB_BASH_REF=v0.2.0 bbb install-agent .... Full flag reference: docs/commands.md#install-agent.
Examples
bbb install-agent --claude # snippet → ./CLAUDE.md (any CLAUDE.md-reading agent)
bbb install-agent --rule --skill # Claude Code: rule (always-on) + skill (on-demand)
bbb install-agent --rule --global # global rule — auto-loaded in every project
bbb install-agent --rule --skill --global # global rule + skill (Claude Code combo)
bbb install-agent --claude --dry-run # preview without writing
What ships out of the box
Pick any one — each artifact is fully self-contained. Your AI agent gets the same end result (install hint, auth, commands, conventions, workflows). Choose by your tool / preference; combine if you want.
| Type | Project install | Global (--global) | Loading | Best for |
|---|---|---|---|---|
CLAUDE.md | ./CLAUDE.md | ~/.claude/CLAUDE.md | every turn | Claude / Cursor / Copilot via CLAUDE.md |
AGENTS.md | ./AGENTS.md | — (project-only) | every turn | cross-tool agents (OpenAI Codex, Aider, Continue, …) |
| Rule | ./.claude/rules/bb-bash-rule.md | ~/.claude/rules/bb-bash-rule.md | session start | short always-on hint, "bbb exists, here's how" |
| Skill | ./.claude/skills/bb-bash/SKILL.md | ~/.claude/skills/bb-bash/SKILL.md | on-demand | full workflows (review, respond, batch cleanup); zero context cost until invoked |
Browse the artifact sources directly: docs/agents/ (README).
Then ask your agent things like
- "Review PR #42 — leave inline comments on anything risky, then summarize."
- "List open PRs by alice."
- "Approve PR #12 and merge with
--squash --delete-branch." - "Reply to comment 753926626 on PR #42 with: 'Good catch, fixed.'"
The agent already knows the commands because the install dropped a Rule + Skill into .claude/, plus a ## Bitbucket via bb-bash section into your CLAUDE.md / AGENTS.md.
Commands
# From inside any bitbucket.org repo:
bbb pr list # open PRs (default)
bbb pr list --state=merged --author=alice
bbb pr show 42
bbb pr diff 42
bbb pr checks 42 # CI + pipelines status
bbb pr comments 42 # general + inline comments
bbb pr comment 42 "general comment"
bbb pr inline 42 src/auth.ts 30 "consider extracting"
bbb pr inline --old 42 src/auth.ts 10 "this was important"
bbb pr reply 42 753926626 "Good point, fixed"
bbb pr edit-comment 42 753926626 "Updated text"
bbb pr delete-comment 42 753926626
bbb pr approve 42 # single
bbb pr approve 42 43 44 # batch
bbb pr decline 99 100 # batch close-without-merge
bbb pr merge 42 --squash --delete-branch
bbb pr create main "Title" "Description"
bbb pr update 42 --title="New title"
bbb pr open 42 # opens in browser
bbb raw "/pullrequests"
bbb raw-post "/pullrequests/42/comments" '{"content":{"raw":"test"}}'
Full command reference: docs/commands.md.
Inline comments
Two modes depending on which side of the diff you're commenting on:
| Command | inline field | Use case |
|---|---|---|
bbb pr inline <id> <path> <line> <text> | "to": <line> | new / modified code |
bbb pr inline --old <id> <path> <line> <text> | "from": <line> | deleted / old code |
Line numbers are real file line numbers, not diff line numbers.
How auto-detect works
bbb resolves workspace/repo per invocation. See docs/design.md for the authoritative precedence chain. tl;dr:
-
Inside a
bitbucket.orggit repo → workspace/repo derived fromorigin(or first matching remote). -
Outside a git repo, or for one-off overrides → set env vars:
BB_BASH_WORKSPACE=mycompany BB_BASH_REPO=myproject bbb pr list -
Override which remote auto-detect uses:
BB_BASH_REMOTE=bb bbb pr list # use 'bb' remote instead of 'origin'
Limitations
- Bitbucket Cloud only — no Bitbucket Server / Data Center.
- No pending / draft comments — Bitbucket's "Start review" batching is web-UI only; the API publishes every comment immediately.
pr list --reviewer=<user>not supported — Bitbucket BBQL doesn't exposereviewers.usernamefiltering. Workaround: pipebbb pr listthroughjq. Tracked inbb-bash-oja.pr update --reviewers=u1,u2uses usernames — Bitbucket has been deprecating usernames as stable identifiers. Migration toaccount_id/uuidtracked inbb-bash-oja.
Authentication
Basic Auth with email:api-token (Bitbucket required this format since Sept 2025; old App Passwords disabled June 2026).
Security
bbb sources .env directly, so shell metacharacters in values execute on every invocation. Keep .env to plain KEY=value lines — no backticks, no $(...), no unmatched quotes. Switching to a safe parser is tracked as a follow-up.
For inspecting install.sh before running it, see docs/installation.md#security-inspection.
API reference
- Bitbucket REST API: https://developer.atlassian.com/cloud/bitbucket/rest/
- Pull Requests endpoint: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-pullrequests/
Contributing
See docs/contributing.md.
Changelog
See CHANGELOG.md.