Metadata-Version: 2.4
Name: bb-tool
Version: 1.0.1
Summary: Bitbucket Cloud CLI for PR review workflows
License-Expression: MIT
Project-URL: Homepage, https://github.com/alipga/bb-cli
Project-URL: Repository, https://github.com/alipga/bb-cli
Project-URL: Issues, https://github.com/alipga/bb-cli/issues
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Version Control
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Requires-Dist: click>=8.1
Requires-Dist: keyring>=25.0
Requires-Dist: rich>=13.0
Dynamic: license-file

# bb

**`gh` for GitHub. `bb` for Bitbucket.** The missing command-line tool for Bitbucket Cloud pull requests.

[![PyPI](https://img.shields.io/pypi/v/bb-tool)](https://pypi.org/project/bb-tool/)
[![Python](https://img.shields.io/pypi/pyversions/bb-tool)](https://pypi.org/project/bb-tool/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

<!-- TODO: Add terminal screenshot/GIF here showing `bb pr list` output -->

## Why bb?

GitHub has `gh`. GitLab has `glab`. **Bitbucket Cloud has nothing** — until now.

If you use Bitbucket at work, you know the pain: context-switch to the browser to check PRs, post review comments, merge branches. `bb` lets you do all of that from the terminal, in the repo you're already working in.

- **Zero config** — auto-detects workspace and repo from your git remote
- **Full PR lifecycle** — list, create, review, comment, approve, merge
- **Inline code comments** — comment on specific files and lines
- **Threaded discussions** — reply to and resolve comment threads
- **JSON output** — pipe to `jq` for scripting and automation
- **AI-ready** — ships with a Claude Code skill for AI-assisted PR reviews

## Quick Start

```bash
pip install bb-tool
bb setup        # authenticates + installs Claude Code skill
bb pr list
```

That's it. `bb setup` walks you through creating an API token (opens your browser), then installs the Claude Code skill. If you're in a Bitbucket repo, `bb` auto-detects your workspace and repo.

### 60-second workflow: review a PR from your terminal

```bash
# See what's open
bb pr list

# Pick a PR and get the overview
bb pr show 42
bb pr files 42

# Read the diff
bb pr diff 42

# Leave a comment on a specific line
bb pr comment 42 --body "This should use a context manager" --file src/db.py --line 15

# Approve and merge
bb pr approve 42
bb pr merge 42 --strategy squash --close-source
```

## Installation

```bash
# pip
pip install bb-tool

# pipx (isolated install, recommended)
pipx install bb-tool

# uv
uv tool install bb-tool
```

Requires Python 3.10+.

## Authentication

`bb` uses [Atlassian API tokens](https://id.atlassian.com/manage-profile/security/api-tokens) for authentication. Create a token with the following scopes:

**Read:** `read:me`, `read:pullrequest:bitbucket`, `read:repository:bitbucket`, `read:project:bitbucket`, `read:user:bitbucket`

**Write:** `write:pullrequest:bitbucket`

```bash
bb auth login    # Opens browser to create a token, then prompts for credentials
bb auth status   # Verify credentials
bb auth logout   # Clear stored credentials
```

Credentials are stored in your system keyring. If keyring is unavailable, they fall back to `~/.config/bb/tokens.json` (file mode `600`).

## Configuration

In most cases, you don't need any configuration — `bb` reads your git remote.

### Config file (optional)

Create `~/.config/bb/config.toml` to set defaults:

```toml
[defaults]
workspace = "myworkspace"
repo = "myrepo"
dest_branch = "main"
```

### Environment variables

Override anything with env vars (highest priority):

- `BITBUCKET_WORKSPACE` — workspace slug
- `BITBUCKET_REPO` — repository slug
- `BITBUCKET_DEST_BRANCH` — default destination branch for `pr create`

**Resolution order:** env vars > config file > git remote

## Commands

### Pull Requests

```bash
bb pr list                              # List open PRs
bb pr list --state MERGED --limit 10    # Filter and limit
bb pr list --json                       # JSON output (pipe to jq)

bb pr show 42                           # PR details
bb pr show 42 --json                    # JSON output
bb pr files 42                          # Changed files with line counts
bb pr diff 42                           # Full unified diff

bb pr create -t "Add feature X"        # Create from current branch
bb pr create -t "Fix" -s feat -d main  # Explicit branches
bb pr create -t "Update" --body "..."  # With description
bb pr create -t "Fix" --reviewer alice # Add reviewers

bb pr approve 42                        # Approve a PR
bb pr merge 42                          # Merge a PR
bb pr merge 42 --strategy squash       # Squash merge
bb pr merge 42 --close-source          # Delete source branch after merge
```

### Comments

```bash
bb pr comments 42                                           # List all (threaded)
bb pr comment 42 --body "Looks good"                        # General comment
bb pr comment 42 --body "Nit" --file src/main.py --line 15  # Inline comment
bb pr reply 42 --comment-id 123 --body "Fixed"              # Reply to thread
bb pr resolve 42 --comment-id 123                           # Resolve thread
```

### Workspace/Repo Override

All `pr` subcommands accept `-w` and `-r` flags:

```bash
bb pr -w myteam -r backend list
bb pr -w myteam -r backend show 99
```

## Claude Code Integration

`bb` ships with a [Claude Code](https://claude.com/claude-code) skill for AI-assisted PR review workflows:

```bash
bb setup-skill   # installs to ~/.claude/skills/bb/
```

This is included automatically when you run `bb setup`. Once installed, Claude can list PRs, read diffs, post review comments, and manage threads on your behalf.

## Contributing

Contributions are welcome! Please open an issue or submit a pull request.

## License

[MIT](LICENSE)
