Buildkite CLI
The Buildkite CLI (bk) provides terminal access to builds, jobs, pipelines, secrets, artifacts, clusters, queues, and packages. Use it to trigger builds, tail logs, manage secrets, run a local agent, and automate CI/CD workflows without leaving the command line.
Tip: This skill covers common commands and patterns. For complete flag details on any command, run
bk <command> --help. The CLI ships exhaustive examples in its own help output — prefer it as the source of truth for a specific flag.
Quick Start
bk job list --build requires Buildkite CLI v3.53.0 or later. Run bk update if the flag is unavailable.
Most build, job, artifact, and pipeline commands resolve the pipeline, branch, and most-recent build from the current git repository. Pass -p/--pipeline explicitly only when outside a repo or when targeting a different pipeline.
Installation
For binary downloads and verification, see references/command-reference.md.
Authentication
bk auth login is the recommended method. It uses OAuth and stores the resulting token in the system keychain — no manual token creation required.
On headless Linux hosts where no keychain is available, pin token storage to an in-memory store: bk config set credential_store shm, then bk auth login --device.
Token-based config (alternative)
bk configure stores a manually-created API token instead of using OAuth. Use it only when OAuth is unavailable.
Create the token at Buildkite > avatar > Personal Settings > API Access Tokens with at least read_builds, write_builds, read_pipelines, and read_artifacts scopes.
Switching organizations
CLI configuration
bk config manages persistent settings (default output format, pager, credential store). User config applies globally; --local writes a .bk.yaml in the current directory.
Builds
Create, view, list, cancel, retry, rebuild, watch, and download builds.
Create a build
View a build
bk build view (and most build commands) default to the most recent build on the current branch.
Use --summary for status checks, polling, scripts, and agent workflows. It excludes jobs and expanded pipeline information, and skips artifact and annotation requests.
List builds
Use --summary for metadata-only output; the API requests exclude jobs and expanded pipeline information. Server-side filters (fast): --pipeline, --since, --until, --state, --branch, --creator, --commit, --meta-data. Client-side filters: --duration, --message. Valid states: running, scheduled, passed, failed, blocked, canceled, canceling, skipped, not_run. Pass --state and --branch as comma-separated lists. Use --limit N (default 50) or --no-limit to control paging. See references/command-reference.md for the full filter table.
Watch a build
Stream real-time progress. Blocks until the build completes or is canceled.
Cancel, retry, rebuild
Download build resources
bk build download downloads a build's artifacts to the local filesystem.
Trigger and follow
Jobs
Inspect and act on individual jobs. Jobs are addressed by UUID — bk job log no longer needs pipeline or build context (the -p/-b flags are deprecated and ignored).
View job logs
List jobs
--step-key and --group-key require Buildkite CLI v3.54.0 or later. Run bk update if either flag is unavailable.
When the build number is known, pass --build so bk job list uses the dedicated cursor-paginated List Jobs endpoint. The pipeline can be explicit or resolved from the current repository or configuration. --state, --step-key, and --group-key are applied server-side; --queue and --duration remain client-side. Use --step-key for every job in a step, including parallel jobs, and --group-key for every job in a group.
Without --build, the command searches across recent builds and extracts their embedded jobs:
--step-key and --group-key require --build and can be combined. --limit caps the total jobs emitted, not the API page size. Use --no-limit to follow every cursor page; the CLI preserves all server-side filters across cursor pages. --since and --until cannot be combined with --build.
Retry, cancel, unblock, reprioritize
Debugging workflow
Pipelines
Create, list, view, copy, validate, and convert pipeline configuration.
List and view
Create a pipeline
Treat pipeline creation and --create-webhook as non-atomic operations: pipeline creation can succeed while SCM webhook creation fails. An SCM webhook delivers repository events and is distinct from an outbound organization notification-service webhook.
For pipeline YAML configuration, step types, and plugins, see the buildkite-pipelines skill.
Copy a pipeline
Validate a pipeline
bk pipeline validate checks YAML against the pipeline schema locally (no API token needed). It does not check repository access, source-control provider setup, permissions, or server-side pipeline creation constraints. Defaults to .buildkite/pipeline.yaml or .yml.
Convert from another CI system
Convert GitHub Actions, Bitbucket, CircleCI, Jenkins, GitLab (beta), Harness (beta), or Bitrise (beta) config to Buildkite YAML. No login required.
Output defaults to .buildkite/pipeline.<vendor>.yml (stdout when reading from stdin). Use -o/--output for a custom path.
For converting pipelines from other CI systems in depth, see the buildkite-migration skill.
Secrets
Manage cluster-scoped secrets. All secret commands require --cluster-uuid.
Naming rules: keys may contain only letters, numbers, and underscores, and cannot begin with buildkite or bk (case-insensitive). Exception: BUILDKITE_API_TOKEN. Pass --description and an access --policy (YAML) on create or update.
For using secrets inside pipeline YAML (
secrets:) and job steps (buildkite-agent secret get), see the buildkite-pipelines and buildkite-agent-runtime skills.
Artifacts
List and download build artifacts. The command is bk artifacts (plural). Build number defaults to the most recent build on the current branch.
There is no
bk artifacts upload. Upload artifacts from within a job step withbuildkite-agent artifact upload(see the buildkite-agent-runtime skill). Forartifact_paths:in pipeline YAML, see the buildkite-pipelines skill.
Clusters and Queues
The CLI manages clusters, queues, and cluster maintainers directly:
Full CRUD exists for bk cluster, bk queue, and bk maintainer. See references/command-reference.md for the command list.
Local Agent
bk agent run downloads the agent, creates a temporary cluster token, and runs an ephemeral buildkite-agent locally — useful for testing pipeline changes against your own machine. Everything is cleaned up on Ctrl+C.
bk agent list/view/pause/resume/stop manage registered agents in the org.
Preflight, Browse, and Other Commands
For running a build against local uncommitted changes with
bk preflight run, see the buildkite-preflight skill.
Raw API Access
Make direct REST or GraphQL calls with bk api:
For comprehensive REST and GraphQL documentation (endpoints, mutations, pagination, webhooks), see the buildkite-api skill.
MCP Server Alternatives
When the Buildkite MCP server is available, prefer MCP tools for read operations — they handle auth, pagination, and parsing. Fall back to the CLI for actions MCP does not cover.
Common Mistakes
Additional Resources
Reference Files
references/command-reference.md— Installation methods, fullbk build list/bk job listfilter tables, cluster/queue/maintainer commands,bk agent,bk api, package push, and config details


