Bitbottle

bitbottle CLI

A gh-style CLI for Bitbucket Server/DC and Cloud. This file is a router plus invariant safety rules — load the matching reference for command detail. Don't memorize this file; run bitbottle <cmd> -h for the authoritative shape and flag list. Run bitbottle --version if behavior disagrees with this doc; the binary wins.

When to load which reference

Load both when a task spans areas. Don't load speculatively.

Safety rules (always apply)

1. Never echo tokens. Pass tokens via stdin (--with-token) or the BB_TOKEN env var. Never put a PAT/App Password on the command line — it lands in shell history.
2. Confirm before destructive ops. repo delete, repo rename, branch delete, tag delete, webhook delete, pr decline, pr merge are not undoable (repo rename breaks existing clones' origin URL on Cloud). Show the exact command + resolved host/PROJECT/REPO + PR/branch/tag name, then wait for explicit confirm.
3. Don't fabricate flags. bitbottle has gh-like shape but not gh-compatible flags. If a flag isn't in bitbottle <cmd> -h, don't pass it. Common phantoms: --author, --mine, --reviewer @me (no "self" sentinel — pass the user slug).
4. --json is a BOOLEAN flag, not a field selector. --json emits the full object as JSON; filter with --jq EXPR. Passing --json title,body is parsed as --json plus a positional argument (title,body) and fails with accepts N arg(s), received N+1. To discover field names: run with --json once, inspect the object.

Argument shape (high-frequency footgun)

bitbottle is inconsistent about repo targeting — match what -h says:

Outside any Bitbucket checkout, the relevant positional/-R is mandatory.

MCP tools use ONE canonical repo-arg shape: {project, slug} (plus an optional hostname) — project is the Server project key or Cloud workspace slug, slug is the repository slug. The few tools that historically took a single repo (WORKSPACE/REPO) string or {project, repo} — compare_refs, list_pr_commits, list_pr_files, get_repo_pr_settings, set_repo_pr_settings — now accept {project, slug}; the old shape still works for one release but the result carries a deprecation note. Each tool's tools/list entry also advertises _meta.backends (["server"], ["cloud"], or both); calling a Server-only tool against a Cloud host (or vice versa) returns host.unsupported before any HTTP, and an unknown hostname returns host.unknown listing the configured hosts.

Repo targeting & TLS

# Inside a Bitbucket checkout: host/project/repo auto-detected.
# Outside one (or to override):
bitbottle pr list      -R git.example.com/PROJ/repo
bitbottle repo view    PROJ/repo --hostname git.example.com
bitbottle repo edit    PROJ/repo --description "new description"

# Pin a default for the current checkout (writes .git/config):
bitbottle repo set-default HOST/PROJ/repo

Self-signed CA on Server/DC? -k / --skip-tls-verify is an inherited flag on every command. For permanence, set skip_tls_verify: true on the host entry in hosts.yml (see references/auth.md).

Cloud vs Server/DC

For custom-hostname Bitbucket Data Center, force routing with backend_type: cloud|server in hosts.yml.

Hot-path env vars

Failure-mode hints

Pipeline lifecycle (Cloud only)

# Trigger, watch, stop, view
bitbottle pipeline trigger WORKSPACE/REPO --branch main
bitbottle pipeline watch WORKSPACE/REPO UUID
bitbottle pipeline stop UUID WORKSPACE/REPO --confirm
bitbottle pipeline rerun UUID WORKSPACE/REPO
bitbottle pipeline view UUID WORKSPACE/REPO

# Pipeline config (Cloud only)
bitbottle pipeline config get WORKSPACE/REPO
bitbottle pipeline config enable WORKSPACE/REPO
bitbottle pipeline config disable WORKSPACE/REPO

# List and download step artifacts
bitbottle pipeline artifact list PIPELINE_UUID WORKSPACE/REPO --step STEP_UUID
bitbottle pipeline artifact download PIPELINE_UUID WORKSPACE/REPO \
  --step STEP_UUID --name build.tar.gz [--out PATH|-] [--clobber]

# Test report and test cases (Cloud only)
bitbottle pipeline test-report view PIPELINE_UUID WORKSPACE/REPO --step STEP_UUID
bitbottle pipeline test-case list PIPELINE_UUID WORKSPACE/REPO --step STEP_UUID [--status FAILED|PASSED|SKIPPED] [--limit N]

# Pipeline SSH configuration (Cloud only)
bitbottle pipeline ssh key-pair view [WORKSPACE/REPO]
bitbottle pipeline ssh key-pair regenerate [WORKSPACE/REPO] [--bits 2048|4096] [--confirm]
bitbottle pipeline ssh known-hosts list [WORKSPACE/REPO]
bitbottle pipeline ssh known-hosts view UUID [WORKSPACE/REPO]
bitbottle pipeline ssh known-hosts add HOSTNAME [WORKSPACE/REPO] [--key KEY] [--key-type rsa|ecdsa|ed25519]
bitbottle pipeline ssh known-hosts delete UUID [WORKSPACE/REPO] [--confirm]

# Pipeline OIDC configuration (Cloud only)
bitbottle pipeline oidc config WORKSPACE [--json]
bitbottle pipeline oidc keys WORKSPACE [--json]

# Branch compare (Cloud + Server/DC)
bitbottle branch compare main..feature WORKSPACE/REPO
bitbottle branch compare main..feature WORKSPACE/REPO --json

Dashboard

# Open PRs (author + reviewer) across a repo, or globally with --hostname
bitbottle status [PROJECT/REPO]
bitbottle pr status [PROJECT/REPO]

# Open a Bitbucket page in the browser
bitbottle browse [PROJECT/REPO]              # repo home
bitbottle browse [PROJECT/REPO] 42           # PR #42
bitbottle browse [PROJECT/REPO] abc1234      # commit
bitbottle browse [PROJECT/REPO] src/main.go  # file

Install / version

npm install -g @proggarapsody/bitbottle installs the CLI and auto-registers this skill. For non-npm installs (Homebrew, Go, bare binary): bitbottle skill install (refresh), skill path (locate), skill remove (uninstall).