bitbottle

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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; consult
-h
for any flag you're not sure about.

一款适用于Bitbucket Server/DC和Cloud的gh风格CLI。本文档包含路由规则及安全规范——如需命令详情，请查阅对应参考文档。无需记忆本文档内容；对不确定的参数，请使用
-h
查看帮助。

When to load which reference

何时加载对应参考文档

Task	Open
Auth, hosts.yml, env vars, multi-host setup	`references/auth.md`
PR lifecycle (list/view/create/merge/approve/comment/…)	`references/pr.md`
Repos, branches, tags, commits, clone	`references/repos.md`
Raw REST passthrough, pagination, MCP server config	`references/api.md`

When the user's task spans two areas, load both. Don't load all of them speculatively.

任务	打开文档
认证、hosts.yml配置、环境变量、多主机设置	`references/auth.md`
PR生命周期（列出/查看/创建/合并/批准/评论/…）	`references/pr.md`
仓库、分支、标签、提交、克隆	`references/repos.md`
原生REST透传、分页、MCP服务器配置	`references/api.md`

当用户的任务涉及两个领域时，加载对应的两份文档。请勿随意加载所有文档。

Safety rules (always apply)

安全规范（始终适用）

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.
Confirm before destructive ops.
```
repo delete
```
,
```
branch delete
```
,
```
tag delete
```
,
```
pr decline
```
,
```
pr merge
```
are not undoable. Before running, show the user:
- the exact command,
- the target host and
```
PROJECT/REPO
```
  ,
- the PR ID / branch / tag name, then wait for explicit confirmation.
Don't fabricate flags. bitbottle has gh-like shape but not gh-compatible flags. If a flag isn't in the reference and the user asks for behavior you can't find, run
```
bitbottle <command> -h
```
first. Flags that DO NOT exist in 1.13.1 (commonly assumed):
```
--author
```
,
```
--state all
```
,
```
--mine
```
,
```
--all
```
,
```
--reviewer @me
```
.
Prefer JSON for automation. Parsing TTY tables is brittle; use
```
--json field1,field2 --jq 'expr'
```
whenever the output feeds another step. Most list/view commands support
```
--json
```
and
```
--jq
```
— verify per-command with
```
-h
```
.
Check the version on behavior mismatches. If a command behaves differently from this file, run
```
bitbottle --version
```
. This skill was last verified against 1.14.0.

切勿回显令牌。通过标准输入（
```
--with-token
```
）或
```
BB_TOKEN
```
环境变量传递令牌。绝不要将PAT/应用密码放在命令行中——这会被记录到shell历史里。
执行破坏性操作前确认。
```
repo delete
```
、
```
branch delete
```
、
```
tag delete
```
、
```
pr decline
```
、
```
pr merge
```
这些操作不可撤销。执行前需向用户展示：
- 完整的命令内容，
- 目标主机及
```
PROJECT/REPO
```
  ，
- PR ID / 分支 / 标签名称，然后等待用户明确确认。
不要虚构参数。bitbottle的风格与gh类似，但参数并不兼容。如果参考文档中没有某个参数，且用户询问的行为无法找到，请先执行
```
bitbottle <command> -h
```
查看帮助。1.13.1版本中不存在的常见假设参数包括：
```
--author
```
、
```
--state all
```
、
```
--mine
```
、
```
--all
```
、
```
--reviewer @me
```
。
自动化场景优先使用JSON。解析TTY表格的方式很脆弱；当输出需要作为后续步骤的输入时，请使用
```
--json field1,field2 --jq 'expr'
```
。大多数列表/查看命令都支持
```
--json
```
和
```
--jq
```
参数——请通过
```
-h
```
验证具体命令是否支持。
行为不符时检查版本。如果命令行为与本文档不符，请执行
```
bitbottle --version
```
查看版本。本技能最后验证的版本为1.14.0。

Repo targeting (high-frequency)

仓库定位（高频操作）

Inside a Bitbucket checkout: host/project/repo auto-detected.

Outside one (or to override), pass

-R [HOST/]PROJECT/REPO

bash

bitbottle pr list      -R git.example.com/PROJ/repo
bitbottle pr approve 42 -R git.example.com/PROJ/repo

Pin a default for the current checkout (writes

.git/config

bitbottle repo set-default HOST/PROJ/repo

. After this, every command in that checkout runs without

-R

在Bitbucket本地仓库目录中：主机/项目/仓库会被自动识别。

在仓库目录外（或需覆盖自动识别），请传递

-R [HOST/]PROJECT/REPO

参数：

bash

bitbottle pr list      -R git.example.com/PROJ/repo
bitbottle pr approve 42 -R git.example.com/PROJ/repo

为当前本地仓库设置默认仓库（会写入

.git/config

）：

bitbottle repo set-default HOST/PROJ/repo

。设置完成后，该目录下的所有命令无需再添加

-R

参数。

Cloud vs Server/DC (decision table)

Cloud与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 commands	`pipeline *` , `pr request-changes`	—

Custom-hostname Cloud Data Center? Force routing in

hosts.yml

backend_type: cloud

(or

server

). See

references/auth.md

	Cloud（ `bitbucket.org` ）	Server/DC（自托管）
认证上下文参数	`--email you@…`	`--username your.user`
令牌类型	App Password / API令牌	PAT（ `BBDC-…` ）
API基础路径	`2.0/…`	`rest/api/1.0/…`
Cloud专属命令	`pipeline *` 、 `pr request-changes`	—

自定义主机名的Cloud Data Center？在

hosts.yml

中强制指定路由类型：

backend_type: cloud

（或

server

）。详情请查阅

references/auth.md

。

Hot-path env vars

高频环境变量

Var	Effect
`BB_TOKEN`	Token override for API calls (CI use)
`BB_HOST`	Default `--hostname`
`BB_REPO`	Default `-R [HOST/]PROJECT/REPO`
`BB_PROMPT_DISABLED`	Fail rather than prompt (non-interactive scripts)
`BB_CONFIG_DIR`	Override config dir (default `$XDG_CONFIG_HOME/bitbottle` )

Editor/pager/browser/force-tty/no-color overrides are in

references/auth.md

变量	作用
`BB_TOKEN`	覆盖API调用使用的令牌（适用于CI场景）
`BB_HOST`	默认 `--hostname` 参数值
`BB_REPO`	默认 `-R [HOST/]PROJECT/REPO` 参数值
`BB_PROMPT_DISABLED`	非交互式脚本中，遇到需要提示的场景时直接失败
`BB_CONFIG_DIR`	覆盖配置目录（默认路径为 `$XDG_CONFIG_HOME/bitbottle` ）

编辑器/分页器/浏览器/强制TTY/无颜色输出的相关配置，请查阅

references/auth.md

。

Failure-mode hints

故障排查提示

When you see one of these messages, you know the fix:

"not authenticated; run
bitbottle auth login
first" → no host configured. Run
```
auth login
```
. See
```
references/auth.md
```
.
"multiple hosts configured; specify hostname" → pass
```
--hostname HOST
```
or use
```
-R HOST/PROJ/repo
```
.
"no git remotes found; pass [HOST/]PROJECT/REPO …" → outside a Bitbucket checkout. Pass
```
-R
```
or
```
cd
```
into the right repo.
Cloud auth fails → most often a missing or wrong
```
--email
```
. App passwords need the Atlassian email, not the username.
Server/DC auth fails → missing
```
--username
```
, or
```
--git-protocol ssh
```
was used with an HTTPS-only PAT.

当出现以下消息时，对应的解决方法如下：

"未认证；请先执行
bitbottle auth login
" → 未配置主机。执行
```
auth login
```
命令。详情请查阅
```
references/auth.md
```
。
"已配置多个主机；请指定主机名" → 传递
```
--hostname HOST
```
参数或使用
```
-R HOST/PROJ/repo
```
。
"未找到git远程仓库；请传递[HOST/]PROJECT/REPO …" → 当前不在Bitbucket本地仓库目录中。传递
```
-R
```
参数或切换到正确的仓库目录。
Cloud认证失败 → 最常见原因是缺少或错误的
```
--email
```
参数。应用密码需要使用Atlassian邮箱，而非用户名。
Server/DC认证失败 → 缺少
```
--username
```
参数，或使用了
```
--git-protocol ssh
```
但令牌仅支持HTTPS。

Install / version

安装 / 版本

npm install -g @proggarapsody/bitbottle

installs the CLI and auto-registers this skill across detected agent runtimes (Claude Code, Cursor, Codex, …). To check or refresh after a release:

bash

bitbottle --version
bitbottle skill install            # remove + reinstall, picks up latest
bitbottle skill path               # where the skill landed

执行

npm install -g @proggarapsody/bitbottle

即可安装该CLI，并会在检测到的Agent运行时（Claude Code、Cursor、Codex等）中自动注册本技能。如需检查版本或在新版本发布后更新：

bash

bitbottle --version
bitbottle skill install            # 卸载并重新安装，获取最新版本
bitbottle skill path               # 查看技能安装路径