bkt

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Bitbucket CLI (bkt)

Bitbucket CLI（bkt）

bkt

is a unified CLI for Bitbucket Data Center and Bitbucket Cloud. It mirrors

gh

ergonomics and provides structured JSON/YAML output for automation.

bkt

是适用于Bitbucket Data Center和Bitbucket Cloud的统一CLI工具。它借鉴了

gh

的设计风格，可提供结构化的JSON/YAML输出以支持自动化操作。

Dependency Check

依赖检查

Before executing any
bkt
command, verify the CLI is installed:

bash

bkt --version

If the command fails or

bkt

is not found, install it using one of these methods:

Platform	Command
macOS/Linux	`brew install avivsinai/tap/bitbucket-cli`
Windows	`scoop bucket add avivsinai https://github.com/avivsinai/scoop-bucket && scoop install bitbucket-cli`
Go	`go install github.com/avivsinai/bitbucket-cli/cmd/bkt@latest`
Binary	Download from GitHub Releases

Only proceed with
bkt
commands after confirming installation succeeds.

在执行任何
bkt
命令之前，请确认CLI已安装：

bash

bkt --version

如果命令执行失败或未找到

bkt

，请通过以下方式之一安装：

平台	命令
macOS/Linux	`brew install avivsinai/tap/bitbucket-cli`
Windows	`scoop bucket add avivsinai https://github.com/avivsinai/scoop-bucket && scoop install bitbucket-cli`
Go	`go install github.com/avivsinai/bitbucket-cli/cmd/bkt@latest`
二进制包	从GitHub Releases下载

确认安装成功后，再执行
bkt
命令。

Authentication

身份验证

bash

undefined

bash

undefined

Data Center (opens browser for PAT creation)

Data Center（打开浏览器创建PAT）

bkt auth login https://bitbucket.example.com --web

Data Center (direct)

Data Center（直接方式）

bkt auth login https://bitbucket.example.com --username alice --token <PAT>

Bitbucket Cloud

bkt auth login https://bitbucket.org --kind cloud --web

Check auth status

检查身份验证状态

bkt auth status


**Bitbucket Cloud Token Requirements:**
- Create an "API token with scopes" (not a general API token)
- Select **Bitbucket** as the application
- Required scope: **Account: Read** (`read:user:bitbucket`)
- Additional scopes as needed: Repositories, Pull requests, Issues

bkt auth status


**Bitbucket Cloud令牌要求：**
- 创建“带权限范围的API令牌”（而非通用API令牌）
- 选择**Bitbucket**作为应用
- 必需权限范围：**账号：读取**（`read:user:bitbucket`）
- 根据需要添加额外权限范围：仓库、拉取请求、问题

Contexts

上下文管理

Contexts store host, project/workspace, and default repo settings:

bash

undefined

上下文用于存储主机、项目/工作区和默认仓库设置：

bash

undefined

Create context for Data Center

为Data Center创建上下文

bkt context create dc-prod --host bitbucket.example.com --project ABC --set-active

Create context for Cloud

为Cloud创建上下文

bkt context create cloud-team --host bitbucket.org --workspace myteam --set-active

List and switch contexts

列出并切换上下文

bkt context list bkt context use cloud-team

undefined

bkt context list bkt context use cloud-team

undefined

Quick Command Reference

快速命令参考

Task	Command
List repos	`bkt repo list`
View repo	`bkt repo view <slug>`
Clone repo	`bkt repo clone <slug> --ssh`
Create repo	`bkt repo create <name> --description "..."`
List PRs	`bkt pr list --state OPEN`
View PR	`bkt pr view <id>`
Create PR	`bkt pr create --title "..." --source feature --target main`
Merge PR	`bkt pr merge <id>`
PR checks	`bkt pr checks <id> --wait`
List branches	`bkt branch list`
Create branch	`bkt branch create <name> --from main`
Delete branch	`bkt branch delete <name>`
List issues (Cloud)	`bkt issue list --state open`
Create issue	`bkt issue create -t "Bug title" -k bug`
Webhooks	`bkt webhook list`
Run pipeline	`bkt pipeline run --ref main`
API escape hatch	`bkt api /rest/api/1.0/projects`

任务	命令
列出仓库	`bkt repo list`
查看仓库详情	`bkt repo view <slug>`
克隆仓库	`bkt repo clone <slug> --ssh`
创建仓库	`bkt repo create <name> --description "..."`
列出拉取请求	`bkt pr list --state OPEN`
查看拉取请求详情	`bkt pr view <id>`
创建拉取请求	`bkt pr create --title "..." --source feature --target main`
合并拉取请求	`bkt pr merge <id>`
拉取请求检查	`bkt pr checks <id> --wait`
列出分支	`bkt branch list`
创建分支	`bkt branch create <name> --from main`
删除分支	`bkt branch delete <name>`
列出问题（仅Cloud）	`bkt issue list --state open`
创建问题	`bkt issue create -t "Bug title" -k bug`
Webhook管理	`bkt webhook list`
运行流水线	`bkt pipeline run --ref main`
原生API调用	`bkt api /rest/api/1.0/projects`

Repository Operations

仓库操作

bash

bkt repo list --limit 20
bkt repo list --workspace myteam          # Cloud workspace override
bkt repo view platform-api
bkt repo create data-pipeline --description "Data ingestion" --project DATA
bkt repo browse --project DATA --repo platform-api
bkt repo clone platform-api --ssh

bash

bkt repo list --limit 20
bkt repo list --workspace myteam          # 覆盖Cloud工作区设置
bkt repo view platform-api
bkt repo create data-pipeline --description "数据采集" --project DATA
bkt repo browse --project DATA --repo platform-api
bkt repo clone platform-api --ssh

Pull Request Workflows

拉取请求工作流

bash

undefined

bash

undefined

List and view

列出和查看

bkt pr list --state OPEN --limit 10 bkt pr list --mine # PRs you authored bkt pr view 42 bkt pr view 42 --web # Open in browser

bkt pr list --state OPEN --limit 10 bkt pr list --mine # 你创建的拉取请求 bkt pr view 42 bkt pr view 42 --web # 在浏览器中打开

Create and edit

创建和编辑

bkt pr create --title "feat: cache" --source feature/cache --target main --reviewer alice bkt pr edit 123 --title "New title" --body "Updated description"

bkt pr create --title "feat: 缓存功能" --source feature/cache --target main --reviewer alice bkt pr edit 123 --title "新标题" --body "更新后的描述"

Review and merge

评审和合并

bkt pr approve 42 bkt pr comment 42 --text "LGTM" bkt pr merge 42 --message "merge: feature/cache" bkt pr merge 42 --strategy fast-forward

CI/build status

CI/构建状态

bkt pr checks 42 # Show build status bkt pr checks 42 --wait # Wait for builds to complete bkt pr checks 42 --wait --timeout 5m # With timeout bkt pr checks 42 --fail-fast # Exit on first failure

bkt pr checks 42 # 查看构建状态 bkt pr checks 42 --wait # 等待构建完成 bkt pr checks 42 --wait --timeout 5m # 设置超时时间 bkt pr checks 42 --fail-fast # 首次失败即退出

Checkout locally

本地检出

bkt pr checkout 42 # Fetches to pr/42 branch

undefined

bkt pr checkout 42 # 拉取到pr/42分支

undefined

Branch Management

分支管理

bash

bkt branch list
bkt branch list --filter "feature/*"
bkt branch create release/1.9 --from main
bkt branch delete feature/old-stuff
bkt branch set-default main               # DC only
bkt branch protect add main --type fast-forward-only  # DC only

bash

bkt branch list
bkt branch list --filter "feature/*"
bkt branch create release/1.9 --from main
bkt branch delete feature/old-stuff
bkt branch set-default main               # 仅Data Center支持
bkt branch protect add main --type fast-forward-only  # 仅Data Center支持

Issue Tracking (Bitbucket Cloud Only)

问题追踪（仅Bitbucket Cloud）

bash

bkt issue list --state open --kind bug
bkt issue view 42 --comments
bkt issue create -t "Login broken" -k bug -p major
bkt issue edit 42 --assignee "{uuid}" --priority critical
bkt issue close 42
bkt issue reopen 42
bkt issue comment 42 -b "Fixed in v1.2.0"
bkt issue status                          # Your assigned/created issues

Issue kinds:

bug

enhancement

proposal

task

Priorities:

trivial

minor

major

critical

blocker

bash

bkt issue list --state open --kind bug
bkt issue view 42 --comments
bkt issue create -t "登录功能异常" -k bug -p major
bkt issue edit 42 --assignee "{uuid}" --priority critical
bkt issue close 42
bkt issue reopen 42
bkt issue comment 42 -b "已在v1.2.0版本修复"
bkt issue status                          # 你分配/创建的问题

问题类型：

bug

、

enhancement

、

proposal

、

task

优先级：

trivial

、

minor

、

major

、

critical

、

blocker

Webhooks

Webhook管理

bash

bkt webhook list
bkt webhook create --name "CI" --url https://ci.example.com/hook --event repo:refs_changed
bkt webhook delete <id>
bkt webhook test <id>

bash

bkt webhook list
bkt webhook create --name "CI" --url https://ci.example.com/hook --event repo:refs_changed
bkt webhook delete <id>
bkt webhook test <id>

Pipelines (Cloud)

流水线（仅Cloud）

bash

bkt pipeline run --ref main --var ENV=staging
bkt pipeline list                         # Recent runs
bkt pipeline view <uuid>                  # Pipeline details
bkt pipeline logs <uuid>                  # Fetch logs
bkt status pipeline <uuid>                # Alt: status check

bash

bkt pipeline run --ref main --var ENV=staging
bkt pipeline list                         # 最近的运行记录
bkt pipeline view <uuid>                  # 流水线详情
bkt pipeline logs <uuid>                  # 获取日志
bkt status pipeline <uuid>                # 替代方式：状态检查

Permissions (DC)

权限管理（仅Data Center）

bash

bkt perms project list --project DATA
bkt perms project grant --project DATA --user alice --perm PROJECT_WRITE
bkt perms repo list --project DATA --repo platform-api
bkt perms repo grant --project DATA --repo api --user alice --perm REPO_WRITE

bash

bkt perms project list --project DATA
bkt perms project grant --project DATA --user alice --perm PROJECT_WRITE
bkt perms repo list --project DATA --repo platform-api
bkt perms repo grant --project DATA --repo api --user alice --perm REPO_WRITE

Raw API Access

原生API访问

For endpoints not yet wrapped:

bash

bkt api /rest/api/1.0/projects --param limit=100 --json
bkt api /repositories --param workspace=myteam --field pagelen=50

对于尚未封装的接口：

bash

bkt api /rest/api/1.0/projects --param limit=100 --json
bkt api /repositories --param workspace=myteam --field pagelen=50

Output Modes

输出模式

All commands support structured output:

bash

bkt pr list --json                        # JSON output
bkt pr list --yaml                        # YAML output
bkt pr list --json | jq '.pull_requests[0].title'

所有命令均支持结构化输出：

bash

bkt pr list --json                        # JSON格式输出
bkt pr list --yaml                        # YAML格式输出
bkt pr list --json | jq '.pull_requests[0].title'

Global Options

全局选项

```
--json
```
/
```
--yaml
```
— Structured output
```
--context <name>
```
— Use specific context
```
--project <key>
```
— Override project (DC)
```
--workspace <name>
```
— Override workspace (Cloud)
```
--repo <slug>
```
— Override repository

```
--json
```
/
```
--yaml
```
— 结构化输出
```
--context <name>
```
— 使用指定上下文
```
--project <key>
```
— 覆盖项目设置（仅Data Center）
```
--workspace <name>
```
— 覆盖工作区设置（仅Cloud）
```
--repo <slug>
```
— 覆盖仓库设置

Environment Variables

环境变量

```
BKT_CONFIG_DIR
```
— Config directory override
```
BKT_ALLOW_INSECURE_STORE
```
— Allow file-based credential storage
```
BKT_KEYRING_TIMEOUT
```
— Keyring operation timeout (for example
```
2m
```
)

```
BKT_CONFIG_DIR
```
— 覆盖配置目录
```
BKT_ALLOW_INSECURE_STORE
```
— 允许基于文件的凭据存储
```
BKT_KEYRING_TIMEOUT
```
— 密钥环操作超时时间（例如
```
2m
```
）

References

参考资料

Full command reference: See references/commands.md

完整命令参考：查看references/commands.md