buildkite-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Buildkite CLI

The Buildkite CLI (

bk

) provides terminal access to builds, jobs, pipelines, secrets, artifacts, clusters, and packages. Use it to trigger builds, tail logs, manage secrets, and automate CI/CD workflows without leaving the command line.

Buildkite CLI（

bk

）提供对构建、任务、流水线、密钥、制品、集群和包的终端访问能力。无需离开命令行，即可用它触发构建、跟踪日志、管理密钥并自动化CI/CD工作流。

Quick Start

快速开始

bash

undefined

bash

undefined

Install

安装

brew tap buildkite/buildkite && brew install buildkite/buildkite/bk

Authenticate

认证

bk configure

Trigger a build on the current branch

在当前分支触发构建

bk build create --pipeline my-app

Watch it run

监控构建运行

bk build watch 42 --pipeline my-app

View logs for a failed job

查看失败任务的日志

bk job log <job-id> --pipeline my-app --build 42

undefined

bk job log <job-id> --pipeline my-app --build 42

undefined

Installation

安装

bash

brew tap buildkite/buildkite && brew install buildkite/buildkite/bk

For binary downloads, shell completion, and verification, see

references/command-reference.md

bash

brew tap buildkite/buildkite && brew install buildkite/buildkite/bk

如需二进制下载、Shell补全和验证，请查看

references/command-reference.md

。

Authentication

认证

Run

bk configure

to set the organization slug and API access token. This creates

$HOME/.config/bk.yaml

on first run.

bash

bk configure

运行

bk configure

设置组织标识和API访问令牌。首次运行时会创建

$HOME/.config/bk.yaml

文件。

bash

bk configure

Non-interactive (CI/Docker): bk configure --org my-org --token "$BUILDKITE_API_TOKEN" --no-input

非交互式（CI/ Docker环境）：bk configure --org my-org --token "$BUILDKITE_API_TOKEN" --no-input


Or use keychain-based auth (v3.31+): `bk auth login`


也可使用基于密钥链的认证（v3.31+版本支持）：`bk auth login`

Token creation

令牌创建步骤

Open Buildkite > user avatar > Personal Settings > API Access Tokens
Select New API Access Token

Grant scopes:

read_builds

write_builds

read_pipelines

read_artifacts

at minimum

Copy the token and pass it to
```
bk configure
```

For the full

bk auth

subcommand reference and organization switching (

bk use

), see

references/command-reference.md

打开Buildkite > 用户头像 > 个人设置 > API访问令牌
选择新建API访问令牌

授予权限范围：至少需要

read_builds

、

write_builds

、

read_pipelines

、

read_artifacts

复制令牌并传入
```
bk configure
```
命令

关于完整的

bk auth

子命令参考以及组织切换（

bk use

），请查看

references/command-reference.md

。

Builds

构建管理

Manage pipeline builds — create, view, list, cancel, retry, and watch.

管理流水线构建——创建、查看、列出、取消、重试和监控。

Create a build

创建构建

bash

undefined

bash

undefined

Build the current branch and commit (pipeline auto-detected from repo)

构建当前分支和提交（流水线从仓库自动检测）

bk build create

Explicit pipeline

指定流水线

bk build create --pipeline my-app

Build with environment variables and metadata

携带环境变量和元数据构建

bk build create -e "FOO=BAR" -e "BAR=BAZ" bk build create --branch feature/auth --commit abc1234 --env "DEPLOY_ENV=staging"


| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--pipeline` | `-p` | auto-detected | Pipeline slug; resolved from repo context when omitted |
| `--branch` | `-b` | current branch | Git branch to build |
| `--commit` | `-c` | HEAD | Git commit SHA |
| `--message` | `-m` | — | Build message |
| `--env` | `-e` | — | Environment variables (repeatable) |
| `--env-file` | `-f` | — | Load environment variables from a file |
| `--metadata` | `-M` | — | Build metadata key=value (repeatable) |

bk build create -e "FOO=BAR" -e "BAR=BAZ" bk build create --branch feature/auth --commit abc1234 --env "DEPLOY_ENV=staging"


| 参数 | 简写 | 默认值 | 说明 |
|------|-------|---------|-------------|
| `--pipeline` | `-p` | 自动检测 | 流水线标识；省略时从仓库上下文解析 |
| `--branch` | `-b` | 当前分支 | 要构建的Git分支 |
| `--commit` | `-c` | HEAD | Git提交SHA值 |
| `--message` | `-m` | — | 构建消息 |
| `--env` | `-e` | — | 环境变量（可重复使用） |
| `--env-file` | `-f` | — | 从文件加载环境变量 |
| `--metadata` | `-M` | — | 构建元数据key=value（可重复使用） |

View a build

查看构建详情

bash

bk build view 42 --pipeline my-app

bash

bk build view 42 --pipeline my-app

List builds

列出构建

bash

undefined

bash

undefined

List recent builds for a pipeline

列出流水线的最近构建

bk build list --pipeline my-app

List only failed builds

仅列出失败的构建

bk build list --pipeline my-app --state failed


| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--pipeline` | `-p` | — | Pipeline slug (omit for org-wide listing) |
| `--state` | `-s` | — | Filter by state: `running`, `scheduled`, `passed`, `failed`, `blocked`, `canceled`, `canceling`, `skipped`, `not_run`, `finished` |
| `--output` | `-o` | `text` | Output format: `text`, `json` |

bk build list --pipeline my-app --state failed


| 参数 | 简写 | 默认值 | 说明 |
|------|-------|---------|-------------|
| `--pipeline` | `-p` | — | 流水线标识（省略则列出组织内所有构建） |
| `--state` | `-s` | — | 按状态过滤：`running`、`scheduled`、`passed`、`failed`、`blocked`、`canceled`、`canceling`、`skipped`、`not_run`、`finished` |
| `--output` | `-o` | `text` | 输出格式：`text`、`json` |

Watch a build

监控构建

Stream real-time build progress to the terminal. Blocks until the build completes or is canceled.

bash

bk build watch 42 --pipeline my-app

将构建实时进度流式传输到终端，会阻塞直到构建完成或被取消。

bash

bk build watch 42 --pipeline my-app

Cancel a build

取消构建

bash

bk build cancel 42 --pipeline my-app

The build must be in a

scheduled

running

, or

failing

state.

bash

bk build cancel 42 --pipeline my-app

构建必须处于

scheduled

、

running

或

failing

状态才能被取消。

Retry a build

重试构建

bash

bk build retry 42 --pipeline my-app

bash

bk build retry 42 --pipeline my-app

Build workflow: trigger and watch

构建工作流：触发并监控

Combine

create

and

watch

for a complete trigger-and-follow workflow:

bash

undefined

结合

create

和

watch

命令完成完整的触发并跟踪工作流：

bash

undefined

Trigger a build and immediately stream progress

触发构建并立即流式传输进度

bk build create --pipeline my-app --branch main && bk build watch --pipeline my-app

undefined

bk build create --pipeline my-app --branch main && bk build watch --pipeline my-app

undefined

Jobs

任务管理

Manage individual jobs within a build — view logs, retry failures, cancel running jobs.

管理构建中的单个任务——查看日志、重试失败任务、取消运行中的任务。

View job logs

查看任务日志

bash

bk job log <job-id> --pipeline my-app --build 42 --follow

Flag	Short	Default	Description
`--pipeline`	`-p`	—	Pipeline slug (required)
`--build`	`-b`	—	Build number (required)
`--follow`	`-f`	`false`	Stream logs in real-time

bash

bk job log <job-id> --pipeline my-app --build 42 --follow

参数	简写	默认值	说明
`--pipeline`	`-p`	—	流水线标识（必填）
`--build`	`-b`	—	构建编号（必填）
`--follow`	`-f`	`false`	实时流式传输日志

Retry a job

重试任务

Each job ID can only be retried once — subsequent retries must use the new job ID returned by the first retry.

bash

bk job retry <job-id> --pipeline my-app --build 42

每个任务ID只能重试一次——后续重试必须使用第一次重试返回的新任务ID。

bash

bk job retry <job-id> --pipeline my-app --build 42

Cancel a job

取消任务

bash

bk job cancel <job-id> --pipeline my-app --build 42

bash

bk job cancel <job-id> --pipeline my-app --build 42

Debugging workflow: find failures and read logs

调试工作流：查找失败并查看日志

bash

undefined

bash

undefined

Find failed builds

查找失败的构建

bk build list --pipeline my-app --state failed

View the build to identify which jobs failed

查看构建详情以确定哪个任务失败

bk build view 42 --pipeline my-app

Read logs for the failed job

查看失败任务的日志

bk job log <job-id> --pipeline my-app --build 42

undefined

bk job log <job-id> --pipeline my-app --build 42

undefined

Pipelines

流水线管理

Manage pipeline configuration — list, create, and update pipelines.

For converting pipelines from other CI systems, see the buildkite-migration skill.

管理流水线配置——列出、创建和更新流水线。

如需从其他CI系统转换流水线，请查看buildkite-migration技能。

Convert a pipeline from another CI system

从其他CI系统转换流水线

Convert a GitHub Actions, Jenkins, CircleCI, Bitbucket, GitLab, Harness, or Bitrise pipeline to Buildkite YAML. No login required — uses a public API.

bash

undefined

将GitHub Actions、Jenkins、CircleCI、Bitbucket、GitLab、Harness或Bitrise流水线转换为Buildkite YAML格式。无需登录——使用公开API。

bash

undefined

Auto-detect vendor from file path and save to .buildkite/pipeline.<vendor>.yml

从文件路径自动检测供应商并保存到.buildkite/pipeline.<vendor>.yml

bk pipeline convert -F .github/workflows/ci.yml bk pipeline convert -F .circleci/config.yml bk pipeline convert -F Jenkinsfile

Specify vendor explicitly (required for gitlab, harness, bitrise)

显式指定供应商（gitlab、harness、bitrise需要）

bk pipeline convert -F .gitlab-ci.yml --vendor gitlab

Custom output path

自定义输出路径

bk pipeline convert -F .github/workflows/ci.yml --output .buildkite/pipeline.yml

Read from stdin

从标准输入读取

cat .github/workflows/ci.yml | bk pipeline convert --vendor github


| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--file` | `-F` | — | Path to source pipeline file (required unless using stdin) |
| `--vendor` | `-v` | auto-detected | Source CI vendor: `github`, `bitbucket`, `circleci`, `jenkins`, `gitlab`, `harness`, `bitrise` |
| `--output` | `-o` | `.buildkite/pipeline.<vendor>.yml` | Output file path |
| `--timeout` | — | `300` | Cancellation timeout in seconds |

cat .github/workflows/ci.yml | bk pipeline convert --vendor github


| 参数 | 简写 | 默认值 | 说明 |
|------|-------|---------|-------------|
| `--file` | `-F` | — | 源流水线文件路径（使用标准输入时可省略） |
| `--vendor` | `-v` | 自动检测 | 源CI供应商：`github`、`bitbucket`、`circleci`、`jenkins`、`gitlab`、`harness`、`bitrise` |
| `--output` | `-o` | `.buildkite/pipeline.<vendor>.yml` | 输出文件路径 |
| `--timeout` | — | `300` | 取消超时时间（秒） |

List pipelines

列出流水线

bash

bk pipeline list

bash

bk pipeline list

Create a pipeline

创建流水线

bash

bk pipeline create --name "My App" --repository "git@github.com:org/my-app.git"

Flag	Short	Default	Description
`--name`	`-n`	—	Pipeline name (required)
`--repository`	`-r`	—	Git repository URL (required)
`--cluster`		—	Cluster UUID to assign the pipeline to
`--description`	`-d`	—	Pipeline description

For pipeline YAML configuration after creation, see the buildkite-pipelines skill.

bash

bk pipeline create --name "My App" --repository "git@github.com:org/my-app.git"

参数	简写	默认值	说明
`--name`	`-n`	—	流水线名称（必填）
`--repository`	`-r`	—	Git仓库URL（必填）
`--cluster`		—	要分配流水线的集群UUID
`--description`	`-d`	—	流水线描述

创建后的流水线YAML配置，请查看buildkite-pipelines技能。

Update a pipeline

更新流水线

bash

bk pipeline update my-app --description "Production application pipeline"

bash

bk pipeline update my-app --description "Production application pipeline"

Secrets

密钥管理

Manage cluster-scoped secrets for pipelines. Secrets are encrypted and accessible to all agents within a cluster.

For using secrets inside pipeline YAML (
secrets:
key) and inside job steps (
buildkite-agent secret get
), see the buildkite-pipelines skill and buildkite-agent-runtime skill respectively.

管理流水线的集群级密钥。密钥会被加密，且对集群内所有Agent可见。

如需在流水线YAML（
secrets:
字段）和任务步骤（
buildkite-agent secret get
）中使用密钥，请分别查看buildkite-pipelines技能和buildkite-agent-runtime技能。

Create a secret

创建密钥

bash

bk secret create MY_SECRET --cluster my-cluster --value "$TOKEN"

Flag	Short	Default	Description
`--cluster`		—	Cluster UUID or slug (required)
`--value`		—	Secret value (omit for interactive prompt)
`--description`	`-d`	—	Human-readable description

Naming rules:

Keys must contain only letters, numbers, and underscores
Keys cannot begin with
```
buildkite
```
or
```
bk
```
(case-insensitive)
Exception:
```
BUILDKITE_API_TOKEN
```
is allowed

bash

bk secret create MY_SECRET --cluster my-cluster --value "$TOKEN"

参数	简写	默认值	说明
`--cluster`		—	集群UUID或标识（必填）
`--value`		—	密钥值（省略则进入交互式输入）
`--description`	`-d`	—	易读的描述信息

命名规则：

密钥只能包含字母、数字和下划线
密钥不能以
```
buildkite
```
或
```
bk
```
开头（不区分大小写）
例外：
```
BUILDKITE_API_TOKEN
```
是允许的

List secrets

列出密钥

bash

bk secret list --cluster my-cluster

bash

bk secret list --cluster my-cluster

Update a secret

更新密钥

bash

bk secret update MY_SECRET --cluster my-cluster --value "$NEW_TOKEN"

bash

bk secret update MY_SECRET --cluster my-cluster --value "$NEW_TOKEN"

Delete a secret

删除密钥

bash

bk secret delete MY_SECRET --cluster my-cluster

bash

bk secret delete MY_SECRET --cluster my-cluster

Artifacts

制品管理

Upload and download build artifacts from the terminal.

从终端上传和下载构建制品。

Download artifacts

下载制品

bash

bk artifact download "dist/*.tar.gz" --pipeline my-app --build 42

bash

bk artifact download "dist/*.tar.gz" --pipeline my-app --build 42

Upload artifacts

上传制品

bash

bk artifact upload "dist/**/*" --pipeline my-app --build 42 --job <job-id>

For uploading artifacts from within a running job step, use
buildkite-agent artifact upload
— see the buildkite-agent-runtime skill. For declaring artifact paths in pipeline YAML (
artifact_paths:
), see the buildkite-pipelines skill.

bash

bk artifact upload "dist/**/*" --pipeline my-app --build 42 --job <job-id>

如需在运行中的任务步骤内上传制品，请使用
buildkite-agent artifact upload
——查看buildkite-agent-runtime技能。如需在流水线YAML中声明制品路径（
artifact_paths:
），请查看buildkite-pipelines技能。

Clusters

集群管理

List and view clusters with

bk cluster list

and

bk cluster view <slug>

. For flags and examples, see

references/command-reference.md

For cluster creation, queue management, and infrastructure provisioning, see the buildkite-agent-infrastructure skill.

使用

bk cluster list

和

bk cluster view <slug>

列出和查看集群。参数和示例请查看

references/command-reference.md

。

如需集群创建、队列管理和基础设施配置，请查看buildkite-agent-infrastructure技能。

Packages

包管理

List registries with

bk package list

and push packages with

bk package push <file> --registry <slug>

. For flags and supported formats, see

references/command-reference.md

For OIDC-based authentication to package registries (no static credentials), see the buildkite-secure-delivery skill.

使用

bk package list

列出注册表，使用

bk package push <file> --registry <slug>

推送包。参数和支持格式请查看

references/command-reference.md

。

如需基于OIDC的包注册表认证（无需静态凭证），请查看buildkite-secure-delivery技能。

Raw API Access

原生API访问

Make direct REST or GraphQL API calls with

bk api <path>

(REST) or

bk api --graphql --data '<query>'

(GraphQL). For flags and examples, see

references/command-reference.md

For comprehensive REST and GraphQL API documentation (endpoints, mutations, pagination, webhooks), see the buildkite-api skill.

使用

bk api <path>

（REST）或

bk api --graphql --data '<query>'

（GraphQL）直接调用REST或GraphQL API。参数和示例请查看

references/command-reference.md

。

如需完整的REST和GraphQL API文档（端点、变更、分页、Webhook），请查看buildkite-api技能。

Users

用户管理

Invite users with

bk user invite user@example.com

. See

references/command-reference.md

for details.

使用

bk user invite user@example.com

邀请用户。详情请查看

references/command-reference.md

。

Pipeline Initialization

流水线初始化

Scaffold a starter

pipeline.yaml

with

bk init

. For pipeline YAML syntax and step types, see the buildkite-pipelines skill. See

references/command-reference.md

for details.

使用

bk init

生成初始的

pipeline.yaml

文件。流水线YAML语法和步骤类型请查看buildkite-pipelines技能。详情请查看

references/command-reference.md

。

MCP Server Alternatives

MCP Server替代方案

When the Buildkite MCP server is available, agents can use MCP tools for direct access without shell execution. The table below maps CLI commands to their MCP equivalents:

CLI Command	MCP Tool	Notes
`bk build create`	`create_build`	MCP handles auth automatically
`bk build view`	`get_build`	MCP returns structured data
`bk build list`	`list_builds`	MCP supports the same filters
`bk job log`	`read_logs` , `tail_logs`	MCP supports streaming
`bk pipeline list`	`list_pipelines`
`bk pipeline create`	`create_pipeline`
`bk pipeline update`	`update_pipeline`
`bk artifact download`	`list_artifacts_for_build` , `get_artifact`
`bk cluster list`	`list_clusters`
`bk auth status`	`current_user` , `access_token`
`bk secret create/list/delete`	—	No MCP equivalent; CLI required
`bk package push`	—	No MCP equivalent; CLI required
`bk job retry`	—	No MCP equivalent; CLI required
`bk job cancel`	—	No MCP equivalent; CLI required
`bk build watch`	—	No MCP equivalent; CLI required
`bk api`	—	Use MCP tools for read operations; CLI for custom API calls

When to use CLI vs MCP: Use MCP tools when available — they handle authentication, pagination, and response parsing automatically. Fall back to the CLI when MCP does not cover the operation (secrets, packages, job retry, build watch) or when the agent needs to execute commands in a Bash workflow.

当Buildkite MCP服务器可用时，Agent可使用MCP工具直接访问，无需执行Shell命令。下表映射了CLI命令对应的MCP工具：

CLI命令	MCP工具	说明
`bk build create`	`create_build`	MCP自动处理认证
`bk build view`	`get_build`	MCP返回结构化数据
`bk build list`	`list_builds`	MCP支持相同的过滤器
`bk job log`	`read_logs` , `tail_logs`	MCP支持流式传输
`bk pipeline list`	`list_pipelines`
`bk pipeline create`	`create_pipeline`
`bk pipeline update`	`update_pipeline`
`bk artifact download`	`list_artifacts_for_build` , `get_artifact`
`bk cluster list`	`list_clusters`
`bk auth status`	`current_user` , `access_token`
`bk secret create/list/delete`	—	无MCP等效工具；需使用CLI
`bk package push`	—	无MCP等效工具；需使用CLI
`bk job retry`	—	无MCP等效工具；需使用CLI
`bk job cancel`	—	无MCP等效工具；需使用CLI
`bk build watch`	—	无MCP等效工具；需使用CLI
`bk api`	—	读取操作使用MCP工具；自定义API调用使用CLI

何时使用CLI vs MCP： 优先使用MCP工具（如果可用）——它们会自动处理认证、分页和响应解析。当MCP不支持该操作（密钥、包、任务重试、构建监控），或Agent需要在Bash工作流中执行命令时，再回退使用CLI。

Common Mistakes

常见错误

Mistake	What happens	Fix
Running `bk` commands before `bk configure`	Every command fails with authentication errors	Run `bk configure` or `bk auth login` first
Running `bk configure` in Docker/CI without `--no-input`	Hangs or fails trying to read from TTY or system keychain	Add `--no-input` flag: `bk configure --org my-org --token "$TOKEN" --no-input`
Omitting `--pipeline` on build commands	Command fails or targets the wrong pipeline	Always pass `--pipeline <slug>` explicitly
Retrying a job ID that was already retried	API returns 422 error — each job ID can only be retried once	Use the new job ID returned by the first retry
Creating secrets with keys starting with `buildkite` or `bk`	Creation fails — reserved prefix	Choose a different key name (exception: `BUILDKITE_API_TOKEN` )
Passing secret values as literal strings in `--value`	Values persist in shell history and process list	Use env var references ( `--value "$TOKEN"` ) or interactive prompts
Using `bk build cancel` on a completed build	API returns error — only `scheduled` , `running` , or `failing` builds can be canceled	Check build state with `bk build view` first
Expecting `bk artifact download` to work cross-cluster	Artifacts are cluster-scoped by default	Ensure both pipelines are in the same cluster or configure cross-cluster artifact access
Confusing `bk` CLI with `buildkite-agent`	`bk` runs on local machines to interact with the Buildkite API; `buildkite-agent` runs inside CI job steps	Use `bk` from terminal, `buildkite-agent` inside pipeline step commands

错误操作	后果	修复方法
在执行 `bk configure` 前运行 `bk` 命令	所有命令因认证错误失败	先运行 `bk configure` 或 `bk auth login`
在Docker/CI环境中运行 `bk configure` 时未添加 `--no-input`	因尝试读取TTY或系统密钥链而挂起或失败	添加 `--no-input` 参数： `bk configure --org my-org --token "$TOKEN" --no-input`
构建命令中省略 `--pipeline`	命令失败或指向错误的流水线	始终显式传递 `--pipeline <slug>`
重试已被重试过的任务ID	API返回422错误——每个任务ID只能重试一次	使用第一次重试返回的新任务ID
创建以 `buildkite` 或 `bk` 开头的密钥	创建失败——该前缀为保留前缀	选择其他密钥名称（例外： `BUILDKITE_API_TOKEN` ）
在 `--value` 中以字面字符串传递密钥值	值会保留在Shell历史和进程列表中	使用环境变量引用（ `--value "$TOKEN"` ）或交互式输入
对已完成的构建执行 `bk build cancel`	API返回错误——只有 `scheduled` 、 `running` 或 `failing` 状态的构建可被取消	先使用 `bk build view` 检查构建状态
期望 `bk artifact download` 跨集群工作	制品默认是集群级别的	确保两个流水线在同一个集群，或配置跨集群制品访问
混淆 `bk` CLI和 `buildkite-agent`	`bk` 在本地机器运行，用于与Buildkite API交互； `buildkite-agent` 在CI任务步骤内运行	在终端使用 `bk` ，在流水线步骤命令内使用 `buildkite-agent`

Additional Resources

额外资源

Reference Files

参考文件

references/command-reference.md
— Full installation methods, auth subcommands, organization switching, and detailed flags/examples for clusters, packages, API access, users, and pipeline initialization

references/command-reference.md
— 完整的安装方法、认证子命令、组织切换，以及集群、包、API访问、用户和流水线初始化的详细参数/示例