buildkite-cli

name: buildkite-cli description: > This skill should be used when the user asks to "trigger a build", "check build status", "watch a build", "view build logs", "retry a build", "cancel a build", "list builds", "download artifacts", "upload artifacts", "manage secrets", "create a pipeline", "list pipelines", or "interact with Buildkite from the command line". Also use when the user mentions bk commands, bk build, bk job, bk pipeline, bk secret, bk artifact, bk cluster, bk package, bk auth, bk configure, bk use, bk init, bk api, or asks about Buildkite CLI installation, terminal-based Buildkite workflows, or command-line CI/CD operations.

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.

Quick Start

# 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

Installation

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

For binary downloads, shell completion, and verification, see 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.

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

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

Token creation

1. Open Buildkite > user avatar > Personal Settings > API Access Tokens
2. Select New API Access Token
3. Grant scopes: read_builds, write_builds, read_pipelines, read_artifacts at minimum
4. 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.

Builds

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

Create a build

# 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"

View a build

bk build view 42 --pipeline my-app

List builds

# List recent builds for a pipeline
bk build list --pipeline my-app

# List only failed builds
bk build list --pipeline my-app --state failed

Watch a build

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

bk build watch 42 --pipeline my-app

Cancel a build

bk build cancel 42 --pipeline my-app

The build must be in a scheduled, running, or failing state.

Retry a build

bk build retry 42 --pipeline my-app

Build workflow: trigger and watch

Combine create and watch for a complete trigger-and-follow workflow:

# Trigger a build and immediately stream progress
bk build create --pipeline my-app --branch main && bk build watch --pipeline my-app

Jobs

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

View job logs

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

Retry a job

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

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

Cancel a job

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

Debugging workflow: find failures and read logs

# 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

Pipelines

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

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

Convert a pipeline from another CI system

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

# Auto-detect vendor from file path and save to .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)
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

List pipelines

bk pipeline list

Create a pipeline

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

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

Update a pipeline

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.

Create a secret

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

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

List secrets

bk secret list --cluster my-cluster

Update a secret

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

Delete a secret

bk secret delete MY_SECRET --cluster my-cluster

Artifacts

Upload and download build artifacts from the terminal.

Download artifacts

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

Upload artifacts

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.

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.

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.

Raw API Access

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.

Users

Invite users with bk user invite user@example.com. See references/command-reference.md for details.

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.

MCP Server Alternatives

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:

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.

Common Mistakes

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

Further Reading

• Buildkite Docs for LLMs
• Buildkite CLI overview
• CLI command reference
• CLI installation
• CLI configuration and authentication
• Managing secrets