bitbucket-cli

oasis-bitbucket — an AXI-compliant CLI for the Oasis Bitbucket Server. Browse repos, branches, and pull requests, review diffs, comment, create, and merge PRs — with token-efficient TOON output built for autonomous agents.

Extracted from the oasis-core Claude Code plugin so it can be installed, versioned, and released on its own.

Quick Start

Install the bitbucket-cli skill in the Agent Skills format with npx skills:

npx skills add oasissys/bitbucket-cli --skill bitbucket-cli -g

That is the entire setup — the skill teaches your agent the CLI, and it runs without a global install as npx -y @oasissys/bitbucket-cli (Node 20+ required). Installing the skill itself needs GitHub access to this private repo.

-g installs the skill for all projects (~/.claude/skills/); drop it to install for the current project only.

Other ways to install

Zero setup

Any capable agent can run the CLI directly with nothing installed. Just tell your agent:

Execute `npx -y @oasissys/bitbucket-cli` to get Oasis Bitbucket tools.

Global install + session hook

Want the CLI on PATH and your open pull requests fed into every agent session?

npm install -g @oasissys/bitbucket-cli   # installs `oasis-bitbucket` (and the `bitbucket-cli` alias)
oasis-bitbucket setup

setup registers a SessionStart hook for Claude Code, Codex, and OpenCode that surfaces your open pull requests at session start — restart your agent session after running it. If you use the oasis-core Claude Code plugin, it already ships this hook; skip setup or remove one of the two.

From a clone (development)

pnpm install && pnpm run build && pnpm link --global

Authenticate

Credentials live in ~/.oasis.json (shared with the other oasis CLIs and the Oasis dashboard) and are verified against the live server before being saved.

oasis-bitbucket auth --user <username> --password <password>
oasis-bitbucket auth            # show current status
oasis-bitbucket auth --clear    # sign out

Use

oasis-bitbucket                                  # live view: your open PRs
oasis-bitbucket repos OCL                        # repositories in a project
oasis-bitbucket prs OAS_PLS/oasis-common         # a repo's pull requests
oasis-bitbucket pr OAS_PLS/oasis-common 681      # PR details + reviewers
oasis-bitbucket diff OAS_PLS/oasis-common 681    # unified diff (400 lines, --full for all)
oasis-bitbucket merge OAS_PLS/oasis-common 681   # merge (version auto-resolved)

Every command supports --help. Output is TOON on stdout, diagnostics on stderr, exit codes 0/1/2 (success/error/usage).

Development

pnpm run dev -- prs OCL/common-web-components   # run from source
pnpm test                                        # vitest
pnpm run lint                                    # eslint
pnpm run build:skill                             # regenerate SKILL.md

Releases are cut by release-please from conventional commits on main. Do not hand-edit CHANGELOG.md, .release-please-manifest.json, or skills/bitbucket-cli/SKILL.md — they are generated.