bitbottle

bitbottle CLI

适用于 Bitbucket Server/DC 和 Cloud 的 gh 风格 CLI。本文档是路由索引，另包含不可违反的安全规则——请加载相应的参考文档以了解命令详情。**不要死记本文档；运行 bitbottle <cmd> -h 获取权威的命令格式和标志列表。**如果行为与本文档不符，请运行 bitbottle --version；以二进制文件为准。

根据任务加载相应参考文档

任务	打开
身份验证、hosts.yml、环境变量、多主机、auth migrate、auth doctor	references/auth.md
PR 生命周期（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
仓库、分支、标签、文件/目录树、可见性、编辑、转移、关注者、仓库标签 list/create/update/delete、仓库 pr-settings get、仓库 pr-settings set、仓库下载 list/upload/get/delete、仓库克隆（MCP：clone_repo）、仓库 hook list/view/enable/disable/settings get/set（仅 Server/DC）、仓库同步 Cloud fork sync（MCP：sync_repo）	references/repos.md
提交（log、search、view/files/status/comment/comment-react）	references/commit.md
Pipelines、pipeline config get/enable/disable、计划任务、缓存、关注、触发、test-report view、test-case list、SSH 密钥对、known hosts、OIDC config/keys（仅 Cloud）	references/pipeline.md
Pipeline 运行器——list / create / delete（仅 Cloud）	references/runner.md
Code Insights 报告/注释（Cloud + Server/DC）；merge-check（仅 Server/DC）	references/code-insights.md
问题、评论、附件（list/delete）、投票/取消投票、关注/取消关注、活动/更改日志（仅 Cloud）	references/issues.md
问题里程碑 list/view（仅 Cloud）	references/milestone.md
问题版本 list/view/create/delete（仅 Cloud）	references/version.md
代码片段 list/view/create/delete、代码片段评论 list/add/delete（仅 Cloud）	references/snippet.md
部署 + 环境 + 变量（仅 Cloud）	references/deployment.md、references/variable.md
部署密钥（两者均支持）、分支规则（仅 Cloud）、ssh-keys（Cloud + Server/DC）	references/deploy-key.md、references/branch-rule.md、references/ssh-key.md
引用之间的差异、diff REF1..REF2	references/diff.md
分支比较（branch compare BASE..HEAD）——超前/落后计数 + 提交列表（Cloud + Server/DC）	references/branch.md
工作区 + Webhook + 工作区项目 CRUD + 工作区项目权限 + 工作区权限 + 工作区 pipeline 变量（仅 Cloud）、user view	references/workspace.md、references/user.md
镜像服务器（list/view/repo list）（仅 Server/DC）	references/mirror.md
命名凭据配置文件（profile create/use/list/delete）	references/profile.md
原始 REST 透传、分页、MCP 服务配置	references/api.md
扩展（extension install/list/upgrade/remove/exec、扩展脚手架）	references/extension.md
组管理——group list、group create、group delete、group member list、group member add、group member remove（仅 Server/DC）	references/groups.md
项目 CRUD——project server-list、project create、project view、project edit、project delete（仅 Server/DC）；project list WORKSPACE（仅 Cloud）	references/project.md
auth pat list/create/revoke（仅 Server/DC）	references/auth.md
主机信息——后端类型、基础 URL、版本、功能矩阵（host info [--json]）	references/host.md

如果任务涉及多个领域，请同时加载相应文档。不要臆测并加载无关文档。

安全规则（始终适用）

1. 绝不回显令牌。 通过标准输入（--with-token）或 BB_TOKEN 环境变量传递令牌。绝不要在命令行中填写 PAT/App Password——它会留在 shell 历史记录中。
2. 执行破坏性操作前先确认。 repo delete、repo rename、branch delete、tag delete、webhook delete、pr decline、pr merge 均不可撤销（在 Cloud 上，repo rename 会导致现有克隆的 origin URL 失效）。显示准确的命令以及解析后的 host/PROJECT/REPO 和 PR/branch/tag 名称，然后等待明确确认。
3. 不要编造标志。 bitbottle 的形式类似 gh，但标志与 gh 不兼容。如果某个标志不在 bitbottle <cmd> -h 中，就不要传入。常见的虚构标志：--author、--mine、--reviewer @me（没有“自己”哨兵值——请传入用户 slug）。
4. --json 是布尔标志，不是字段选择器。 --json 会以 JSON 格式输出完整对象；使用 --jq EXPR 进行筛选。传入 --json title,body 会被解析为 --json 加一个位置参数（title,body），并报错 accepts N arg(s), received N+1。若要了解字段名称：运行一次带 --json 的命令并检查对象。

参数形式（高频易错点）

bitbottle 对仓库目标的指定方式不一致——请遵循 -h 中的说明：

命令组	仓库参数	备注
pr *（view/list/create/merge/…）	-R [HOST/]PROJECT/REPO 标志	-R 是唯一方式；不能使用位置参数
repo *、branch *、tag *、webhook *	位置参数 PROJECT/REPO	-R 虽然出现在继承的标志列表中，但会被静默忽略——请将 PROJECT/REPO 作为位置参数传入，并单独使用 --hostname HOST
commit view PROJECT/REPO HASH	位置参数，先 PROJ/REPO
commit files HASH [PROJECT/REPO]	位置参数，先 HASH	与 commit view 顺序相反
commit cherry-pick HASH BRANCH [PROJECT/REPO]	位置参数，先 HASH，再 BRANCH	仅限 Server/DC（branch-utils 插件）；--message/-m 会覆盖提交消息
issue *、code-insights *	[PROJECT/REPO] 位置参数或 -R	可选；默认使用当前检出项

在任何 Bitbucket 检出目录之外，必须提供相关的位置参数或 -R。

MCP 工具统一使用一种规范的仓库参数形式：{project, slug}（以及可选的 hostname）——project 是 Server 项目键或 Cloud 工作区 slug，slug 是仓库 slug。以前使用单个 repo（WORKSPACE/REPO）字符串或 {project, repo} 的少数工具——compare_refs、list_pr_commits、list_pr_files、get_repo_pr_settings、set_repo_pr_settings——现在均接受 {project, slug}；旧形式还会兼容一个版本周期，但返回结果会附带弃用说明。每个工具的 tools/list 条目还会声明 _meta.backends（["server"]、["cloud"] 或两者）；针对 Cloud 主机调用仅支持 Server 的工具（反之亦然）时，会在发起任何 HTTP 请求之前返回 host.unsupported；未知的 hostname 会返回 host.unknown，并列出已配置的主机。

仓库目标与 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

Server/DC 使用自签名 CA？-k / --skip-tls-verify 是每个命令都会继承的标志。若要永久生效，请在 hosts.yml 中对应的主机条目上设置 skip_tls_verify: true（参见 references/auth.md）。

Cloud 与 Server/DC

此版本暂不支持 Cloud 自动合并。pr merge --auto、 pr merge --auto-off，以及 MCP merge_pr 中设置 auto=true 时，会在发起任何 HTTP 请求前返回 pr.automerge.unavailable，并提供可执行的提示。 普通合并、压缩合并和变基仍可用。Server/DC 自动合并 行为不变；尚未在 DC 上进行实时验证。

	Cloud（bitbucket.org）	Server/DC（可自托管）
身份验证上下文标志	--email you@…	--username your.user
令牌类型	App Password / API token	PAT（BBDC-…）
API 基础路径	2.0/…	rest/api/1.0/…
仅限 Cloud	pipeline *（list/view/run/stop/trigger/watch/logs/steps/schedule/cache/variable/config/test-report/test-case）、runner list、runner create、runner delete、issue *（包括 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 *（包括 workspace search、workspace perms *、workspace project perms *、workspace project default-reviewer *）、search、project list WORKSPACE	—
仅限 Server	—	admin user list/activate/deactivate/rename、admin license、admin cluster、admin secrets rotate、admin logging get/set、code-insights *、pr task *、pr suggestion apply、pr/commit comment react/unreact、pr reviewer-group *、repo pr-settings get、repo pr-settings set、group list、group create、group delete、group member list、group member add、group member remove、mirror list、mirror view、mirror repo list、project server-list、project create、project view、project edit、project delete、auth pat list、auth pat create、auth pat revoke、commit cherry-pick HASH BRANCH

对于使用自定义主机名的 Bitbucket Data Center，请在 hosts.yml 中设置 backend_type: cloud|server 以强制路由。

热路径环境变量

变量	作用
BB_TOKEN	覆盖令牌（用于 CI）
BB_HOST	默认的 --hostname
BB_REPO	默认的 -R [HOST/]PROJECT/REPO
BB_PROMPT_DISABLED	失败而非提示（非交互模式）
BB_CONFIG_DIR	覆盖配置目录（默认为 $XDG_CONFIG_HOME/bitbottle）

故障模式提示

消息	修复方法
not authenticated; run bitbottle auth login	未配置主机 — 运行 auth login。
multiple hosts configured; specify hostname	传入 --hostname HOST 或 -R HOST/PROJ/repo。
no git remotes found; pass [HOST/]PROJECT/REPO	当前目录不在检出目录中 — 传入位置参数或 -R。
在 --json … 后出现 accepts N arg(s), received N+1	你输入了 --json field1,field2；bitbottle 的 --json 是布尔选项。删除字段列表并使用 --jq。
warning: token found in hosts.yml — run bitbottle auth migrate	在令牌迁移到 OS 密钥环之前，每条命令都会打印此警告。运行一次 bitbottle auth migrate。
code-insights … unsupported on host	仅限 Server/DC 的功能。使用 bitbottle context 确认主机。
Cloud 身份验证失败	通常是缺少或错误的 --email — App Password 需要使用 Atlassian 邮箱，而不是用户名。
Server/DC 身份验证失败	缺少 --username，或使用 --git-protocol ssh 搭配仅支持 HTTPS 的 PAT。
凭据/密钥链/TLS/代理异常	bitbottle auth doctor [--hostname HOST] 会报告密钥环后端、令牌是否存在及其格式、基础 URL 可达性和身份验证是否成功。绝不会回显令牌。

流水线生命周期（仅限 Cloud）

# 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

仪表板

# 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

安装 / 版本

npm install -g @proggarapsody/bitbottle 会安装 CLI 并 自动注册此技能。对于非 npm 安装方式（Homebrew、Go、独立 二进制文件）：bitbottle skill install（刷新）、skill path（定位）、 skill remove（卸载）。