Buildkite CLI for coding agents

When a coding agent can run shell commands in a repository, it can use Buildkite’s command-line tool, bk, to inspect continuous integration (CI) builds on Buildkite. A CI build runs configured checks, such as tests, against a code change. The CLI retrieves build and job details, along with artifacts and annotations, so the agent can report what happened during testing.

An agent can use bk shell commands to inspect CI. The list and view commands described here read Buildkite data without changing it. The CLI requires a Buildkite API token, and its list and view commands support JSON output for scripts and agents.

Install and authenticate

On macOS with Homebrew, Buildkite documents this installation command:

brew install buildkite/buildkite/bk@3

The installation page also covers Linux packages, Windows and manual binary installation.

For this read-only example, sign in through your browser:

bk auth login --scopes read_only

The authentication documentation explains the requested scopes and other login options. Complete the login yourself before starting the agent task. Keep credentials out of the agent prompt and repository.

Inspect a build

A coding agent can check whether a recent build passed and summarize the result for a developer. Start by listing builds:

bk build list --pipeline YOUR_ORG/YOUR_PIPELINE --limit 10 --json

Use a build number from that output to inspect an individual build:

bk build view BUILD_NUMBER --pipeline YOUR_ORG/YOUR_PIPELINE --json

Replace YOUR_ORG/YOUR_PIPELINE with your organization and pipeline slugs. Replace BUILD_NUMBER with a number from the first command’s response. The build command reference documents these flags. The list returns at most ten builds as JSON; view returns details for the selected build. Both commands read from Buildkite over the network.

An explicit pipeline helps when you work across several projects. An agent can read the JSON to identify the build and its state without depending on the layout of a terminal table. These commands do not start a new CI run.

A concise prompt for the example could be:

List up to ten builds as JSON for YOUR_ORG/YOUR_PIPELINE, then inspect the build for the current change with bk build view. Report the build number and state, and summarize any failure details available. Do not trigger or modify a build.

The agent runs the commands in its local shell, and Buildkite returns the build information. The prompt limits the agent to reading that information; it does not ask the agent to change Buildkite.

Know which Buildkite CLI you are using

Buildkite also provides buildkite-agent, a separate command-line tool for interacting with the agent that runs jobs in a pipeline. The bk CLI is for managing and inspecting Buildkite platform resources. An agent working in a developer’s shell should use the documented bk commands to inspect the Buildkite platform. Commands for buildkite-agent serve a different purpose.