diff --git a/bitbucket-jira-cli/SKILL.md b/bitbucket-jira-cli/SKILL.md new file mode 100644 index 0000000..60badcc --- /dev/null +++ b/bitbucket-jira-cli/SKILL.md @@ -0,0 +1,164 @@ +--- +name: bitbucket-jira-cli +description: Manage Bitbucket pull requests, repos and pipelines and Jira issues from the terminal with the gh-style bj CLI, which self-installs if missing. +author: Spenhouet +version: "1.0" +tags: + - bitbucket + - jira + - atlassian + - cli + - pull-request +--- + +# 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 --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 with whatever Python packaging tool is available, +preferring an isolated, self-updating install: + +```bash +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 + else + pip install --user bitbucket-jira-cli + fi +fi +``` + +Then verify, and fix `PATH` if the install dir is not picked up yet: + +```bash +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 +``` + +If none of `uv`, `pipx` or `pip` is present, install `uv` first (see the +[uv install guide](https://docs.astral.sh/uv/getting-started/installation/)) or +follow the [bj installation docs](https://spenhouet.github.io/bitbucket-jira-cli/installation/). +To run `bj` once without installing it, use `uvx bitbucket-jira-cli ` in +place of `bj `. + +## Setup + +Authenticate once, like `gh auth login`: + +```bash +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: + +```bash +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 ''` + (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` | +| `gh alias` | `bj alias` | +| `gh ssh-key` | `bj ssh-key` | +| `gh status` | `bj status` | +| `gh project` | `bj board` (Jira boards/sprints) | + +## 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 + +```bash +# 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.