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 token (PAT or HTTP access token)

BBVA note:

• Most users will authenticate with Project/Repository HTTP access tokens.
• Those tokens usually work for repository/project workflows, but some user-account endpoints can return 401.

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
# machine-readable output
bbdc doctor --json

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

Optional (for account profile/settings lookups):

• BITBUCKET_USER_SLUG: your Bitbucket user slug

Common commands

Show help:

bbdc --help
bbdc account --help
bbdc dashboard --help
bbdc pr --help

Get information about your authenticated account:

# consolidated snapshot (recent repos + SSH keys + GPG keys)
bbdc account me

# if some account endpoints are not permitted with your token,
# account me still returns partial JSON with "partial" + "errors"
bbdc account me

# account me is JSON by default; there is no --json flag
# (use: bbdc account me)

# include user profile and settings when your slug is known
bbdc account me --user-slug your.user --include-settings

# raw account endpoint calls
bbdc account recent-repos
bbdc account ssh-keys
bbdc account gpg-keys
bbdc account user --user-slug your.user
bbdc account settings --user-slug your.user

Inspect dashboard pull requests:

# pull requests where you are involved (author/reviewer/participant)
bbdc dashboard pull-requests

# filter by role/state
bbdc dashboard pull-requests --role REVIEWER --state OPEN

# return JSON
bbdc dashboard pull-requests --json

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"

Batch operations

Batch commands live under bbdc pr batch ... and read a JSON list of items from --file (or - for stdin). You can provide --project and --repo as defaults for each item.

Example batch approvals (approve.json):

[
  {"pr_id": 123},
  {"pr_id": 456}
]

bbdc pr batch approve -p GL_KAIF_APP-ID-2866825_DSG -r mercury-viz -f approve.json

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.

Codex integration

If teammates will use this through Codex with natural language:

1. Distribute this CLI through PyPI (bbdc-cli).
2. Distribute the Codex skill separately (for example, git repo cloned into $CODEX_HOME/skills/bbdc-cli).
3. Keep the skill's command inventory synced with this repo's bbdc_cli/__main__.py.

Recommended split of responsibilities:

• This repo: command behavior, API semantics, package distribution.
• Skill repo: natural-language intent mapping, execution policy, Codex-specific prompting.

This separation is the correct approach and avoids coupling Codex behavior to package release timing.

Codex runtime execution caveat

For this BBVA infrastructure, assume Codex runtimes cannot execute bbdc against Bitbucket (DNS/VPN/network constraints), even though the same command works on the user's machine.

Typical error:

• Request failed: HTTPSConnectionPool(... NameResolutionError ... Failed to resolve ...)

Recommended workflow in Codex:

1. Codex generates exact bbdc commands.
2. User runs commands locally in their terminal.
3. User shares output back to Codex for analysis or next steps.

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)
• In BBVA, Project/Repository HTTP access tokens may return 401 on user-account endpoints (account ssh-keys, account gpg-keys, account user, account settings)
• account me now returns partial results when some account endpoints are unauthorized; inspect errors in output

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