Buildkite CLI build command

The bk build command allows you to manage pipeline builds from the command line.

Commands

Command Description
bk build create Create a new build.
bk build cancel Cancel a build.
bk build view View build information.
bk build list List builds.
bk build download Download resources for a build.
bk build rebuild Rebuild a build.
bk build watch Watch a build's progress in real-time.

Create a build

Create a new build.

bk build create [flags]

Flags

Flag Description
-a, --author=STRING Author of the build. Supports: "Name ", "email@domain.com", "Full Name", or "username"
-b, --branch=STRING The branch to build. Defaults to the default branch of the pipeline.
-c, --commit="HEAD" The commit to build.
-e, --env=ENV,... Set environment variables for the build (KEY=VALUE)
-f, --env-file=STRING Set the environment variables for the build via an environment file
-i, --ignore-branch-filters Ignore branch filters for the pipeline
-m, --message=STRING Description of the build. If left blank, the commit message will be used once the build starts.
-M, --metadata=METADATA,... Set metadata for the build (KEY=VALUE)
-p, --pipeline=STRING The pipeline to use. This can be a {pipeline slug} or in the format {org slug}/{pipeline slug}.
-w, --web Open the build in a web browser after it has been created.
--debug Enable debug output for REST API calls

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

Argument Description
<build-number> Build number to cancel

Flags

Flag Description
-p, --pipeline=STRING The pipeline to use. This can be a {pipeline slug} or in the format {org slug}/{pipeline slug}.
-w, --web Open the build in a web browser after it has been cancelled.
--debug Enable debug output for REST API calls

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

View a build

View build information.

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

Arguments

Argument Description
[<build-number>] Build number to view (omit for most recent build)

Flags

Flag Description
-b, --branch=STRING Filter builds to this branch.
-o, --output="json" Output format. One of: json, yaml, text
-p, --pipeline=STRING The pipeline to use. This can be a {pipeline slug} or in the format {org slug}/{pipeline slug}.
-u, --user=STRING Filter builds to this user. You can use name or email.
-w, --web Open the build in a web browser.
--debug Enable debug output for REST API calls
--mine Filter builds to only my user.

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

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-y

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

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

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

List builds

List builds.

bk build list [flags]

Flags

Flag Description
-o, --output="json" Output format. One of: json, yaml, text
-p, --pipeline=STRING The pipeline to use. This can be a {pipeline slug} or in the format {org slug}/{pipeline slug}.
--branch=BRANCH,... Filter by branch name
--commit=STRING Filter by commit SHA
--creator=STRING Filter by creator (email address or user ID)
--debug Enable debug output for REST API calls
--duration=STRING Filter by duration (e.g. >5m, <10m, 20m) - supports >, <, >=, <= operators
--limit=50 Maximum number of builds to return
--message=STRING Filter by message content --meta-data=KEY=VALUE;... Filter by build meta-data (key=value format, can be specified multiple times)
--no-limit Fetch all builds (overrides --limit)
--since=STRING Filter builds created since this time (e.g. 1h, 30m)
--state=STATE,... Filter by build state
--until=STRING Filter builds created before this time (e.g. 1h, 30m)

Examples

List recent builds (50 by default):

bk build list

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

Argument Description
[<build-number>] Build number to download (omit for most recent build)

Flags

Flag Description
-b, --branch=STRING Filter builds to this branch.
-m, --mine Filter builds to only my user.
-p, --pipeline=STRING The pipeline to use. This can be a {pipeline slug} or in the format {org slug}/{pipeline slug}.
-u, --user=STRING Filter builds to this user. You can use name or email.
--debug Enable debug output for REST API calls

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

Rebuild a build

Rebuild a build.

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

Arguments

Argument Description
[<build-number>] Build number to rebuild (omit for most recent build)

Flags

Flag Description
-b, --branch=STRING Filter builds to this branch.
-m, --mine Filter builds to only my user.
-p, --pipeline=STRING The pipeline to use. This can be a {pipeline slug} or in the format {org slug}/{pipeline slug}.
-u, --user=STRING Filter builds to this user. You can use name or email.
-w, --web Open the build in a web browser after it has been created.
--debug Enable debug output for REST API calls

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

Argument Description
[<build-number>] Build number to watch (omit for most recent build)

Flags

Flag Description
-b, --branch=STRING The branch to watch builds for.
-p, --pipeline=STRING The pipeline to use. This can be a {pipeline slug} or in the format {org slug}/{pipeline slug}.
--debug Enable debug output for REST API calls
--interval=1 Polling interval in seconds

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