bitbucket-axi

Agent-facing Bitbucket Cloud CLI with compact TOON output, strict validation, explicit empty states, and useful next-command hints.

Install

Requires Node.js 20 or newer.

npm install -g bitbucket-axi
# From a checkout:
npm install -g .

Authenticate

bitbucket-axi stores your Bitbucket Cloud API token in your operating system credential manager (macOS Keychain, Windows Credential Manager, or libsecret on Linux). It never writes the token to a plaintext file and never accepts it as a command-line argument.

Create a Bitbucket Cloud API token with the read:user:bitbucket scope (used once by config set to verify the token belongs to your account) plus the repository, pull request, and pipeline scopes your commands need. Then run the interactive setup:

bitbucket-axi config set

Use the Atlassian account email that owns the token (not your Bitbucket username). You can supply it up front with bitbucket-axi config set --email [email protected]. The API token is prompted for without echo, validated against Bitbucket's current-user endpoint, and only then written to the keychain.

For non-interactive automation, pipe the token from your secret manager. The email remains explicit, and --token-stdin prevents prompting:

token-producing-command | bitbucket-axi config set --email [email protected] --token-stdin

Verify setup at any time:

bitbucket-axi config status   # shows the configured email and readiness, never the token
bitbucket-axi config clear    # removes the stored credential (idempotent)

Every network-backed command requires a stored credential. If none is configured, the command makes no API call and returns an auth-required result pointing at bitbucket-axi config set.

Select a repository

Pass -R/--repo <workspace/repo> after the command:

bitbucket-axi pr list -R acme/widgets

When omitted, bitbucket-axi scans git remotes for a bitbucket.org repository. Running with no arguments shows a compact dashboard for the selected repository.

Commands

| Command | Purpose | | --- | --- | | config set [--email <email>] | Interactively validate and store API credentials in the OS keychain | | config status | Show the configured email and credential readiness | | config clear | Remove the stored credential | | config git set --token-stdin | Validate and store a separate Git HTTPS token for the credential helper | | config git status | Show whether the Git HTTPS token is configured | | config git clear | Remove the stored Git HTTPS token | | credential-helper | Git credential helper supplying stored HTTPS credentials (invoked by git) | | repo view | Show repository details | | pr list | List pull requests | | pr view <id> | Show one pull request; use --full for complete text | | pr create | Create a pull request | | pipeline list | List pipeline runs | | pipeline view <uuid> | Show one pipeline run | | pipeline run | Trigger a branch or custom pipeline | | api [method] <path> | Call any Bitbucket Cloud REST API v2.0 path |

Run bitbucket-axi --help or bitbucket-axi <command> --help for the complete, concise flag reference.

Git over HTTPS (optional)

The default Git transport is SSH. For HTTPS clones, bitbucket-axi can act as a Git credential helper using a separate token stored in the OS keychain (distinct from the API token, so a dedicated app password can be used).

token-producing-command | bitbucket-axi config git set --token-stdin
bitbucket-axi config git status   # shows configured, never the token
git config --global credential.helper 'bitbucket-axi credential-helper'

The Git token is validated against the same Bitbucket account as the API token (reusing the configured account email as the git username) before it is stored. The helper is read-only and only responds to bitbucket.org requests; git credential store/erase are ignored. Remove it with bitbucket-axi config git clear.

Examples

bitbucket-axi repo view
bitbucket-axi pr list --state open --fields source,destination
bitbucket-axi pr view 42 --full
bitbucket-axi pr create --title "Fix auth" --source fix/auth --destination main --body "Resolves token refresh"
bitbucket-axi pipeline list --fields commit,url
bitbucket-axi pipeline run --branch main
bitbucket-axi pipeline run --branch main --custom "Deploy production"
bitbucket-axi api /repositories/{workspace}/{repo}/refs/branches
bitbucket-axi api POST /repositories/{workspace}/{repo}/pipelines --field 'target={"type":"pipeline_ref_target","ref_type":"branch","ref_name":"main"}'

List commands default to compact fields. Add supported columns with --fields. Long descriptions and raw API string values are truncated by default; pass --full when complete content is needed.

Development

pnpm install
pnpm run check
pnpm run dev -- --help

Tests mock HTTP responses and the OS credential store; they require no live Bitbucket credentials and never touch the real keychain.

Publishing

From a clean checkout, verify the packed file list with npm pack --dry-run. Maintainers publish the current version with:

npm publish

The publish lifecycle rebuilds the executable and runs the full project checks. Bump the version separately before publishing a release.