Bitbucket Unofficial CLI

Unofficial. This project is not affiliated with, endorsed by, or supported by Atlassian. "Bitbucket" is a trademark of Atlassian. Use at your own risk against the Bitbucket Cloud REST API.

Unofficial command-line interface for Bitbucket Cloud built on bitbucket-unofficial-sdk. It logs in with an Atlassian API token, an access token or an OAuth 2 consumer, and prints results as a table, JSON, JSON Lines, CSV or bare identifiers.

1.0.0 covers everything the SDK offers, and freezes the exit codes, the JSON output, the command surface and the settings keys; see docs/roadmap.md.

Table of contents

• About
• Key features
• Architecture
• Getting started
• Usage
• Configuration
• Agent skills
• Development
• Roadmap
• Contributing
• Security
• License

About

The CLI is a thin layer over the SDK: commands parse options, call one SDK method, and render the model it returns. It never builds a URL or sends a request by hand, except for the OAuth token exchange, which the SDK leaves to the application.

Key features

• Three ways to authenticate. An Atlassian API token with your email, a repository, project or workspace access token, or an OAuth 2 consumer (authorization code or client credentials) that renews its own token.
• Safe storage. Credentials go to the system keyring. A 0600 file is an explicit opt-in, and no secret is ever accepted as a command-line argument.
• Scriptable output. table on a terminal, JSON when piped, plus jsonl, csv and id. Data goes to stdout; messages and errors go to stderr.
• Stable exit codes. Each failure class has its own code, so a script can tell a missing credential from a missing repository.
• Profiles. Keep several accounts and select one with --profile.

Architecture

flowchart TD
    main["main: Typer app and global options"] --> commands
    commands --> services["services: listing"]
    commands --> runtime["runtime: context, errors, exit codes"]
    runtime --> auth["auth: credentials, stores, OAuth"]
    runtime --> config["config: profiles and settings"]
    commands --> output["output: table, json, jsonl, csv, id"]
    runtime --> sdk["bitbucket-unofficial-sdk"]
    auth -. "token exchange" .-> oauth["Bitbucket OAuth endpoints"]
    sdk --> api["Bitbucket Cloud REST API"]

Layers point downward only. See docs/architecture/layering.md.

Getting started

Install the command from PyPI:

uv tool install bitbucket-unofficial-cli
# or
pipx install bitbucket-unofficial-cli

From a checkout, make install syncs the dependencies and registers the bitbucket command.

Log in, pick a workspace and look around:

bitbucket auth login                 # Atlassian email and API token
bitbucket workspace list
bitbucket workspace use my-workspace
bitbucket repo list

Usage

Authentication

Secrets come from a hidden prompt, or from standard input with --with-token. For OAuth, set BITBUCKET_OAUTH_CLIENT_SECRET to skip the prompt. Setting up a consumer is in docs/auth/oauth-consumer.md.

In CI, skip auth login and set ATLASSIAN_USER_EMAIL with ATLASSIAN_API_TOKEN, or BITBUCKET_ACCESS_TOKEN. The environment wins over anything stored.

Commands

Bitbucket pages results by cursor, so list commands take --limit N to stop early, or --cursor URL to fetch one page; the cursor of the next page is printed to stderr.

Global options

Global options go before the command: bitbucket -o json repo list.

Without --output, a terminal gets a table and a pipe gets JSON.

Exit codes

Configuration

Agent skills

The repository is also a Claude Code plugin. Pick one channel:

# Claude Code
/plugin marketplace add gajaguar/bitbucket-cli
/plugin install bitbucket-cli@bitbucket-cli-skills

# Any Agent Skills-compatible agent
npx skills add gajaguar/bitbucket-cli

# opencode
npx skills add gajaguar/bitbucket-cli -a opencode -y

• bitbucket-pull-requests covers pr, its comments, tasks and statuses.
• bitbucket-pipelines covers pipeline, environment and deployment.
• bitbucket-cli covers authentication, profiles, workspaces, repositories, branches, commits, source, permissions, webhooks and snippets.

The skills follow the Agent Skills format, so other agents can read skills/ directly. They require the CLI to be installed and a user to have run bitbucket auth login. See docs/agents/ for what each install channel does.

Development

make install   # dependencies, the `bitbucket` command and the git hooks
make check     # lint, types, spelling, commit messages
make test      # the test suite, with a 90% coverage floor
make help      # every target

The live tests hit the real API and are skipped unless ATLASSIAN_USER_EMAIL, ATLASSIAN_API_TOKEN and BITBUCKET_WORKSPACE are set; run them with uv run pytest -m live.

Roadmap

• 0.1.0 Foundation: authentication, configuration, output, user me, workspace and repository read commands
• 0.2.0 Repositories, projects, members, webhooks
• 0.3.0 Pull requests
• 0.4.0 Branches, tags, commits, source, statuses, reports, downloads
• 0.5.0 Branch restrictions, branching model, reviewers, permissions
• 0.6.0 Pipelines
• 0.7.0 Environments and deployments
• 0.8.0 Keys, emails, search
• 0.9.0 Snippets
• 1.0.0 Every SDK capability, with the contracts frozen

The detail, and what 1.0.0 freezes, is in docs/roadmap.md. docs/coverage.md maps each SDK capability to its command.

Contributing

See CONTRIBUTING.md.

Security

Report a vulnerability privately to dev@gajaguar.com instead of opening a public issue.

License

See LICENSE.