Bitbucket Jira CLI

bitbucket-jira-cli (bj)

bj is gh for Bitbucket and Jira. The command surface mirrors the GitHub CLI: if you know gh, you know bj. It manages Bitbucket pull requests, repositories, and pipelines, plus Jira issues, from one noun-first command tree.

If a command or flag is not covered here, run bj <command> --help; the flags mirror gh and the help is authoritative.

Install bj if it is missing

Before running any bj command, make sure the CLI is on PATH. If command -v bj finds nothing, install it. This snippet picks whatever installer is already available and prefers an isolated, self-updating install:

if ! command -v bj >/dev/null 2>&1; then
  if command -v uv >/dev/null 2>&1; then
    uv tool install bitbucket-jira-cli          # isolated, self-updating (preferred)
  elif command -v pipx >/dev/null 2>&1; then
    pipx install bitbucket-jira-cli
  elif command -v pip3 >/dev/null 2>&1 || command -v pip >/dev/null 2>&1; then
    pip install --user bitbucket-jira-cli
  else
    curl -LsSf uvx.sh/bitbucket-jira-cli/install.sh | sh   # installs uv, then bj
  fi
fi

On Windows PowerShell, install with:

powershell -ExecutionPolicy ByPass -c "irm https://uvx.sh/bitbucket-jira-cli/install.ps1 | iex"

Then verify, and fix PATH if the install dir is not picked up yet:

command -v bj >/dev/null 2>&1 || export PATH="$HOME/.local/bin:$PATH"  # uv/pip user bin
bj --help >/dev/null    # confirms bj is installed and runnable

To run bj once without installing it (one-off commands, ephemeral CI), use uvx bitbucket-jira-cli <args> in place of bj <args>. For repeated use in a session, install it once with the snippet above so later bj calls just work.

Setup

Authenticate once, like gh auth login:

bj auth login          # interactive; logs in Bitbucket and/or Jira
bj auth status         # show who you are logged in as

For CI or headless agents (no interactive prompt), pass tokens instead:

export BJ_BITBUCKET_TOKEN=...   # Bitbucket API token
export BJ_JIRA_TOKEN=...        # Jira API token
# or: bj auth login --bitbucket --with-token < token.txt

Running non-interactively (agents, scripts, CI)

• Set BJ_PROMPT_DISABLED=1 so bj never waits on a prompt; pass required values as flags or the command fails fast with a clear error. Piped output (non-TTY) already skips prompts.
• Set NO_COLOR=1 to drop colors and the spinner (less noise in the transcript).
• Add --json for the full, raw API payload; shape it with --jq '<expr>' (requires the jq binary on PATH).
• Pass --yes/-y to accept confirmations (merge, close, stop).
• Exit codes: 0 success, 1 failure (includes "not logged in"), 2 usage error. Branch on these instead of parsing text.

gh to bj

Differences from gh

• Two products behind one CLI: Bitbucket owns pr, repo, pipeline; Jira owns issue. Each backend has its own token (BJ_BITBUCKET_TOKEN, BJ_JIRA_TOKEN).
• bj issue targets Jira. Issue keys look like PROJ-42, not numbers.
• bj pipeline is Bitbucket Pipelines, the analog of gh run.
• --json emits the whole raw Bitbucket/Jira response. There is no gh-style field list; filter with --jq instead.
• bj api calls the Bitbucket or Jira REST API (--backend bitbucket|jira), not a GraphQL endpoint.
• A failed auth check exits 1 (a normal failure), where gh uses 4.

Branch-key automation

bj reads a Jira key from the current git branch (e.g. feature/PROJ-42-thing gives PROJ-42) and uses it automatically:

• bj pr create fills the PR title from the ticket, links the PR to the issue, and transitions the ticket to In Progress.
• bj pr merge transitions the linked ticket to Done after a successful merge.

Preview the effect without writing anything using --dry-run; skip all Jira side effects with --no-jira. If no key is found, bj acts like a plain Bitbucket client.

Common commands

# Pull requests (Bitbucket)
bj pr create --dry-run                 # preview title/link/transition
bj pr create --title "..." --yes       # non-interactive create
bj pr list --state open --json
bj pr view --json | jq '.title'
bj pr diff
bj pr review --approve                 # or --request-changes --body "..."
bj pr comment --body "..."             # add --file/--line for inline
bj pr merge --squash --delete-branch --yes

# Issues (Jira)
bj issue list --assignee me --json
bj issue view PROJ-42 --json
bj issue create --project PROJ --type Bug --summary "..."
bj issue edit PROJ-42 --field "Story Points=3"
bj issue transition PROJ-42 "In Review"
bj issue fields PROJ-42                 # list editable fields on the issue

# Repos and pipelines (Bitbucket)
bj repo clone WORKSPACE/REPO
bj pipeline list --json
bj pipeline run --branch main

Safety

• Run bj pr create / bj pr merge with --dry-run first when unsure.
• pr merge, pr close, issue close, and pipeline stop change state. In an interactive session bj asks first; with --yes or when non-interactive it proceeds. Confirm intent with the user before passing --yes to these.