{"id":49307029,"url":"https://github.com/proggarapsody/bitbottle","last_synced_at":"2026-05-29T06:02:21.289Z","repository":{"id":353536317,"uuid":"1219834955","full_name":"proggarapsody/bitbottle","owner":"proggarapsody","description":"Go CLI for Bitbucket Cloud and Self-hosted Bitbucket Server","archived":false,"fork":false,"pushed_at":"2026-05-26T08:02:39.000Z","size":11421,"stargazers_count":2,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-26T08:06:58.638Z","etag":null,"topics":["bitbucket","bitbucket-cli","bitbucket-server","cli","devtools","mcp","self-hosted"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/proggarapsody.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-24T09:10:09.000Z","updated_at":"2026-05-26T08:02:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/proggarapsody/bitbottle","commit_stats":null,"previous_names":["proggarapsody/bitbottle"],"tags_count":155,"template":false,"template_full_name":null,"purl":"pkg:github/proggarapsody/bitbottle","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proggarapsody%2Fbitbottle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proggarapsody%2Fbitbottle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proggarapsody%2Fbitbottle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proggarapsody%2Fbitbottle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/proggarapsody","download_url":"https://codeload.github.com/proggarapsody/bitbottle/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proggarapsody%2Fbitbottle/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33637485,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bitbucket","bitbucket-cli","bitbucket-server","cli","devtools","mcp","self-hosted"],"created_at":"2026-04-26T10:02:11.196Z","updated_at":"2026-05-29T06:02:21.282Z","avatar_url":"https://github.com/proggarapsody.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# bitbottle\n\n\u003e Bitbucket CLI for Cloud and Server / Data Center — built with the same philosophy as [GitHub CLI](https://github.com/cli/cli).\n\n[![CI](https://github.com/proggarapsody/bitbottle/actions/workflows/ci.yml/badge.svg)](https://github.com/proggarapsody/bitbottle/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/@proggarapsody/bitbottle)](https://www.npmjs.com/package/@proggarapsody/bitbottle)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/proggarapsody/bitbottle/badge)](https://securityscorecards.dev/viewer/?uri=github.com/proggarapsody/bitbottle)\n\nWork with Bitbucket from your terminal — pull requests, repos, branches, tags, commits, pipelines, and raw API access. One tool, both backends, same commands.\n\n```\n$ bitbottle pr list\n#47  feat: seamless audit            main ← feat/audit       OPEN   alice\n#46  fix: 409 on concurrent merge    main ← fix/merge-race   MERGED bob\n\n$ bitbottle pr create --title \"fix: handle empty diff\" --base main\n✓ Created PR #48 — https://bitbucket.example.com/projects/PROJ/repos/api/pull-requests/48\n```\n\n---\n\n## Installation\n\n**npm** (recommended — works everywhere Node is installed):\n```bash\nnpm install -g @proggarapsody/bitbottle\n```\n\nThis also registers the bundled AI agent skill (`SKILL.md` + topic\nreferences) with any agent runtimes detected on your machine —\nClaude Code, Cursor, Codex, Gemini CLI, and 50+ others — so your\nagents know how to drive bitbottle correctly. Skip with\n`BITBOTTLE_SKIP_SKILL_INSTALL=1 npm install -g …`.\n\nIf you installed via Homebrew, Go install, or the bare binary,\nregister the skill explicitly:\n```bash\nbitbottle skill install            # uses npx; needs Node.js \u003e= 18\nbitbottle skill path               # show where the skill was installed\nbitbottle skill remove             # uninstall\n```\n\n**Go install:**\n```bash\ngo install github.com/proggarapsody/bitbottle/cmd/bitbottle@latest\n```\n\n**Homebrew / binary / deb / rpm / Docker** — see the [latest release](https://github.com/proggarapsody/bitbottle/releases/latest).\n\n---\n\n## Authentication\n\n```bash\n# Bitbucket Cloud\necho \"YOUR_APP_PASSWORD\" | bitbottle auth login --hostname bitbucket.org --with-token\n\n# Bitbucket Server / Data Center (PAT, self-signed cert)\necho \"BBDC-YOUR-PAT\" | bitbottle auth login \\\n  --hostname git.example.com \\\n  --with-token \\\n  --git-protocol https \\\n  --skip-tls-verify\n\n# Verify\nbitbottle auth status\n\n# Diagnose credential / keychain / connectivity issues\nbitbottle auth doctor [--hostname git.example.com]\n```\n\nCredentials are stored in `~/.config/bitbottle/hosts.yml`. Inside a git repo with a Bitbucket remote the host and project/repo are detected automatically. Outside a repo, use `-R HOST/PROJECT/REPO`.\n\nTokens are intentionally stripped from `hosts.yml` on every save. If you have an existing `oauth_token` in `hosts.yml` (from an older version), run `bitbottle auth migrate` to move it to the OS keyring.\n\n---\n\n## Commands\n\n| Group | Commands |\n|---|---|\n| `auth` | `login` `logout` `status` `token` `refresh` `doctor` |\n| `pr` | `list` `view` `create` `merge` `approve` `unapprove` `diff` `checkout` `edit` `decline` `reopen` `ready` `unready` `request-review` `comment` `default-reviewer {list\\|add\\|remove}` |\n| `repo` | `list` `view` `create` `delete` `clone` `set-default` `rename` `fork` _(Cloud)_ `file get` `tree` `watcher list` `download {list\\|upload\\|get\\|delete}` _(Cloud only)_ |\n| `branch` | `list` `create` `delete` `checkout` `compare` |\n| `tag` | `list` `create` `delete` |\n| `webhook` | `list` `view` `create` `delete` |\n| `deploy-key` | `list` `add` `delete` |\n| `branch-rule` | `list` `add` `delete` _(Cloud only)_ |\n| `branch-model` | `get` `set` _(Cloud only)_ |\n| `ssh-key` | `list` `add` `delete` |\n| `commit` | `log` `view` `status` `status report` `files` `comment {list\\|add\\|edit\\|delete}` |\n| `pipeline` | `list` `view` `run` `steps` `logs` `stop` `trigger` `watch` `schedule {list\\|create\\|delete}` `cache {list\\|delete}` `artifact {list\\|download}` `config {get\\|enable\\|disable}` `test-report view` `test-case list` _(Cloud only)_ |\n| `deployment` | `list` `view` _(Cloud only)_ |\n| `environment` | `list` `create` `delete` _(Cloud only)_ |\n| `user` | `view` |\n| `workspace` | `list` `member list` `hook list` `hook create` `hook delete` `project {create\\|view\\|edit\\|delete}` `perms {list\\|repo list\\|grant\\|revoke}` _(Cloud only)_ |\n| `mirror` | `list` `view` `repo list` _(Server/DC only)_ |\n| `project` | `list WORKSPACE` _(Cloud only)_ · `server-list` `create` `view` `edit` `delete` _(Server/DC only)_ |\n| `issue` | `list` `view` `create` `close` `edit` `reopen` `assign` `comment {list\\|add\\|edit\\|delete}` _(Cloud only)_ |\n| `milestone` | `list` `view` _(Cloud only)_ |\n| `version` | `list` `view` `create` `delete` _(Cloud only)_ |\n| `search` | `code QUERY` _(Cloud only)_ |\n| `api` | Raw REST passthrough with pagination, `--jq`, variable expansion |\n| `alias` | Custom command shortcuts |\n| `config` | Editor, pager, git protocol per-host |\n| `completion` | `bash` `zsh` `fish` `powershell` |\n| `mcp` | MCP stdio server for AI assistants |\n| `context` | One-call orientation: host, repo, branch, default branch, ahead/behind, user, backend |\n\nAll listing commands support `--json fields`, `--jq expr`, `--limit N`, `--hostname HOST`. TTY output is aligned and coloured; piped output is plain tab-separated for scripting.\n\n---\n\n## Key Workflows\n\n### Pull Requests\n\n```bash\n# Open PRs in current repo\nbitbottle pr list\n\n# Create a PR\nbitbottle pr create --title \"feat: add retry logic\" --base main\n\n# Review\nbitbottle pr diff 42 | delta\nbitbottle pr checkout 42\n\n# Approve and merge\nbitbottle pr approve 42\nbitbottle pr merge 42 --squash --delete-branch\n\n# Add reviewers\nbitbottle pr request-review 42 --reviewer alice --reviewer bob\n\n# Decline / reopen (reopen is Bitbucket Server / DC only)\nbitbottle pr decline 42\nbitbottle pr reopen  42\n\n# Read review comments — general + inline (file:line) anchors and replies\nbitbottle pr comment list 42                            # all comments; LOCATION column shows path:line for inline\nbitbottle pr comment list 42 --inline                   # only inline review comments\nbitbottle pr comment list 42 --json id,inline,parentId,resolved,updatedAt\n\n# Write review comments — general, inline, replies\nbitbottle pr comment add 42 --body \"LGTM!\"                              # general comment\nbitbottle pr comment add 42 --inline pkg/foo.go:88 --body \"rename?\"      # inline (new side, single line)\nbitbottle pr comment add 42 --inline pkg/foo.go:10-15 --body \"...\"      # multi-line range (Cloud only)\nbitbottle pr comment add 42 --inline pkg/foo.go:7 --side old --body \"..\" # comment on the old / removed side\nbitbottle pr comment add 42 --parent 1234 --body \"agreed\"                # reply to an existing thread\n\n# Edit / delete / resolve a comment\nbitbottle pr comment edit   42 1234 --body \"updated\"\nbitbottle pr comment delete 42 1234\nbitbottle pr comment resolve 42 1234                                     # Bitbucket Cloud only\n\n# Submit a compound review (body + inline comments + action) in one call\nbitbottle pr review 42 --approve --body \"lgtm overall\"\nbitbottle pr review 42 --request-changes --body \"see comments\" \\\n    --inline pkg/foo.go:88:please rename                                  # request-changes is Cloud only\nbitbottle pr review 42 --comment --inline pkg/foo.go:10-15:extract helper # comment-only review\n\n# PR activity event stream (approvals, comments, updates, merges)\nbitbottle pr activity 42\nbitbottle pr activity 42 --limit 20\nbitbottle pr activity 42 --json type,actor,createdAt,detail\n\n# PR commits\nbitbottle pr commits 42\nbitbottle pr commits 42 --json hash,message,author,date\n\n# PR files changed\nbitbottle pr files 42\nbitbottle pr files 42 --json status,path,additions,deletions\n\n# PR participants (author, reviewers, observers)\nbitbottle pr participants 42\nbitbottle pr participants 42 --json role,display_name,username,approved\n\n# Apply a suggested change (Bitbucket Server / DC only — commits to the PR branch)\nbitbottle pr suggestion apply 42 COMMENT_ID SUGGESTION_ID\nbitbottle pr suggestion apply 42 COMMENT_ID SUGGESTION_ID --preview   # show without applying\n```\n\n### Repos \u0026 Branches\n\n```bash\nbitbottle repo list --limit 20\nbitbottle repo create my-service --project MYPROJ\nbitbottle repo clone MYPROJ/my-service\n\nbitbottle branch list\nbitbottle branch create MYPROJ/my-service feature/x --start-at main\nbitbottle branch delete MYPROJ/my-service feature/x\n```\n\n#### Branch protection _(Bitbucket Server / DC only)_\n\nBranch restrictions on Bitbucket Server / DC. Cloud has a different model\nthat isn't wired up yet — invocations against Cloud return a typed\n\"unsupported on host\" error.\n\n```bash\nbitbottle branch protect list   MYPROJ/my-service\nbitbottle branch protect create MYPROJ/my-service \\\n  --type fast-forward-only --branch main \\\n  --user alice --group devs\nbitbottle branch protect delete MYPROJ/my-service 42\n```\n\n`--type` accepts `read-only`, `no-deletes`, `fast-forward-only`, or\n`pull-request-only`. Pass exactly one of `--branch NAME` (literal branch)\nor `--pattern GLOB` (e.g. `release/*`).\n\n### Pipelines _(Cloud only)_\n\n```bash\nbitbottle pipeline list  MYWORKSPACE/my-service\nbitbottle pipeline run   MYWORKSPACE/my-service --branch main\nbitbottle pipeline view  MYWORKSPACE/my-service {uuid} --web\n\n# Drill into a run:\nbitbottle pipeline steps MYWORKSPACE/my-service {pipeline-uuid}\nbitbottle pipeline logs  MYWORKSPACE/my-service {pipeline-uuid} {step-uuid}\n\n# Repository-level pipeline variables (upsert by KEY):\nbitbottle variable list   MYWORKSPACE/my-service\nbitbottle variable set    MYWORKSPACE/my-service DEPLOY_ENV prod\necho \"$TOKEN\" | bitbottle variable set MYWORKSPACE/my-service \\\n  API_TOKEN --body=- --secured\nbitbottle variable delete MYWORKSPACE/my-service DEPLOY_ENV --confirm\n```\n\nSecured variables redact their value on read (TTY column shows\n`\u003csecured\u003e`, JSON `value` shows `\"\u003csecured\u003e\"`). Use `--body=-` to read\nthe value from stdin so the secret never touches shell history.\n\n### Pipeline Schedules _(Cloud only)_\n\n```bash\n# List all pipeline schedules for a repository\nbitbottle pipeline schedule list MYWORKSPACE/my-service\n\n# Create a schedule (runs daily at midnight on main)\nbitbottle pipeline schedule create MYWORKSPACE/my-service \\\n  --cron \"0 0 * * *\" --branch main\n\n# Create a disabled schedule\nbitbottle pipeline schedule create MYWORKSPACE/my-service \\\n  --cron \"0 12 * * 1\" --branch develop --enabled=false\n\n# Delete a schedule by UUID\nbitbottle pipeline schedule delete MYWORKSPACE/my-service {uuid}\n```\n\n### Pipeline Caches _(Cloud only)_\n\n```bash\n# List all pipeline caches for a repository\nbitbottle pipeline cache list MYWORKSPACE/my-service\n\n# Delete a cache by UUID\nbitbottle pipeline cache delete MYWORKSPACE/my-service {uuid}\n```\n\n### Pipeline Artifacts _(Cloud only)_\n\n```bash\n# List artifacts produced by a pipeline step\nbitbottle pipeline artifact list {pipeline-uuid} MYWORKSPACE/my-service --step {step-uuid}\n\n# Download an artifact to the current directory\nbitbottle pipeline artifact download {pipeline-uuid} MYWORKSPACE/my-service \\\n  --step {step-uuid} --name build.tar.gz\n\n# Download to a specific path, or pipe to stdout\nbitbottle pipeline artifact download {pipeline-uuid} MYWORKSPACE/my-service \\\n  --step {step-uuid} --name build.tar.gz --out /tmp/build.tar.gz\nbitbottle pipeline artifact download {pipeline-uuid} MYWORKSPACE/my-service \\\n  --step {step-uuid} --name build.tar.gz --out -\n```\n\n### Deployments \u0026 Environments _(Cloud only)_\n\n```bash\n# List recent deployments\nbitbottle deployment list  MYWORKSPACE/my-service\nbitbottle deployment list  MYWORKSPACE/my-service --limit 25\n\n# View a single deployment\nbitbottle deployment view  MYWORKSPACE/my-service {deployment-uuid}\n\n# List environments\nbitbottle environment list MYWORKSPACE/my-service\n\n# Create an environment (type must be Test, Staging, or Production)\nbitbottle environment create MYWORKSPACE/my-service --name \"QA\" --type Test\nbitbottle environment create MYWORKSPACE/my-service --name \"Prod\" --type Production --rank 10\n\n# Delete an environment (destructive — --confirm required on non-TTY)\nbitbottle environment delete MYWORKSPACE/my-service {env-uuid} --confirm\n\n# Environment variables — use variable --scope deployment (see deprecation note below)\nbitbottle variable list   MYWORKSPACE/my-service --scope deployment --env {env-uuid}\nbitbottle variable set    MYWORKSPACE/my-service DEPLOY_KEY prod-val --scope deployment --env {env-uuid}\nbitbottle variable set    MYWORKSPACE/my-service API_TOKEN secret --scope deployment --env {env-uuid} --secured\nbitbottle variable delete MYWORKSPACE/my-service DEPLOY_KEY --scope deployment --env {env-uuid} --confirm\n```\n\nAll commands support `--json fields` and `--jq expr`. Secured variable values\nare never returned by the API once set.\n\nThese commands return a typed unsupported-capability error on Bitbucket Server /\nData Center — deployments and environments are a Cloud-only feature.\n\n### Webhooks\n\n```bash\nbitbottle webhook list   MYPROJ/my-service\nbitbottle webhook view   MYPROJ/my-service {id}\n\n# Create\nbitbottle webhook create MYPROJ/my-service \\\n  --url https://hooks.example.com/bb \\\n  --events 'repo:push,pullrequest:created'\n\n# With shared secret from stdin (keeps secret out of shell history)\necho \"$WEBHOOK_SECRET\" | bitbottle webhook create MYPROJ/my-service \\\n  --url https://hooks.example.com/bb \\\n  --events 'repo:push' \\\n  --secret -\n\n# Delete (destructive — --confirm required when not interactive)\nbitbottle webhook delete MYPROJ/my-service {id} --confirm\n```\n\nEvent keys differ between backends:\n- **Cloud** uses `repo:push`, `pullrequest:created`, `pullrequest:approved`, …\n- **Server/DC** uses `repo:refs_changed`, `pr:opened`, `pr:merged`, …\n\n`--secret` accepts the raw value, `-` to read from stdin, or `@PATH` to read\nfrom a file. Trailing newlines from stdin / file are trimmed. Webhook\nsecrets are write-only — neither backend returns them on read.\n\n### Deploy keys\n\n```bash\n# List deploy keys\nbitbottle deploy-key list MYPROJ/my-service\n\n# Add a deploy key\nbitbottle deploy-key add MYPROJ/my-service --key \"ssh-rsa AAAA...\" --label \"CI server\"\n\n# Delete a deploy key by ID\nbitbottle deploy-key delete MYPROJ/my-service 42\n```\n\nAll three subcommands work on both Bitbucket Cloud and Server/DC. `list` and\n`add` support `--json` / `--jq` / `--yaml` for structured output.\n\n### Branch restriction rules (Cloud only)\n\n```bash\n# List branch restriction rules\nbitbottle branch-rule list myworkspace/my-service\n\n# Add a rule requiring 2 approvals before merging to main\nbitbottle branch-rule add myworkspace/my-service --kind require_approvals_to_merge --pattern main --value 2\n\n# Add a push restriction (no direct pushes to main)\nbitbottle branch-rule add myworkspace/my-service --kind push --pattern main\n\n# Delete a rule by ID\nbitbottle branch-rule delete myworkspace/my-service 7\n```\n\nCloud only. `list` and `add` support `--json` / `--jq` / `--yaml` for structured output.\n\n### SSH keys (Cloud only)\n\n```bash\n# List SSH keys for the current user\nbitbottle ssh-key list\n\n# Add an SSH key\nbitbottle ssh-key add --key \"ssh-rsa AAAA...\" --label \"Laptop\"\n\n# Delete an SSH key by ID\nbitbottle ssh-key delete 42\n```\n\n`list` and `add` support `--json` / `--jq` / `--yaml` for structured output.\n\n### PR default reviewers\n\n```bash\n# List default reviewers\nbitbottle pr default-reviewer list MYPROJ/my-service\n\n# Add a default reviewer (Server: user slug; Cloud: account ID or nickname)\nbitbottle pr default-reviewer add MYPROJ/my-service jsmith\n\n# Remove a default reviewer\nbitbottle pr default-reviewer remove MYPROJ/my-service jsmith\n```\n\nBoth Cloud and Server/DC are supported. `list` supports `--json` / `--jq` / `--yaml`.\n\n### Repo extras\n\n```bash\n# Rename (both backends — slug derives from new name on Cloud).\n# --confirm is required on non-TTY because the slug change breaks existing\n# clones' origin URL — run `git remote set-url origin ...` after.\nbitbottle repo rename MYPROJ/my-service my-service-v2 --confirm\n\n# Fork into another workspace (Bitbucket Cloud only)\nbitbottle repo fork myworkspace/my-service --into otherws\nbitbottle repo fork myworkspace/my-service --into otherws --name my-fork\n\n# Transfer to another project (Server) or workspace (Cloud)\nbitbottle repo transfer MYPROJ/my-service --to NEWPROJ\nbitbottle repo transfer myworkspace/my-service --to otherws\n```\n\n`repo fork` returns a typed unsupported-capability error on Bitbucket Server /\nData Center, which has no fork primitive in its REST API. Both `rename` and\n`fork` accept `--json fields` and `--jq expr` for structured output.\n`repo transfer` works on both backends and also accepts `--json`/`--jq`.\n\n```bash\n# Get or set repository visibility\nbitbottle repo visibility MYPROJ/my-service          # prints \"public\" or \"private\"\nbitbottle repo visibility MYPROJ/my-service public   # make the repo public\nbitbottle repo visibility MYPROJ/my-service private  # make the repo private\n```\n\n`repo visibility` works on both Bitbucket Cloud and Server / Data Center.\nMCP tool: `repo_visibility(repo[, visibility])`.\n\n### Reading source at a ref\n\nRead file content and directory listings at any ref (branch, tag, commit\nhash) without cloning. Both backends; the bytes round-trip cleanly so\nbinary files survive `--out`.\n\n```bash\n# Read a file at a ref — straight to stdout\nbitbottle repo file get MYPROJ/my-service README.md --ref main\n\n# Pin a tag and write to disk (binary-safe)\nbitbottle repo file get MYPROJ/my-service logo.png --ref v1.2.0 --out logo.png\n\n# List a directory at a ref. PATH defaults to the repo root.\nbitbottle repo tree MYPROJ/my-service --ref main\nbitbottle repo tree MYPROJ/my-service cmd --ref main\n\n# Structured output for scripts and agents\nbitbottle repo tree MYPROJ/my-service --ref main --json path,type,size\nbitbottle repo tree MYPROJ/my-service --ref main --jq '.[]|select(.type==\"dir\").path'\n```\n\n`type` is normalised to `file` or `dir` across both backends. Submodules\nsurface as `dir` (with the submodule pointer in `hash`) so renderers can\nrecurse uniformly without a special case. The MCP equivalents are\n`get_file_content` and `list_tree`.\n\n### Workspaces \u0026 Projects (Cloud only)\n\n```bash\n# Workspaces the authenticated user belongs to\nbitbottle workspace list\nbitbottle workspace list --json slug,name --jq '.[].slug'\n\n# Projects within a workspace\nbitbottle project list myworkspace\nbitbottle project list myworkspace --limit 100\n\n# Members of a workspace\nbitbottle workspace member list myworkspace\nbitbottle workspace member list              # inferred from pinned repo\nbitbottle workspace member list myworkspace --json\n\n# Webhooks for a workspace\nbitbottle workspace hook list myworkspace\nbitbottle workspace hook list myworkspace --json\n\nbitbottle workspace hook create myworkspace --url https://example.com/hook --events repo:push,pullrequest:created\nbitbottle workspace hook create myworkspace --url https://example.com/hook --events repo:push --events pullrequest:created\n\nbitbottle workspace hook delete myworkspace WEBHOOK-UUID\n\n# Workspace permissions (Cloud only)\nbitbottle workspace perms list myworkspace\nbitbottle workspace perms list myworkspace --json\n\nbitbottle workspace perms repo list myworkspace\n\nbitbottle workspace perms grant myworkspace --user alice --permission member\nbitbottle workspace perms revoke myworkspace --user alice --confirm\n```\n\nAll commands surface a typed unsupported-capability error against\nBitbucket Server / Data Center hosts (workspaces are a Cloud concept).\n\n### User Profile\n\n```bash\n# Display the currently authenticated user's profile\nbitbottle user view\n\n# JSON output\nbitbottle user view --json\n\n# Filter with jq\nbitbottle user view --json slug,name --jq '.slug'\n```\n\nWorks on both Bitbucket Cloud and Bitbucket Server / Data Center.\n\n### Search _(Cloud only)_\n\n```bash\n# Search across the workspace inferred from the current checkout's pinned default\nbitbottle search code 'TODO'\n\n# Explicit workspace, custom limit\nbitbottle search code 'foo bar' --workspace myws --limit 50\n\n# Path-restricted query, JSON for scripting\nbitbottle search code 'path:README' --workspace myws --json path,repository\nbitbottle search code 'TODO' --workspace myws --json path --jq '.[].path'\n```\n\nBitbucket Cloud's query language (`path:`, `lang:`, `repo:`, exact-phrase\nquoting, etc.) is passed through verbatim — bitbottle does not translate\noperators. The matched-segment shape (`pathMatches`, `contentMatches`)\nis preserved on the JSON side so renderers can highlight the matched\nruns. Bitbucket Server / Data Center has no first-class code-search\nREST endpoint; invocations against a Server host return the typed\n`host.unsupported` error.\n\n### Code Insights _(Bitbucket Server / DC only)_\n\nPost build / quality / security analysis results as structured annotations\non commits. Requires Bitbucket Server / Data Center.\n\n```bash\n# Create or update a report (upsert by key)\nbitbottle --hostname git.example.com code-insights report set \\\n  MYPROJ/my-service abc123def456 my-scanner \\\n  --title \"Security Scan\" --result PASS \\\n  --report-type SECURITY --reporter \"semgrep\"\n\n# List all reports for a commit\nbitbottle --hostname git.example.com code-insights report list \\\n  MYPROJ/my-service abc123def456\n\n# View a single report as JSON\nbitbottle --hostname git.example.com code-insights report view \\\n  MYPROJ/my-service abc123def456 my-scanner \\\n  --json key,title,result,details\n\n# Bulk-add annotations from a JSON file\nbitbottle --hostname git.example.com code-insights annotation add \\\n  MYPROJ/my-service abc123def456 my-scanner \\\n  --from-json @findings.json\n\n# Single annotation\nbitbottle --hostname git.example.com code-insights annotation add \\\n  MYPROJ/my-service abc123def456 my-scanner \\\n  --path src/main.go --line 42 --severity HIGH --type BUG \\\n  --message \"Potential null dereference\"\n\n# List annotations for a report\nbitbottle --hostname git.example.com code-insights annotation list \\\n  MYPROJ/my-service abc123def456 my-scanner --json path,severity,message\n\n# Delete a report and all its annotations\nbitbottle --hostname git.example.com code-insights report delete \\\n  MYPROJ/my-service abc123def456 my-scanner\n```\n\n#### Merge checks (experimental)\n\nConfigure a Code Insights report as a required gate for PR merges. The\nunderlying API is partly undocumented — commands are marked experimental.\n\n```bash\n# Require the \"my-scanner\" report to pass before merging\nbitbottle --hostname git.example.com code-insights merge-check set \\\n  MYPROJ/my-service required-scan \\\n  --report-key my-scanner --must-pass --min-severity MEDIUM\n\n# Inspect the current merge-check configuration\nbitbottle --hostname git.example.com code-insights merge-check get \\\n  MYPROJ/my-service required-scan\n\n# Remove the merge check\nbitbottle --hostname git.example.com code-insights merge-check delete \\\n  MYPROJ/my-service required-scan\n```\n\nInvoking any `code-insights` command against a Bitbucket Cloud host returns\nthe typed `host.unsupported` error.\n\n### Mirror Servers _(Bitbucket Server / DC only)_\n\nList and inspect Smart Mirror servers configured on a Bitbucket Server instance.\n\n```bash\n# List all mirror servers\nbitbottle mirror list --hostname git.example.com\n\n# View a specific mirror server\nbitbottle mirror view MIRROR-ID --hostname git.example.com\n\n# List repos mirrored by a specific server\nbitbottle mirror repo list MIRROR-ID --hostname git.example.com\n\n# JSON output\nbitbottle mirror list --hostname git.example.com --json\nbitbottle mirror view MIRROR-ID --hostname git.example.com --json\n```\n\nRequires the Bitbucket Server Mirror module to be enabled and at least one mirror configured.\n\n### Permissions _(Bitbucket Server / DC only)_\n\nManage user and group permissions for projects and repositories.\nRequires `PROJECT_ADMIN` on the target project.\n\n```bash\n# List all grants for a project (users + groups, sorted ADMIN → WRITE → READ)\nbitbottle --hostname git.example.com perms project list MYPROJ\n\n# Grant a user PROJECT_WRITE on a project\nbitbottle --hostname git.example.com perms project grant MYPROJ PROJECT_WRITE --user alice\n\n# Grant a group PROJECT_READ on a project\nbitbottle --hostname git.example.com perms project grant MYPROJ PROJECT_READ --group \"qa team\"\n\n# Revoke a user's permission on a project\nbitbottle --hostname git.example.com perms project revoke MYPROJ --user bob\n\n# List all grants for a repository\nbitbottle --hostname git.example.com perms repo list MYPROJ/my-service\n\n# Grant a user REPO_WRITE on a repository\nbitbottle --hostname git.example.com perms repo grant MYPROJ/my-service REPO_WRITE --user carol\n\n# Revoke a group's permission on a repository\nbitbottle --hostname git.example.com perms repo revoke MYPROJ/my-service --group \"qa team\"\n\n# Structured output\nbitbottle --hostname git.example.com perms project list MYPROJ --json permission,subject\nbitbottle --hostname git.example.com perms project list MYPROJ --jq '.[] | select(.permission == \"PROJECT_ADMIN\")'\n```\n\nIf a grant call would **downgrade** an existing permission (e.g. ADMIN → READ),\n`grant` prompts for confirmation on a TTY. Pass `--force` to skip the prompt.\n\n### Commit Files\n\nList files added, modified, or deleted in a specific commit. Both Bitbucket\nCloud and Server / Data Center are supported.\n\n```bash\n# List files changed in a commit (repo from git remote)\nbitbottle commit files abc1234\n\n# Explicit repo\nbitbottle commit files abc1234 MYPROJ/my-service\n\n# Structured output\nbitbottle commit files abc1234 MYPROJ/my-service --json\nbitbottle commit files abc1234 MYPROJ/my-service --jq '.[].path'\n```\n\nOutput columns: `STATUS`, `PATH`, `+ADDITIONS`, `-DELETIONS`.\nLine counts are not available on Bitbucket Server / Data Center (always 0).\n\n### Commit Comments\n\nAdd and manage review-style comments on individual commits. Both Bitbucket\nCloud and Server / Data Center are supported.\n\n```bash\n# List all comments on a commit\nbitbottle commit comment list MYPROJ/my-service abc1234\n\n# Add a comment\nbitbottle commit comment add MYPROJ/my-service abc1234 --body \"LGTM\"\n\n# Edit an existing comment (COMMENT_ID from list --json id)\nbitbottle commit comment edit MYPROJ/my-service abc1234 1234 --body \"Updated text\"\n\n# Delete a comment\nbitbottle commit comment delete MYPROJ/my-service abc1234 1234\n\n# Structured output\nbitbottle commit comment list MYPROJ/my-service abc1234 --json id,author,body\nbitbottle commit comment list MYPROJ/my-service abc1234 --jq '.[].body'\n\n# Emoji reactions (Bitbucket Server / DC only)\nbitbottle commit comment list MYPROJ/my-service abc1234 --reactions   # adds REACTIONS column\nbitbottle commit comment react   MYPROJ/my-service abc1234 1234 --emoji thumbs_up\nbitbottle commit comment unreact MYPROJ/my-service abc1234 1234 --emoji thumbs_up\n```\n\nOn Bitbucket Server / Data Center, `edit` and `delete` use optimistic\nconcurrency (fetches the current `version` before writing). A 409 Conflict\nmeans the comment changed between calls — retry.\n\n### Raw API\n\n```bash\n# Any endpoint not yet wrapped\nbitbottle api 2.0/user\nbitbottle api --paginate --jq '.[].full_name' '2.0/repositories/{workspace}'\nbitbottle api -X POST -F 'title=hotfix' -F 'source.branch.name=hotfix/x' \\\n  '2.0/repositories/{workspace}/{repo_slug}/pullrequests'\n```\n\n### Context (one-call orientation)\n\n`bitbottle context` collapses three previously independent calls\n(`auth status`, `repo view`, `git status`) into a single structured\nsnapshot of where you are. Especially useful for AI agents that drive\nbitbottle through MCP — `get_context` is the standard first call.\n\n```bash\nbitbottle context\n# Host:           git.example.com\n# Backend:        server\n# Project:        PROJ\n# Slug:           repo\n# Branch:         feat/ctx\n# Default branch: main\n# Ahead/Behind:   2 / 0\n# User:           alice (Alice Smith)\n\nbitbottle context --json host,project,slug,branch,default_branch,ahead,behind,user,backend\nbitbottle context --json user --jq '.user.slug'\n```\n\nOutside a git repo `project`, `slug`, `branch`, and `default_branch`\nare empty; `ahead` and `behind` are omitted from the JSON output\nentirely (and rendered as `(unknown — run 'git fetch')` in the human\ntable). They are also omitted whenever `git rev-list` cannot compute\nthe counts — `0 / 0` would falsely read as \"in sync\". `host`, `user`,\nand `backend` still resolve via the configured (or `--hostname`) host.\n\n### Outside a git repo\n\n```bash\nbitbottle pr list   -R git.example.com/PROJ/api\nbitbottle pr merge 42 -R git.example.com/PROJ/api\n```\n\n---\n\n## MCP Server — AI Assistant Integration\n\n`bitbottle mcp serve` exposes all CLI operations as [Model Context Protocol](https://modelcontextprotocol.io) tools. Claude Desktop, Claude Code, and any MCP client can call Bitbucket as native tools — no raw API, no output parsing.\n\n**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n```json\n{\n  \"mcpServers\": {\n    \"bitbottle\": {\n      \"command\": \"bitbottle\",\n      \"args\": [\"mcp\", \"serve\"]\n    }\n  }\n}\n```\n\n**Claude Code** (`.mcp.json` in project root):\n```json\n{\n  \"mcpServers\": {\n    \"bitbottle\": {\n      \"command\": \"bitbottle\",\n      \"args\": [\"mcp\", \"serve\"]\n    }\n  }\n}\n```\n\n**Docker** (no local install required):\n```bash\ndocker run --rm -i \\\n  -v ~/.config/bitbottle:/root/.config/bitbottle \\\n  proggarapsody/bitbottle mcp serve\n```\n\nThe MCP server uses the same `~/.config/bitbottle/hosts.yml` credentials as the CLI — no separate auth setup needed.\n\n---\n\n## Cloud vs Server / Data Center\n\nbitbottle automatically routes to the correct backend based on hostname: `bitbucket.org` → Cloud; anything else → Server/DC. Override with `backend_type: cloud|server` in `hosts.yml`.\n\nThe same commands and flags work on both backends. Differences in API shape, pagination style, and endpoint paths are handled internally — no `--cloud` / `--server` flags needed.\n\n---\n\n## Shell Completion\n\n```bash\nbitbottle completion --shell bash   \u003e\u003e ~/.bash_profile\nbitbottle completion --shell zsh    \u003e\u003e ~/.zshrc\nbitbottle completion --shell fish   \u003e ~/.config/fish/completions/bitbottle.fish\nbitbottle completion --shell powershell \u003e\u003e $PROFILE\n```\n\n---\n\n## Environment Variables\n\n| Variable | Effect |\n|---|---|\n| `BB_TOKEN` | Override auth token |\n| `BB_HOST` | Default hostname |\n| `BB_REPO` | Override `[HOST/]PROJECT/REPO` |\n| `BB_FORCE_TTY` | Force aligned/coloured output in pipes |\n| `NO_COLOR` | Disable colour (standard) |\n\nFull list in [`internal/envvars/envvars.go`](internal/envvars/envvars.go).\n\n## Colour \u0026 pager\n\nState columns in TTY tables are colourised: `OPEN` / `SUCCESSFUL` /\nactive webhooks render green; `MERGED` magenta; `DECLINED` /\n`SUPERSEDED` / `FAILED` / `ERROR` / `STOPPED` / inactive webhooks red;\n`IN_PROGRESS` / `PENDING` yellow. Colour applies to TTY table output\nonly — JSON (`--json`) and piped output stay raw.\n\nDisable colour with the global `--no-color` flag or by setting\n`NO_COLOR=1` in the environment. JSON output is never colourised.\n\nLong-output commands (`pr diff`, `commit log`) pipe through `$PAGER`\nwhen stdout is a TTY (default `less -FRX`). Set `PAGER=cat` to disable.\n\n---\n\n## Extensions\n\nbitbottle supports third-party extensions. Extension repositories must be named `bitbottle-\u003cname\u003e`.\n\n```bash\nbitbottle extension install USER/bitbottle-\u003cname\u003e  # install from GitHub\nbitbottle extension install --local PATH           # install from local dir\nbitbottle extension list                           # list installed\n```\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). Run `go test ./...` before sending a PR.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fproggarapsody%2Fbitbottle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fproggarapsody%2Fbitbottle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fproggarapsody%2Fbitbottle/lists"}