Metadata-Version: 2.4
Name: lite-bb
Version: 0.1.8
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Rust
License-File: LICENSE
Summary: A gh-style CLI for Bitbucket — PR management for humans, scripts, and LLM agents
Keywords: bitbucket,cli,pull-request,git
License-Expression: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/key4ng/lite-bb
Project-URL: Repository, https://github.com/key4ng/lite-bb

# lite-bb (Lite Bitbucket CLI)

Because sometimes you want `gh`, but your company uses Bitbucket.

`lite-bb` is a lightweight, `gh`-style command-line tool for managing Bitbucket repositories and pull requests. It brings the simplicity and ergonomics of the GitHub CLI to Bitbucket — whether you're on **Bitbucket Cloud** or running **Bitbucket Server / Data Center** on-prem.

Built for developers who live in the terminal, CI/CD pipelines that need scriptable PR workflows, and LLM agents that benefit from structured `--json` output.

## Features

- **Familiar interface** — if you know `gh pr`, you already know `bb pr`. Same commands, same flags, same muscle memory.
- **Cloud + on-prem** — works with both Bitbucket Cloud and Bitbucket Server / Data Center. Auto-detects your instance type from the git remote.
- **Zero-config start** — auto-detects workspace, repo, and branch from your git context. Just `cd` into your repo and go.
- **Repository management** — `bb repo list/view/clone/create` manages repos the same way `gh repo` does.
- **API passthrough** — `bb api <endpoint>` makes authenticated API calls like `gh api`, with `--jq`, `--field`, and `--method` support.
- **Code search** — `bb search code` searches across your workspace or a specific repo, with filters for extension and filename.
- **Machine-readable output** — every command supports `--json` for scripting, piping, and LLM agent consumption.
- **Credential verification** — `bb auth login` validates your token against the API before saving, so you catch auth issues immediately.
- **Easy install** — distributed as a pre-built binary via PyPI. No Rust toolchain needed — just `pip install lite-bb`.

## Install

The recommended way to install `lite-bb` is via pip or uv. This downloads a pre-built native binary for your platform — no Rust toolchain required.

```bash
pip install lite-bb
# or
uv pip install lite-bb
```

After installation, the `bb` command is available on your PATH.

<details>
<summary>Building from source</summary>

If you prefer to build from source, you'll need the Rust toolchain installed:

```bash
cargo install --path crates/cli
```

This compiles and installs the `bb` binary to `~/.cargo/bin/`.
</details>

## Quick Start

```bash
# 1. Authenticate (interactive — choose Cloud or Server, enter token)
bb auth login

# 2. List your repos
bb repo list

# 3. Clone a repo
bb repo clone myworkspace/my-repo

# 4. List open PRs in the current repo
bb pr list

# 5. Create a PR from your current branch
bb pr create --title "feat: add user authentication"

# 6. View PR details (human-readable or JSON)
bb pr view 42
bb pr view 42 --json
```

## Authentication

`lite-bb` supports two authentication methods, matching how Bitbucket handles access:

- **Access Token** — a single token value (workspace, project, or repository token). This is the simplest option, similar to `gh auth login` with a personal access token.
- **App Password** — a username + app password pair. Useful when your organization requires app passwords for API access.

### Interactive Login

```bash
bb auth login
```

This walks you through an interactive setup:
1. Choose your Bitbucket instance — **Cloud** or **Server / Data Center**
2. For Server/DC, enter the server URL (auto-detected from your git remote if available)
3. Choose your credential type — **Access Token** or **App Password**
4. Enter your credentials
5. Credentials are verified against the API before saving

```bash
# Check your current auth status
bb auth status

# Remove saved credentials
bb auth logout
```

### Environment Variables

For CI/CD pipelines and scripting, you can set credentials via environment variables. These take priority over the config file.

| Variable | Description |
|----------|-------------|
| `BB_TOKEN` | Access token (used as Basic auth for Cloud, Bearer for Server/DC) |
| `BB_USERNAME` | Username for app password auth |
| `BB_APP_PASSWORD` | App password (used together with `BB_USERNAME`) |
| `BB_SERVER_URL` | Bitbucket Server/DC base URL (e.g. `https://bitbucket.company.com`) |
| `BB_CONFIG_DIR` | Override the config directory (default: `~/.config/bb/`) |

The config file is stored at `~/.config/bb/config.yml` and respects the `XDG_CONFIG_HOME` environment variable.

## Usage

All commands auto-detect the workspace and repository from your git remote. You can override this with `-R WORKSPACE/REPO` (or `-R PROJECT/REPO` for Server/DC).

### Repositories

```bash
# List repos in your workspace
bb repo list

# List with visibility filter
bb repo list --visibility private

# View a repo
bb repo view myworkspace/my-repo

# Open in browser
bb repo view --web

# Clone a repo (resolves clone URL from API)
bb repo clone myworkspace/my-repo

# Clone into a specific directory, with extra git flags
bb repo clone myworkspace/my-repo ./local-dir -- --depth 1

# Create a new private repo
bb repo create --name my-new-repo --description "My project"

# Create a public repo and clone it immediately
bb repo create --name my-new-repo --public --clone
```

### Listing Pull Requests

```bash
# List open PRs (default)
bb pr list

# Filter by state and limit results
bb pr list --state MERGED --limit 10
bb pr list --state DECLINED --limit 5
```

### Viewing a Pull Request

```bash
# Human-readable summary
bb pr view 42

# JSON output (for scripts, pipes, and LLM agents)
bb pr view 42 --json
```

### Creating a Pull Request

```bash
# Create from current branch (auto-detected) to default branch
bb pr create --title "feat: add login page"

# Specify description
bb pr create --title "feat: add login page" --body "Implements the login page with OAuth support"

# Specify source and destination branches explicitly
bb pr create --title "fix: typo in docs" --head my-branch --base main
```

### Editing a Pull Request

```bash
# Update title
bb pr edit 42 --title "new title"

# Update description
bb pr edit 42 --body "updated description"

# Change destination branch
bb pr edit 42 --base develop
```

### Merging

```bash
# Merge with default strategy
bb pr merge 42

# Merge with a specific strategy and commit message
bb pr merge 42 --strategy squash --message "squash: combine all commits"
```

### Code Review

```bash
# Approve a PR
bb pr review 42 --approve

# Request changes (unapprove)
bb pr review 42 --request-changes
```

### Comments

```bash
# Add a comment to a PR
bb pr comment 42 --body "Looks good! Just one minor suggestion on line 15."
```

### Diffs and CI Checks

```bash
# View the PR diff
bb pr diff 42

# View CI/CD pipeline status
bb pr checks 42

# CI checks as JSON
bb pr checks 42 --json
```

### Searching Code

```bash
# Search across your whole workspace (Cloud) or server (Server/DC)
bb search code "fn main"

# Scope to a specific repo
bb search code "TODO" --repo myworkspace/myrepo

# Scope to a personal repo (Server/DC)
bb search code "TODO" --repo ~username/myrepo

# Filter by file extension or filename
bb search code "import requests" --extension py
bb search code "Makefile" --filename Makefile

# Limit results (default: 30)
bb search code "error handling" --limit 10

# JSON output for scripts and agents
bb search code "apiKey" --json
```

Results show the file path, repository, and matching lines. Lines that directly match the query are highlighted with a `>` prefix.

### Branch Operations

```bash
# Checkout a PR branch locally (fetches and switches)
bb pr checkout 42

# Close (decline) a PR
bb pr close 42

# Reopen a previously declined PR
bb pr reopen 42
```

### API Passthrough

Make raw authenticated requests to the Bitbucket API — the equivalent of `gh api`.

```bash
# GET a resource (pretty-printed JSON by default)
bb api repositories/myworkspace/myrepo

# Read a file from a repo
bb api projects/GENAICORE/repos/ome/raw/config/runtimes/srt/deepseek-r1-rdma-rt.yaml

# Filter JSON output with jq
bb api projects/GENAICORE/repos/ome -q '.slug'
bb api repositories/myworkspace/myrepo/pullrequests -q '[.values[].title]'

# POST with a JSON body built from fields
bb api repositories/myworkspace/myrepo/pullrequests -X POST \
  -F title="My PR" -F description="Fixes the bug"

# POST with a raw JSON body
bb api rest/search/latest/search -X POST \
  --input '{"query":"deepseek","entities":{"code":{"start":0,"limit":3}}}' \
  -q '.code.values[].file'

# Add custom headers
bb api some/endpoint -H 'X-Custom: value'
```

**Base URLs used:**
- Cloud: `https://api.bitbucket.org/2.0`
- Server/DC: your server root (so `/rest/api/1.0/`, `/rest/search/latest/`, etc. are all reachable)

| Flag | Description |
|------|-------------|
| `-X`/`--method` | HTTP method (default: `GET`) |
| `-F key=value` | Add a JSON body field; auto-typed. Repeat for multiple. |
| `--input JSON` | Raw JSON body string (overrides `-F`) |
| `-H 'Key: Value'` | Add a request header. Repeat for multiple. |
| `-q filter` | Pipe response through `jq` (requires `jq` in PATH) |
| `--raw` | Print response as-is without JSON formatting |

## Command Reference

| Command | Description |
|---------|-------------|
| `bb repo list [owner]` | List repositories in a workspace or project |
| `bb repo view [REPO]` | View repository details |
| `bb repo clone REPO [dir]` | Clone a repository locally |
| `bb repo create` | Create a new repository |
| `bb auth login` | Authenticate with Bitbucket (Cloud or Server/DC) |
| `bb auth logout` | Remove saved credentials |
| `bb auth status` | Show current auth info and provider |
| `bb pr list` | List pull requests (filterable by state) |
| `bb pr view <id>` | View pull request details |
| `bb pr create` | Create a new pull request |
| `bb pr edit <id>` | Edit title, description, or destination branch |
| `bb pr merge <id>` | Merge a pull request |
| `bb pr close <id>` | Decline / close a pull request |
| `bb pr reopen <id>` | Reopen a declined pull request |
| `bb pr review <id>` | Approve or request changes |
| `bb pr comment <id>` | Add a comment to a pull request |
| `bb pr diff <id>` | View the pull request diff |
| `bb pr checks <id>` | View CI/CD status checks |
| `bb pr checkout <id>` | Fetch and checkout the PR branch locally |
| `bb search code <query>` | Search code across workspace or a specific repo |
| `bb api <endpoint>` | Make an authenticated API request |

## Bitbucket Server / Data Center

`lite-bb` fully supports Bitbucket Server and Data Center (on-prem) installations. The CLI automatically adapts its API calls, authentication method, and URL structure based on your configured provider.

**Key differences handled automatically:**

- **API endpoints** — Cloud uses `/2.0/repositories/{workspace}/{repo}`, Server/DC uses `/rest/api/1.0/projects/{project}/repos/{repo}`
- **Authentication** — Cloud tokens use Basic auth with `x-token-auth`, Server/DC personal access tokens use Bearer auth
- **Pagination** — Cloud uses `page/pagelen`, Server/DC uses `start/limit`
- **Diff format** — Cloud returns raw unified diff, Server/DC returns structured JSON (converted to unified diff automatically)
- **Git remotes** — parses both Cloud (`bitbucket.org`) and Server/DC remote URL formats (SSH with port, HTTPS with `/scm/` prefix, SCP-style)

No special flags are needed — just configure your server URL during `bb auth login` or via `BB_SERVER_URL`, and all commands work the same way.

## Development

```bash
cargo build            # build the CLI binary
cargo test             # run all unit tests
cargo run -- pr list   # run the CLI directly without installing
```

## License

MIT

