bbdc-cli 0.3.1

Typer CLI for Bitbucket Data Center

bbdc-cli

A small, practical Typer CLI for Bitbucket Data Center / Server REST API.

It reads credentials from environment variables and provides high-signal PR workflows (list, create, comment, approve, merge, update metadata, manage reviewers/participants, review completion, diffs, etc.) without needing a full SDK.

Requirements

• Python 3.9+
• pipx recommended for isolated install

Install

From PyPI:

pipx install bbdc-cli
# or
pip install bbdc-cli

From source (repo root with pyproject.toml):

pipx install .

# If you are iterating locally:
pipx install -e .

# Reinstall after changes (non-editable install):
pipx reinstall bbdc-cli

# Uninstall:
pipx uninstall bbdc-cli

Configuration

The CLI uses two environment variables:

• BITBUCKET_SERVER: base REST URL ending in /rest
• BITBUCKET_API_TOKEN: Bitbucket personal access token (PAT)

Example (BBVA-style context path):

https://bitbucket.globaldevtools.bbva.com/bitbucket/rest

Set them:

export BITBUCKET_SERVER="https://bitbucket.globaldevtools.bbva.com/bitbucket/rest"
export BITBUCKET_API_TOKEN="YOUR_TOKEN"

Quick check

bbdc doctor

If this succeeds, your base URL + token are working.

Common commands

Show help:

bbdc --help
bbdc pr --help

List pull requests:

bbdc pr list --project GL_KAIF_APP-ID-2866825_DSG --repo mercury-viz

Get a pull request:

bbdc pr get -p GL_KAIF_APP-ID-2866825_DSG -r mercury-viz 123

Create a pull request:

bbdc pr create \
  --project GL_KAIF_APP-ID-2866825_DSG \
  --repo mercury-viz \
  --from-branch feature/my-branch \
  --to-branch develop \
  --title "Add viz panel" \
  --description "Implements X"

Add reviewers (repeat --reviewer):

bbdc pr create \
  -p GL_KAIF_APP-ID-2866825_DSG \
  -r mercury-viz \
  --from-branch feature/my-branch \
  --to-branch develop \
  --title "Add viz panel" \
  --description "Implements X" \
  --reviewer some.username \
  --reviewer other.username

Approve, decline, merge:

bbdc pr approve -p GL_KAIF_APP-ID-2866825_DSG -r mercury-viz 123
bbdc pr decline -p GL_KAIF_APP-ID-2866825_DSG -r mercury-viz 123 --comment "Not proceeding"
bbdc pr merge -p GL_KAIF_APP-ID-2866825_DSG -r mercury-viz 123 --message "LGTM"

Update metadata:

bbdc pr update -p GL_KAIF_APP-ID-2866825_DSG -r mercury-viz 123 \
  --title "New title" \
  --description "Updated description" \
  --reviewer some.username

Participants / reviewers:

bbdc pr participants list -p GL_KAIF_APP-ID-2866825_DSG -r mercury-viz 123
bbdc pr participants add -p GL_KAIF_APP-ID-2866825_DSG -r mercury-viz 123 --user alice --role REVIEWER
bbdc pr participants status -p GL_KAIF_APP-ID-2866825_DSG -r mercury-viz 123 alice --status APPROVED

Review completion and comments:

bbdc pr review complete -p GL_KAIF_APP-ID-2866825_DSG -r mercury-viz 123 --comment "Looks good" --status APPROVED
bbdc pr comments add -p GL_KAIF_APP-ID-2866825_DSG -r mercury-viz 123 --text "LGTM"

Diffs and commits:

bbdc pr commits -p GL_KAIF_APP-ID-2866825_DSG -r mercury-viz 123
bbdc pr diff -p GL_KAIF_APP-ID-2866825_DSG -r mercury-viz 123
bbdc pr diff-file -p GL_KAIF_APP-ID-2866825_DSG -r mercury-viz 123 src/main.py

See the full command reference in docs/CLI.md and usage examples in docs/examples.md.

Troubleshooting

BITBUCKET_SERVER must end with /rest.

Use the REST base, not the UI URL. For instances hosted under /bitbucket, the REST base is often:

• UI: https://host/bitbucket/...
• REST: https://host/bitbucket/rest

Unauthorized / 401 / 403:

• Token missing or incorrect
• Token lacks required permissions for that project/repo
• Your Bitbucket instance may require a different auth scheme (rare if PAT is enabled)

404 Not Found:

Usually one of:

• Wrong BITBUCKET_SERVER base path (/rest vs /bitbucket/rest)
• Wrong --project key or --repo slug
• PR id does not exist in that repo

Development

Run without installing:

python -m bbdc_cli --help
python -m bbdc_cli doctor

License

Mercury - BBVA