bitbottle

What this skill does

# 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

| Task | Open |
|---|---|
| Auth, hosts.yml, env vars, multi-host, `auth migrate`, `auth doctor` | `references/auth.md` |
| PR lifecycle (list/view/create/merge/merge-preview/approve/comment/activity/review/commits/files/participants/ready/unready/task/suggestion/comment-react/default-reviewer/reviewer-group/…) | `references/pr.md` |
| Repos, branches, tags, file/tree, visibility, edit, transfer, watcher, repo label list/create/update/delete, repo pr-settings get, repo pr-settings set, repo download list/upload/get/delete, repo clone (MCP: `clone_repo`), repo hook list/view/enable/disable/settings get/set (Server/DC only), repo sync Cloud fork sync (MCP: `sync_repo`) | `references/repos.md` |
| Commits (log, search, view/files/status/comment/comment-react) | `references/commit.md` |
| Pipelines, pipeline config get/enable/disable, schedules, caches, watch, trigger, test-report view, test-case list, SSH key pair, known hosts, OIDC config/keys (Cloud only) | `references/pipeline.md` |
| Pipeline runners — list / create / delete (Cloud only) | `references/runner.md` |
| Code Insights reports/annotations (Cloud + Server/DC); merge-check (Server/DC only) | `references/code-insights.md` |
| Issues, comments, attachments (list/delete), vote/unvote, watch/unwatch, activity/change log (Cloud only) | `references/issues.md` |
| Issue milestones list/view (Cloud only) | `references/milestone.md` |
| Issue versions list/view/create/delete (Cloud only) | `references/version.md` |
| snippet list/view/create/delete, snippet comment list/add/delete (Cloud only) | `references/snippet.md` |
| Deployments + environments + variables (Cloud only) | `references/deployment.md`, `references/variable.md` |
| Deploy keys (both), branch-rules (Cloud only), ssh-keys (Cloud + Server/DC) | `references/deploy-key.md`, `references/branch-rule.md`, `references/ssh-key.md` |
| Diff between refs, `diff REF1..REF2` | `references/diff.md` |
| Branch compare (`branch compare BASE..HEAD`) — ahead/behind counts + commit lists (Cloud + Server/DC) | `references/branch.md` |
| Workspaces + webhooks + workspace project CRUD + workspace project perms + workspace perms + workspace pipeline variables (Cloud only), `user view` | `references/workspace.md`, `references/user.md` |
| Mirror servers (list/view/repo list) (Server/DC only) | `references/mirror.md` |
| Named credential profiles (`profile create/use/list/delete`) | `references/profile.md` |
| Raw REST passthrough, pagination, MCP server config | `references/api.md` |
| Extensions (`extension install/list/upgrade/remove/exec`, extension scaffold) | `references/extension.md` |
| Group management — group list, group create, group delete, group member list, group member add, group member remove (Server/DC only) | `references/groups.md` |
| Project CRUD — project server-list, project create, project view, project edit, project delete (Server/DC only); project list WORKSPACE (Cloud only) | `references/project.md` |
| auth pat list/create/revoke (Server/DC only) | `references/auth.md` |
| Host info — backend type, base URL, version, feature matrix (`host info [--json]`) | `references/host.md` |

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:

| Command group | Repo arg | Notes |
|---|---|---|
| `pr *` (view/list/create/merge/…) | `-R [HOST/]PROJECT/REPO` flag | `-R` is the only path; no positional |
| `repo *`, `branch *`, `tag *`, `webhook *` | positional `PROJECT/REPO` | `-R` is in the inherited flag list but **silently ignored** — pass `PROJECT/REPO` as a positional and `--hostname HOST` separately |
| `commit view PROJECT/REPO HASH` | positional, **PROJ/REPO first** | |
| `commit files HASH [PROJECT/REPO]` | positional, **HASH first** | inverse of `commit view` |
| `commit cherry-pick HASH BRANCH [PROJECT/REPO]` | positional, **HASH then BRANCH** | Server/DC only (`branch-utils` plugin); `--message/-m` overrides commit msg |
| `issue *`, `code-insights *` | `[PROJECT/REPO]` positional or `-R` | optional; defaults to checkout |

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

```bash
# 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

| | Cloud (`bitbucket.org`) | Server/DC (self-hosted) |
|---|---|---|
| Auth context flag | `--email you@…` | `--username your.user` |
| Token type | App Password / API token | PAT (`BBDC-…`) |
| API base path | `2.0/…` | `rest/api/1.0/…` |
| Cloud-only | `pipeline *` (list/view/run/stop/trigger/watch/logs/steps/schedule/cache/variable/config/test-report/test-case), `runner list`, `runner create`, `runner delete`, `issue *` (including `issue attachment list/delete`, `issue vote/unvote`, `issue watch/unwatch`, `issue activity`), `snippet list [--workspace W]`, `snippet view`, `snippet create`, `snippet delete`, `snippet comment list`, `snippet comment add`, `snippet comment delete`, `pr request-changes`, `pr comment resolve`, `branch-rule *`, `branch-model *`, `workspace *` (including `workspace search`