Buildkite CLI build command

Commands

Create a build

Create a new build.

The web URL to the build will be printed to stdout.

bk build create [flags]

Flags

Examples

Create a new build:

bk build create

Create a new build with environment variables set:

bk build create -e "FOO=BAR" -e "BAR=BAZ"

Create a new build with metadata:

bk build create -M "key=value" -M "foo=bar"

Cancel a build

Cancel a build.

bk build cancel <build-number> [flags]

Arguments

Flags

Examples

Cancel a build by number:

bk build cancel 123 --pipeline my-pipeline

Cancel a build and open in browser:

bk build cancel 123 --pipeline my-pipeline --web

Compare builds

Compare final job attempts between two builds.

Compare final job attempts, not all retry attempts. Requires read_builds. An explicit --baseline may be newer, failed or on another branch, but must be a different positive build number in the same pipeline. Otherwise search up to 500 candidates for the latest earlier-created build that is currently passed on the target branch. It need not have passed before the target started.

Match unique step keys with type, matrix and parallel index/total. Unkeyed jobs use unique exact names within their group and coordinates (a heuristic, reported as name_fallback). Duplicates and unnamed unkeyed jobs remain unmatched. Changes in soft_failed are state_changed, not newly_failing/recovered.

All comparison rows are returned, failures first. Each inventory is limited to 10 pages (1000 jobs). Missing baselines, incomplete inventories and API failures return an error without partial output. Unfinished builds are snapshots only. Timings cover final attempts; positive execution deltas mean slower, not build wall-clock changes. Still-failing does not establish a shared cause or retry safety. No logs are fetched; use job IDs/URLs to investigate. JSON/YAML never prompts for pipeline selection; use --pipeline when ambiguous.

bk build compare <build-number> [flags]

Arguments

Flags

Examples

bk build compare 123 --pipeline my-pipeline --json

bk build compare acme/my-pipeline/123 --baseline 120 --text

bk build compare https://buildkite.com/acme/my-pipeline/builds/123 --yaml

List build annotations

List a build's annotations, including HTML bodies.

List all build- and job-scoped annotations for an explicit build. All pages are fetched, including HTML bodies (not the original Markdown). Requires the read_builds token scope. JSON/YAML never prompts for pipeline selection; use --pipeline when ambiguous. Empty results have annotations=[]. Errors return a nonzero exit status without partial results on stdout.

bk build annotations <build-number> [flags]

Arguments

Flags

Examples

bk build annotations 123 --pipeline my-pipeline --json

bk build annotations acme/my-pipeline/123 --text

bk build annotations https://buildkite.com/acme/my-pipeline/builds/123 --yaml

bk build annotations acme/my-pipeline/123 --json | jq '.annotations[].body_html'

List failed tests

List tests with failed executions in a build.

List tests with at least one failed execution in this build, including tests that passed on retry, regardless of their current flaky labels or the build state. All result pages are fetched. Requires read_builds and read_suites token scopes. JSON/YAML never prompts for pipeline selection; use --pipeline when ambiguous.

Results include test details, current labels, and build execution metrics, not individual failure messages or backtraces. Labels are not a per-failure verdict. Only uploaded Test Engine data from suites accessible to your token is included; an empty result does not prove that no tests failed. The API's aggregation window is limited by retention and ends at most 24 hours after build creation.

bk build failed-tests <build-number> [flags]

Arguments

Flags

Examples

bk build failed-tests 123 --pipeline my-pipeline --json

bk build failed-tests acme/my-pipeline/123 --text

bk build failed-tests https://buildkite.com/acme/my-pipeline/builds/123

Retry failed jobs

Queue retries for failed jobs in a build (may repeat side effects).

Queue retries for failed jobs in an existing build. Requires write_builds. By default, retries all retryable failed jobs. Use --states to select failure types. This is not limited to infrastructure failures and does not check whether jobs are safe to rerun; retries can repeat side effects, including deployments.

Requires confirmation unless --yes is supplied. --no-input without --yes fails without retrying. JSON/YAML never prompts for pipeline selection; use --pipeline when ambiguous. Confirmation goes to stderr, not structured stdout. Malformed or conflicting explicit build/pipeline selectors are rejected.

The API returns 202 Accepted asynchronously. retried_jobs_count is the number of jobs queued for retry, not completed or successful retries. No waiting is done; use bk build view or bk build watch to follow the build. If the accepted response has no usable count, check the build before resubmitting.

bk build retry-failed-jobs <build-number> [flags]

Arguments

Flags

Examples

bk build retry-failed-jobs 123 --pipeline my-pipeline

bk build retry-failed-jobs acme/my-pipeline/123 --states failed,soft_failed --yes --json

bk build retry-failed-jobs https://buildkite.com/acme/my-pipeline/builds/123 --yes --no-input --text

List dynamic step uploads

List dynamic step uploads for a build.

List a build's dynamic step uploads, newest first, fetching all cursor pages. Requires the read_builds token scope. JSON/YAML never prompts for pipeline selection; use --pipeline when ambiguous.

Includes state, source job, created job count, rejection type and outcome message. An unavailable count is omitted in JSON and shown as "-" in text, not zero. Messages do not include uploaded configuration or internal failure details; check the source job's pipeline upload command output for further diagnostics. Uploaded definitions are not included. History is only available within the build's maximum lifetime (up to 30 days after creation); older builds return 410.

bk build step-uploads <build-number> [flags]

Arguments

Flags

Examples

bk build step-uploads 123 --pipeline my-pipeline --json

bk build step-uploads acme/my-pipeline/123 --text

bk build step-uploads https://buildkite.com/acme/my-pipeline/builds/123 --yaml

View a build

View build information.

You can pass an optional build number to view. If omitted, the most recent build on the current branch will be resolved. Builds from all creators are included by default. Use --mine or --user to filter by creator.

--recursive follows all current trigger attempts, including passed/asynchronous triggers, and returns hard-failed or timed-out script jobs from the root and descendant builds. Superseded retries, soft failures, canceled/expired jobs, and jobs that never ran are excluded. Logs are linked, not downloaded. Missing children or request errors produce partial output with complete=false and a nonzero exit status.

bk build view [<build-number>] [flags]

Arguments

Flags

Examples

By default, the most recent build for the current branch is shown:

bk build view

If not inside a repository or to use a specific pipeline, pass -p:

bk build view -p monolith

To view a specific build:

bk build view 429

Check build state without downloading jobs, artifacts, annotations, or pipeline details:

bk build view 429 --summary

Add -w to any command to open the build in your web browser instead:

bk build view -w 429

To view the most recent build on feature-x branch:

bk build view -b feature-x

You can filter by a user name or id:

bk build view -u "alice"

A shortcut to view your builds is --mine:

bk build view --mine

Filter to only show failed and broken jobs:

bk build view -s failed,broken

Find current command failures throughout a trigger tree in one CLI invocation:

bk build view acme/monolith/429 --recursive --json

To view most recent build by greg on the deploy-pipeline:

bk build view -p deploy-pipeline -u "greg"

List builds

List builds.

List builds with optional filtering.

This command supports both server-side filtering (fast) and client-side filtering. Server-side filters are applied by the Buildkite API, while client-side filters are applied after fetching results and may require loading more builds.

Client-side filters: --duration, --message Server-side filters: --pipeline, --since, --until, --state, --branch, --creator, --commit, --meta-data

Builds can be filtered by their duration, message content, and other attributes. When filtering by duration, you can use operators like >, <, >=, and <= to specify your criteria. Supported duration units are seconds (s), minutes (m), and hours (h).

bk build list [flags]

Flags

Examples

List recent builds (50 by default):

bk build list

Check build states without downloading jobs or pipeline details:

bk build list --summary

Get more builds (automatically paginates):

bk build list --limit 500

List builds from the last hour:

bk build list --since 1h

List failed builds:

bk build list --state failed

List builds on main branch:

bk build list --branch main

List builds by alice:

bk build list --creator alice@company.com

List builds that took longer than 20 minutes:

bk build list --duration ">20m"

List builds that finished in under 5 minutes:

bk build list --duration "<5m"

Combine filters: failed builds on main branch in the last 24 hours:

bk build list --state failed --branch main --since 24h

Find builds containing "deploy" in the message:

bk build list --message deploy

Filter builds by meta-data:

bk build list --meta-data env=production

Filter by multiple meta-data keys:

bk build list --meta-data env=production --meta-data deploy=true

Complex filtering: slow builds (>30m) that failed on feature branches:

bk build list --duration ">30m" --state failed --branch feature/

Download a build

Download resources for a build.

bk build download [<build-number>] [flags]

Arguments

Flags

Examples

Download build 123:

bk build download 123 --pipeline my-pipeline

Download most recent build:

bk build download --pipeline my-pipeline

Download most recent build on a branch:

bk build download -b main --pipeline my-pipeline

Download most recent build by a user:

bk build download --pipeline my-pipeline -u alice@hello.com

Download most recent build by yourself:

bk build download --pipeline my-pipeline --mine

Filter artifacts to download by path or state:

bk build download --pipeline my-pipeline --artifacts-path "log/rspec*.json"

bk build download --pipeline my-pipeline --artifacts-state finished

Rebuild a build

Rebuild a build.

bk build rebuild [<build-number>] [flags]

Arguments

Flags

Examples

Rebuild a specific build by number:

bk build rebuild 123

Rebuild most recent build:

bk build rebuild

Rebuild and open in browser:

bk build rebuild 123 --web

Rebuild most recent build on a branch:

bk build rebuild -b main

Rebuild most recent build by a user:

bk build rebuild -u alice

Rebuild most recent build by yourself:

bk build rebuild --mine

Watch a build

Watch a build's progress in real-time.

bk build watch [<build-number>] [flags]

Arguments

Flags

Examples

Watch the most recent build for the current branch:

bk build watch --pipeline my-pipeline

Watch a specific build:

bk build watch 429 --pipeline my-pipeline

Watch the most recent build on a specific branch:

bk build watch -b feature-x --pipeline my-pipeline

Watch a build on a specific pipeline:

bk build watch --pipeline my-pipeline

Set a custom polling interval (in seconds):

bk build watch --interval 5 --pipeline my-pipeline

Stop watching after 20 minutes without canceling the build:

bk build watch 429 --pipeline my-pipeline --timeout 20m