bitbucket-jira-cli

name

bitbucket-jira-cli

description

Manage Bitbucket pull requests, repositories, and pipelines and Jira issues from the terminal with the bj CLI. bj mirrors the GitHub gh CLI, so gh pr/issue/repo commands map to bj pr/issue/repo, no MCP server or API wiring needed. Installs the bj CLI automatically if it is missing. Use when working with Bitbucket or Jira, opening or reviewing pull requests, managing Jira issues, running pipelines, or when a git branch name contains a Jira issue key like PROJ-42.

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

gh	bj
gh auth login / gh auth status	bj auth login / bj auth status
gh pr create	bj pr create
gh pr list / gh pr view	bj pr list / bj pr view
gh pr checkout / gh pr diff	bj pr checkout / bj pr diff
gh pr review / gh pr comment	bj pr review / bj pr comment
gh pr merge / gh pr close	bj pr merge / bj pr close
gh issue …	bj issue … (Jira issues)
gh repo clone / view / list	bj repo clone / view / list
gh run list / gh run view	bj pipeline list / bj pipeline view
gh api	bj api
gh browse	bj browse
gh release	bj release (Jira versions)
gh secret / gh variable	bj variable (--secured for secrets)
gh config	bj config
gh search	bj search

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, appends Jira: [PROJ-42](https://site/browse/PROJ-42) to the description, and transitions the ticket to In Progress. The line is skipped when the body already names the key, so write your own reference if you want it elsewhere.
• 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 "..." --body "..."
bj issue edit PROJ-42 --body "$(cat body.md)"   # replace the description
bj issue edit PROJ-42 --field "Story Points=3"
bj issue comment PROJ-42 --body "..."
bj issue transition PROJ-42 "In Review"
bj issue fields PROJ-42                 # list editable fields on the issue
bj issue link PROJ-42 PROJ-43 --type blocks    # PROJ-42 blocks PROJ-43
bj issue link https://example.com/doc   # attach a URL to the branch's issue
bj issue links PROJ-42                  # linked issues and URLs
bj issue unlink PROJ-42 PROJ-43         # remove a link

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

Writing issue descriptions and comments

• --body/-b carries the description on issue create and issue edit, and the text on issue comment. --editor/-e opens $EDITOR instead, which is no use non-interactively.
• Bodies are Markdown. They are converted to Jira Cloud's ADF, so headings, bullet and numbered lists, tables, fenced code blocks, block quotes, links and bold/italic/strikethrough/inline code all render. Wiki markup (h3., {code}) does not: Jira Cloud dropped it and it shows up verbatim.
• For a multi-line body, write the Markdown to a file and pass it in, which keeps quoting and backticks intact:

bj issue create --project PROJ --type Task --summary "..." --body "$(cat body.md)"

• Set the epic or parent with a bare issue key. An explicit {"key": "PROJ-1"} or a numeric issue id works too:

bj issue edit PROJ-42 --field Parent=PROJ-1

• --field takes plain values for every field type, including multi-value fields such as fix versions, components, labels and linked issues. Separate the values with commas; bj reads the field's schema off the issue and sends each one in the shape the API wants:

bj issue edit PROJ-42 --field "Fix versions=v1.3.0"
bj issue edit PROJ-42 --field "Components=Backend, Reporting"

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.