buildkite-cli

Buildkite CLI

Buildkite CLI（bk）提供对构建、作业、流水线、机密、制品、集群、队列和软件包的终端访问。使用它可以触发构建、跟踪日志、管理机密、运行本地 Agent，并在不离开命令行的情况下自动化 CI/CD 工作流。

提示： 本技能涵盖常见命令和用法模式。若要查看任何命令的完整标志详情，请运行 bk <command> --help。CLI 自带详尽的示例，可在其帮助输出中查看 — 对于具体标志，应优先以此为准。

快速开始

bk job list --build 需要 Buildkite CLI v3.53.0 或更高版本。如果该标志不可用，请运行 bk update。

# Install
brew install buildkite/buildkite/bk

# Authenticate (OAuth — opens a browser)
bk auth login

# Trigger a build on the current branch (pipeline auto-detected from the repo)
bk build create

# Watch the most recent build run
bk build watch

# Inspect build state, find failed jobs, and read a failed job's log
bk build view 429 --summary
bk job list --pipeline my-app --build 429 --state failed
bk job log <job-uuid>

大多数构建、作业、制品和流水线命令会根据当前 Git 仓库解析流水线、分支和最近一次构建。只有在仓库外操作，或要指定其他流水线时，才需要显式传入 -p/--pipeline。

安装

# Homebrew (macOS and Linux)
brew install buildkite/buildkite/bk

# Update an existing install (prints the right command for brew/mise installs)
bk update

有关二进制文件下载和验证，请参阅 references/command-reference.md。

身份验证

推荐使用 bk auth login。它使用 OAuth，并将生成的令牌存储在系统钥匙串中 — 无需手动创建令牌。

# OAuth login (opens a browser; grants all scopes your account allows)
bk auth login

# Login to a specific organization
bk auth login --org my-org

# Login with read-only access (scope group), plus write access to builds
bk auth login --scopes "read_only write_builds"

# Headless / remote machine (no browser)
bk auth login --device

# Non-interactive with an existing API token (CI/Docker)
bk auth login --org my-org --token "$BUILDKITE_API_TOKEN"

命令	说明
bk auth login	使用 OAuth 或令牌登录；将凭据存储在钥匙串中
bk auth status	显示当前会话（支持 -o json）
bk auth token	将存储的令牌输出到 stdout（例如用于 curl）
bk auth switch [org]（别名 bk auth use）	切换当前组织
bk auth logout	移除存储的凭据（使用 --all 可移除所有组织的凭据）

在没有可用钥匙串的无头 Linux 主机上，请将令牌存储固定为内存存储：bk config set credential_store shm，然后运行 bk auth login --device。

基于令牌的配置（替代方案）

bk configure 会存储手动创建的 API 令牌，而非使用 OAuth。仅在 OAuth 不可用时使用。

bk configure --org my-org --token "$BUILDKITE_API_TOKEN"
bk configure add --org second-org --token "$OTHER_TOKEN"   # add another org

在 Buildkite > 头像 > 个人设置 > API 访问令牌中创建令牌，并至少授予 read_builds、write_builds、read_pipelines 和 read_artifacts 权限范围。

切换组织

bk use my-other-org      # top-level alias for bk auth switch
bk auth switch           # interactive selection
bk organization list     # list configured orgs

CLI 配置

bk config 用于管理持久设置（默认输出格式、分页器、凭据存储）。用户配置全局生效；--local 会在当前目录中写入 .bk.yaml。

bk config list                          # show effective config
bk config set output_format json        # default all output to JSON
bk config set selected_org my-org --local

构建

创建、查看、列出、取消、重试、重新构建、监视和下载构建。

创建构建

# Build the current branch and commit (pipeline auto-detected from the repo)
bk build create

# Explicit pipeline, branch, and message
bk build create -p my-app -b feature/auth -m "Test auth changes"

# With environment variables and metadata
bk build create -e "DEPLOY_ENV=staging" -M "release=true"

# Open the new build in the browser
bk build create -w

标志	短选项	默认值	说明
--pipeline	-p	自动检测	流水线 slug，或 {org}/{slug}
--branch	-b	流水线默认分支	要构建的 Git 分支
--commit	-c	HEAD	Git 提交 SHA
--message	-m	提交消息	构建消息
--author	-a	—	构建作者（"Name <email>"、电子邮件、姓名或用户名）
--env	-e	—	环境变量 KEY=VALUE（可重复指定）
--env-file	-f	—	从文件加载环境变量
--metadata	-M	—	构建元数据 KEY=VALUE（可重复指定）
--ignore-branch-filters	-i	false	即使分支筛选条件会跳过构建，也照常构建
--web	-w	false	创建构建后在浏览器中打开

查看构建

bk build view（以及大多数构建命令）默认使用当前分支上最近一次的构建。

在状态检查、轮询、脚本和 Agent 工作流中使用 --summary。该选项会排除作业和展开的流水线信息，并跳过制品和注释请求。

bk build view --summary             # latest build metadata and state
bk build view 429 --summary         # a specific build number
bk build view 429 --summary -o json # compact structured output
bk build view --mine --summary      # latest build by the current user

列出构建

bk build list --summary                              # 50 most recent build summaries
bk build list --summary --state failed --branch main # filter by state and branch
bk build list --summary --since 24h --duration ">20m" # slow builds from the last 24 hours
bk build list --summary --meta-data env=production -o json

使用 --summary 仅输出元数据；API 请求会排除作业和展开的流水线信息。服务端筛选（速度快）：--pipeline、--since、--until、--state、--branch、--creator、--commit、--meta-data。客户端筛选：--duration、--message。有效状态：running、scheduled、passed、failed、blocked、canceled、canceling、skipped、not_run。--state 和 --branch 请使用逗号分隔的列表。使用 --limit N（默认值为 50）或 --no-limit 控制分页。完整筛选表请参阅 references/command-reference.md。

监视构建

实时流式查看进度。命令会持续运行，直至构建完成或被取消。

bk build watch                       # watch the most recent build
bk build watch 429 -p my-app         # watch a specific build
bk build watch --interval 5          # custom polling interval (seconds)

取消、重试、重新构建

bk build cancel 429 -p my-app   # only scheduled/running/failing builds
bk build rebuild 429            # rebuild a specific build (or most recent)

下载构建资源

bk build download 会将构建的制品下载到本地文件系统。

bk build download 429 -p my-app
bk build download --mine          # most recent build by the current user

触发并跟踪

bk build create -p my-app -b main && bk build watch -p my-app

作业

检查并操作单个作业。作业通过 UUID 定位 — bk job log 不再需要流水线或构建上下文（-p/-b 标志已弃用并会被忽略）。

查看作业日志

bk job log 0190046e-e199-453b-a302-a21a4d649d31
bk job log <job-uuid> --no-timestamps   # strip timestamp prefixes

列出作业

--step-key 和 --group-key 要求使用 Buildkite CLI v3.54.0 或更高版本。如果任一标志不可用，请运行 bk update。

已知构建编号时，请传入 --build，这样 bk job list 就会使用专用的、通过游标分页的 List Jobs 端点。流水线可以显式指定，也可以根据当前仓库或配置解析。--state、--step-key 和 --group-key 会在服务端应用；--queue 和 --duration 仍在客户端应用。使用 --step-key 可列出某个步骤中的所有作业，包括并行作业；使用 --group-key 可列出某个组中的所有作业。

bk job list --pipeline my-app --build 429 --state failed
bk job list --build 429 --state running # pipeline auto-detected
bk job list --build 429 --step-key test
bk job list --build 429 --group-key verification

未指定 --build 时，命令会搜索近期构建并提取其中嵌入的作业：

bk job list --queue test-queue --state running
bk job list --duration ">10m" --order-by duration --no-limit

--step-key 和 --group-key 必须与 --build 搭配使用，也可以同时使用。--limit 限制输出的作业总数，而不是 API 页大小。使用 --no-limit 可遍历所有游标分页；CLI 会在游标分页中保留所有服务端筛选条件。--since 和 --until 不能与 --build 同时使用。

重试、取消、解除阻塞、调整优先级

bk job retry <job-uuid>           # each job UUID can be retried once
bk job cancel <job-uuid>          # cancel one job; prompts for confirmation
bk job unblock <job-uuid>         # unblock a blocked step
bk job unblock <job-uuid> --data '{"release": "true"}'   # with block-step fields
bk job reprioritize <job-uuid> 10 # raise scheduling priority

bk job cancel 会停止一个作业；bk build cancel 会停止所有尚未完成的作业。不会直接取消其他作业，但除非该步骤设置了 soft_fail，否则被取消的作业会导致构建失败，并可能在其他步骤上触发快速失败（cancel_on_build_failing）。取消之前，请使用 bk api /jobs/<job-uuid>（或 MCP get_job）读取该作业的信息，并向用户显示其名称和状态。只有在用户确认要取消该作业后，才传入全局标志 --yes（bk job --yes cancel <job-uuid>）。运行中的作业会保持 canceling 状态，直至其 Agent 执行完毕。从 v3.62.0 起，该命令使用 REST 作业取消端点；对于运行中的作业，会输出 Job canceling: <url>，否则会输出 Job canceled: <url>；v3.61.1 及更早版本在两种情况下均输出 Job canceled: <url>。无论哪种情况，在报告作业已停止之前都应重新读取作业状态。

调试工作流

bk build list --summary --state failed -p my-app
bk job list --pipeline my-app --build 429 --state failed
bk job log <job-uuid>

流水线

创建、列出、查看、复制、验证和转换流水线配置。

列出和查看

bk pipeline list                 # all pipelines (default 100)
bk pipeline list --name deploy   # filter by name (partial, case-insensitive)
bk pipeline view my-app          # pipeline details
bk pipeline view my-app -w       # open in browser

创建流水线

bk pipeline create "My App" -r "[email protected]:org/my-app.git" --cluster-name "Default"
bk pipeline create "My App" -r "[email protected]:org/my-app.git" --dry-run   # synthetic non-mutating preview

标志	简写	默认值	说明
<name>	—	—	流水线名称（位置参数，必填）
--repository	-r	—	Git 仓库 URL
--description	-d	—	流水线说明
--cluster-uuid	—	—	要分配给流水线的集群 UUID
--cluster-name	—	—	集群名称（解析为 UUID）
--create-webhook	-W	false	创建流水线后创建 GitHub 或 GitHub Enterprise SCM webhook
--dry-run	—	false	输出合成预览，不创建流水线；可能会进行只读 API 调用

请将流水线创建和 --create-webhook 视为非原子操作：流水线创建可能成功，但 SCM webhook 创建可能失败。SCM webhook 用于传递仓库事件，与出站组织通知服务 webhook 不同。

有关流水线 YAML 配置、步骤类型和插件，请参阅 buildkite-pipelines 技能。

复制流水线

bk pipeline copy my-app --target "my-app-v2"             # within the org
bk pipeline copy my-app --target "other-org/my-app"      # across orgs (cluster reset)

验证流水线

bk pipeline validate 会在本地根据流水线架构检查 YAML（不需要 API 令牌）。它不会检查仓库访问权限、源代码管理提供商设置、权限或服务器端流水线创建限制。默认使用 .buildkite/pipeline.yaml 或 .yml。

bk pipeline validate
bk pipeline validate --file .buildkite/deploy.yml

从其他 CI 系统转换

将 GitHub Actions、Bitbucket、CircleCI、Jenkins、GitLab（测试版）、Harness（测试版）或 Bitrise（测试版）配置转换为 Buildkite YAML。无需登录。

bk pipeline convert -F .github/workflows/ci.yml          # vendor auto-detected
bk pipeline convert -F .gitlab-ci.yml --vendor gitlab    # specify when ambiguous
cat .circleci/config.yml | bk pipeline convert --vendor circleci

输出默认写入 .buildkite/pipeline.<vendor>.yml（从标准输入读取时输出到标准输出）。使用 -o/--output 指定自定义路径。

有关从其他 CI 系统深度转换流水线的信息，请参阅 buildkite-migration 技能。

密钥

管理集群范围的密钥。所有密钥命令都需要 --cluster-uuid。

# Create (omit --value to enter it via a masked prompt)
bk secret create --cluster-uuid <uuid> --key MY_SECRET --value "$TOKEN"

# List, view, update, delete
bk secret list --cluster-uuid <uuid>
bk secret get --cluster-uuid <uuid> --secret-id <secret-uuid>
bk secret update --cluster-uuid <uuid> --secret-id <secret-uuid> --update-value
bk secret delete --cluster-uuid <uuid> --secret-id <secret-uuid>

**命名规则：**键只能包含字母、数字和下划线，且不能以 buildkite 或 bk 开头（不区分大小写）。例外：BUILDKITE_API_TOKEN。创建或更新时，请传入 --description 和访问 --policy（YAML）。

有关在流水线 YAML（secrets:）和作业步骤（buildkite-agent secret get）中使用密钥的信息，请参阅 buildkite-pipelines 和 buildkite-agent-runtime 技能。

构件

列出并下载构建构件。命令为 bk artifacts（复数）。构建编号默认为当前分支上的最新构建。

bk artifacts list                              # most recent build
bk artifacts list 429 -j <job-uuid>            # a specific job in a build
bk artifacts download --build 429              # all artifacts for a build
bk artifacts download <artifact-id> --build 429

没有 bk artifacts upload。请在作业步骤中使用 buildkite-agent artifact upload 上传构件（参阅 buildkite-agent-runtime 技能）。有关流水线 YAML 中的 artifact_paths:，请参阅 buildkite-pipelines 技能。

集群和队列

CLI 可直接管理集群、队列和集群维护者：

bk cluster list
bk cluster create --name "Production"
bk queue list <cluster-uuid>
bk queue create <cluster-uuid> --key deploy
bk queue pause <cluster-uuid> <queue-uuid>     # stop dispatching to a queue

bk cluster、bk queue 和 bk maintainer 均支持完整的 CRUD 操作。命令列表请参阅 references/command-reference.md。

本地 Agent

bk agent run 会下载 Agent、创建临时集群令牌，并在本地运行临时的 buildkite-agent，适合在自己的计算机上测试流水线更改。按下 Ctrl+C 后，所有内容都会清理。

bk agent run                      # latest agent on the Default cluster
bk agent run --queue deploy       # listen on a specific queue
bk agent install                  # install the binary + a starter config

bk agent list/view/pause/resume/stop 用于管理组织中已注册的 Agent。

预检、浏览及其他命令

bk browse                 # open the current pipeline (filtered to the branch)
bk browse 429 -n          # print the build URL instead of opening it
bk init                   # scaffold a starter pipeline.yaml
bk package push <registry-slug> --file-path pkg.tar.gz
bk user invite [email protected] [email protected]
bk skill add buildkite-api   # install a Buildkite skill into the current agent

有关使用 bk preflight run 针对本地未提交的更改运行构建的信息，请参阅 buildkite-preflight 技能。

原始 API 访问

使用 bk api 直接调用 REST 或 GraphQL API：

bk api '/pipelines/my-app/builds/429?exclude_jobs=true&exclude_pipeline=true'
bk api -X POST /pipelines --data '{"name":"New","repository":"git@..."}'
bk api --file query.graphql # GraphQL file with a named operation

有关 REST 和 GraphQL 的完整文档（端点、变更、分页、webhook），请参阅 buildkite-api 技能。

MCP 服务替代方案

Buildkite MCP 服务可用时，优先使用 MCP 工具执行读取操作——它们会处理身份验证、分页和解析。MCP 未覆盖的操作则回退到 CLI。

CLI 命令	MCP 工具	说明
bk build create	create_build	MCP 会自动处理身份验证
bk build view --summary / list --summary	get_build / list_builds	仅包含元数据；不包含作业和展开后的流水线信息
bk job list --build	list_jobs	列出作业，不展开构建响应
—	get_job	仅 MCP 支持的单个作业元数据查询
bk job log	read_logs、tail_logs	MCP 支持流式处理
bk pipeline list / view / create	list_pipelines、get_pipeline、create_pipeline
bk artifacts list / download	list_artifacts_for_build、get_artifact
bk cluster list	list_clusters
bk auth status	current_user、access_token
bk build watch / download	—	仅 CLI 支持
bk job cancel	cancel_job	需要服务版本为 v1.27.0 或更高版本，且不能处于只读模式；请传入 org_slug 和 job_id，并同时传入 pipeline_slug 和 build_number，或两者都不传。确认和重新检查规则与 CLI 相同。如果服务未列出此工具，则回退到 bk job cancel
bk job retry / unblock	—	仅 CLI 支持
bk secret *、bk package push、bk agent run	—	仅 CLI 支持
bk api	—	读取操作使用 MCP 工具；自定义调用使用 CLI

常见错误

错误	后果	修正方法
使用完整构建响应进行状态轮询	反复下载作业、流水线详情、制品和注释	使用 bk build view --summary 或 bk build list --summary
已知构建编号却省略 --build	扫描近期构建响应并提取其中嵌入的作业	使用 bk job list --pipeline my-app --build 429，或使用 MCP list_jobs
尚未完成身份验证就运行 bk 命令	命令因身份验证错误而失败	先运行 bk auth login（或使用令牌运行 bk configure）
在 Docker/CI 中运行 bk auth login 并期待出现浏览器	命令挂起——没有可用的浏览器或钥匙串	使用 bk auth login --org my-org --token "$TOKEN"，或在无头环境中使用 --device
将 -p/-b 传给 bk job log	这些标志已弃用且会被忽略——作业 UUID 已包含所需信息	只传入作业 UUID
重试已经重试过的作业 UUID	API 返回 422——每个 UUID 只能重试一次	使用首次重试返回的新作业 UUID
创建键名以 buildkite/bk 开头的密钥	创建失败——这是保留前缀	选择其他名称（BUILDKITE_API_TOKEN 除外）
在 --value 中直接传入密钥值	值会保留在 shell 历史记录和进程列表中	使用环境变量引用（--value "$TOKEN"）或带掩码的提示
运行 bk build cancel 来停止一个卡住的作业	构建中的所有未完成作业都会被取消	对已确认的作业运行 bk job cancel <job-uuid>
对已完成的构建运行 bk build cancel	API 报错——只有已调度、运行中或失败的构建才能取消	先使用 bk build view --summary 检查状态
认为存在 bk artifacts upload	没有此命令	使用 buildkite-agent artifact upload 从作业中上传
混淆 bk 和 buildkite-agent	bk 在本地对 API 执行操作；buildkite-agent 在作业步骤中运行	在终端中使用 bk，在流水线命令中使用 buildkite-agent

其他资源

参考文件

• references/command-reference.md — 安装方法、完整的 bk build list/bk job list 筛选器表、集群/队列/维护者命令、bk agent、bk api、软件包推送和配置详情

延伸阅读

• Buildkite 的大模型文档
• Buildkite CLI 概览
• CLI 命令参考
• CLI 配置与身份验证
• 管理密钥