buildkite-cli

Buildkite CLI

Buildkite CLI（bk）を使うと、ビルド、ジョブ、パイプライン、シークレット、アーティファクト、クラスター、キュー、パッケージにターミナルからアクセスできます。コマンドラインを離れずに、ビルドの実行、ログの追跡、シークレットの管理、ローカルエージェントの実行、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	保存されたトークンを標準出力に表示します（例：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 は OAuth の代わりに、手動で作成した API トークンを保存します。OAuth を利用できない場合に限り使用してください。

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

Buildkite > アバター > Personal Settings > API Access Tokens で、少なくとも 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	自動検出	パイプラインのスラッグ、または {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（およびほとんどのビルドコマンド）は、現在のブランチで最新のビルドをデフォルトで対象にします。

ステータス確認、ポーリング、スクリプト、エージェントのワークフローには --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 は 1 つのジョブを停止し、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 の状態のままです。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 ウェブフックを作成します
--dry-run	—	false	パイプラインを作成せずに合成プレビューを表示します。読み取り専用の API 呼び出しが行われる場合があります

パイプラインの作成と --create-webhook は、アトミックではない操作として扱ってください。SCM ウェブフックの作成に失敗しても、パイプラインの作成は成功する場合があります。SCM ウェブフックはリポジトリのイベントを配信するものであり、組織の送信通知サービスのウェブフックとは異なります。

パイプラインの 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 を参照してください。

ローカルエージェント

bk agent run はエージェントをダウンロードし、一時的なクラスター・トークンを作成して、一時的な 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 で、組織に登録されたエージェントを管理できます。

事前チェック、参照、その他のコマンド

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 を直接呼び出します。

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 の包括的なドキュメント（エンドポイント、ミューテーション、ページネーション、ウェブフック）については、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 を使用してください
bk job log に -p／-b を渡す	フラグは非推奨で、無視されます。ジョブ UUID に必要な情報が含まれています	ジョブ UUID のみを渡してください
すでに再試行済みのジョブ UUID を再試行する	API が 422 を返します。各 UUID は一度だけ再試行できます	最初の再試行で返された新しいジョブ UUID を使用してください
キーが buildkite／bk で始まるシークレットを作成する	予約済みのプレフィックスのため、作成に失敗します	別の名前を選んでください（例外：BUILDKITE_API_TOKEN）
--value にシークレット値をそのまま渡す	値がシェルの履歴とプロセス一覧に残ります	環境変数の参照（--value "$TOKEN"）またはマスクされたプロンプトを使用してください
停滞したジョブを 1 つ停止するために 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、パッケージのプッシュ、設定の詳細

参考資料

• LLM 向け Buildkite ドキュメント
• Buildkite CLI の概要
• CLI コマンドリファレンス
• CLI の設定と認証
• シークレットの管理