--- schema_version: 1 route: /t/bk.md tool: "bk" --- # sincecutoff.com /t/bk — Buildkite CLI - name: Buildkite CLI - kind: cli - children: none - homepage: Changes to the tools coding agents drive, since a model's training cutoff, each linked to its first-party source. Check installed versions and limitations before acting; a cutoff date does not establish what a model knows. Original editorial content: [Apache 2.0](https://sincecutoff.com/v1/data-license.txt), by [0xPatrick](https://0xpatrick.dev). Preserve applicable license and [NOTICE](https://sincecutoff.com/notice.txt) attribution when redistributing. Third-party source text and examples retain their own rights. [License scope and attribution](https://sincecutoff.com/v1/license.json). To stay current, read the changes feed: [`/v1/changes.md?tool=bk`](https://sincecutoff.com/v1/changes.md?tool=bk) (or `.json`), adding `since=YYYY-MM-DD` for your training cutoff. Entries for registered children are included; the registry itself is `/v1/tools.json`. How to page and save your place: [llms.txt](https://sincecutoff.com/llms.txt). ### bk pipeline create infers repository defaults and shares local starter setup with bk init (2026-10-14) - slug: bk-pipeline-create-infers-repository-defaults-and-shares-local-starter-setup-wit-035a47a1f3c0 - score: 0.94 How to use it: When creating a pipeline from a Git checkout, run `bk pipeline create` to infer its repository URL and default name from `origin` (or use the checkout directory name); supply a name or `--repository` to override either default. To initialize only a local pipeline file, run `bk init`; use `--template` for noninteractive starter selection, and use `--dry-run` to resolve inputs without creating remote resources or writing files. Examples: ``` bk pipeline create ``` ``` bk pipeline create "My Pipeline" --repository git@github.com:org/repo.git ``` ``` bk pipeline create --no-input --template go ``` - why_it_matters: Create a pipeline from a Git checkout, or initialize its local pipeline file, while preserving existing files and output preferences. - sources: , , - gotchas: "Version: v3.63.0"; "name (positional argument): Explicit pipeline name; overrides the inferred default name."; "--repository : Explicit repository URL; overrides the URL inferred from Git origin."; "--template : Selects a starter explicitly. Documented values: `go`, `node`, `pipenv`, `ruby`, `empty`."; "--no-input: Runs without interactive input; it does not add prompts or local files unless `--template` is supplied."; "--dry-run: Resolves the same name and URL without writing local files or creating a pipeline or webhook; still performs API reads and requires existing authentication configuration."; "--json: The README shows this flag with `--dry-run`; its specific behavior for `pipeline create` is not documented there."; "Prerequisite: Dry-run requires existing authentication configuration and performs API reads."; "Prerequisite: Generated starters need review, commit, and push before building; agents must have the matching runtime and package manager installed."; "Named invocations, redirected input, and `--no-input` do not add prompts or local files unless `--template` is supplied."; "Dry-run still performs API reads and requires the existing authentication configuration."; "Both commands search the checkout root, including from subdirectories and linked worktrees, and leave existing pipeline files unchanged."; "Generated starters need review, commit, and push before building; suitable agents must have matching runtimes."; "Go runs test/vet; Node requires a real test script and adapts installation to npm, pnpm, Yarn, or Bun lockfiles."; "Pipenv/pytest and Bundler/RSpec recommendations require dependency evidence and lockfiles." ### bk commands accept a global --org flag (2026-10-08) - slug: bk-commands-accept-a-global-org-flag-950214133d3c - score: 0.98 How to use it: When a `bk` command must use a different organization for one invocation, add `--org ` to the command or place it before the command. This selects that organization’s stored credentials and overrides environment and saved defaults; qualified targets must agree with it. Examples: ``` bk build list --org ``` ``` bk build view --pipeline --org ``` ``` bk --org job list ``` - why_it_matters: Run a `bk` command against a different Buildkite organization while preserving saved organization and pipeline defaults. - before: Build list and view relied on the selected organization; multi-organization use required changing the selected organization or configuration. - sources: , , - gotchas: "Version: v3.61.1"; "--org : Selects an organization for this invocation, overrides `BUILDKITE_ORGANIZATION_SLUG` and repository/user defaults, and selects that organization's stored credentials. Qualified pipeline or build targets must agree with it."; "--pipeline : Specifies the pipeline; provide it when the effective organization differs from the saved organization and a cached pipeline name would otherwise be used."; "--target org/name: For `pipeline copy`, specifies a destination organization and pipeline independently of `--org`, which selects the source organization."; "Prerequisite: Install the Buildkite CLI and authenticate/configure credentials for the target organization so its stored credentials are available."; "Prerequisite: An explicit `BUILDKITE_API_TOKEN` takes precedence over stored credentials."; "Explicit API environment tokens retain precedence."; "Qualified pipeline or build targets, including URLs, must agree with an explicit `--org`; disagreements error before execution."; "When the effective organization differs from the saved selection, cached pipeline names are ignored; provide `--pipeline` or allow repository discovery to find a pipeline in the target organization."; "Repository pipeline discoveries made with `--org` or `BUILDKITE_ORGANIZATION_SLUG` are not cached."; "For `pipeline copy`, `--org` selects the source organization; `--target org/name` can select a different destination."; "Authentication and configuration commands retain their existing credential or selection changes." ### bk build view --recursive reports failures across triggered builds (2026-10-08) - slug: bk-build-view-recursive-reports-failures-across-triggered-builds-04b29d1ee196 - score: 0.98 How to use it: When diagnosing a build that may have failed in a triggered child, run `bk build view --recursive --json` to retrieve current hard-failed and timed-out command jobs from the build and its reachable descendants. Review `complete` and `issues`; incomplete traversal returns partial results and a nonzero exit status. Examples: ``` bk build view acme/my-pipeline/123 --recursive --json ``` - why_it_matters: When diagnosing a build that may have failed in a triggered child, inspect command failures across the root build and its reachable descendants. - before: Run `bk build view` on each child build separately to find underlying failures. - sources: , , - gotchas: "Version: v3.61.0"; " (required): Build to inspect, in `org/pipeline/number` form."; "--recursive (required): Follow available child references and return current hard-failed (`failed`) and timed-out (`timed_out`) command jobs from the selected build and descendants. Cannot be combined with `--summary`, `--web`, or `--job-states`."; "--json: Output JSON; JSON/YAML output contains `root_build`, `complete`, `failures`, and `issues`. `--json`, `--yaml`, and `--text` are alternative output formats."; "read_builds (required): Token scope required for build access; pipeline read permission is also required."; "read_build_logs: Required to follow log pointers separately."; "Prerequisite: Authenticate the CLI with Buildkite; its README gives `bk auth login`. Build access requires `read_builds` and permission to read each pipeline."; "Prerequisite: Use `read_build_logs` to follow log pointers separately."; "Follows every available child reference, including passed, asynchronous, and soft-failed triggers, without filtering by build state."; "Excludes superseded retry attempts and children of superseded trigger attempts."; "Reports current hard-failed and timed-out command jobs; soft-failed command jobs, canceled or expired jobs, configuration-excluded (`broken`) jobs, jobs stopped by failed dependencies, and running jobs that have promised failure are excluded."; "Uses the existing REST API and fetches each reachable build once; it does not download logs, artifacts, or annotations."; "Requires `read_builds` and permission to read each pipeline. Following log pointers separately requires `read_build_logs`."; "Inaccessible children, invalid child references, missing or not-yet-created child builds (except skipped or configuration-excluded triggers), and request failures produce partial output with `complete: false`, explanatory `issues`, and a nonzero exit status; accessible sibling failures are still returned."; "`complete` describes traversal of observed current attempts, not an atomic snapshot or a guarantee that running builds have finished."; "Builds created by scripts or API calls without a trigger-job link cannot be discovered."; "Docs conflict: Current CLI reference page documents `bk build view` formats but does not list `--recursive`; the v3.61.0 README documents `--recursive`." ### bk job flaky-tests lists flaky tests for a failed job (2026-10-08) - slug: bk-job-flaky-tests-lists-flaky-tests-for-a-failed-job-950f66fa1999 - score: 0.96 How to use it: When inspecting a failed job for retry evidence, run `bk job flaky-tests ` to list failed tests Test Engine currently labels flaky. Treat an empty result as inconclusive; current labels do not establish why the job failed. Examples: ``` bk job flaky-tests --text ``` ``` bk job flaky-tests --json ``` - why_it_matters: When deciding whether to retry a failed job, inspect the failed tests Test Engine currently labels flaky. - sources: , , , - gotchas: "Version: v3.61.0"; " (required): UUID of the failed job to inspect."; "--text: Select text output."; "--json: Select JSON output; structured output includes job UUID, build UUID, test details, and execution metrics."; "--yaml: Select YAML output; structured output includes job UUID, build UUID, test details, and execution metrics."; "Prerequisite: Token requires `read_builds` and `read_suites` scopes."; "Prerequisite: Test Engine executions need the `build.job_id` tag matching the job UUID; missing or overridden collector job metadata may prevent matches."; "Requires `read_builds` and `read_suites` token scopes."; "Test Engine executions must be tagged with the matching `build.job_id`; missing or overridden collector job metadata can prevent matches."; "Current flaky labels do not prove flakiness caused the job failure."; "An empty result does not mean the tests are not flaky; Test Engine data may be missing or incomplete."; "The command fetches all pages."; "Live Test Engine data was not exercised." ### bk api sends custom headers with --headers (2026-10-08) - slug: bk-api-sends-custom-headers-with-headers-d71fd6f766e3 - score: 0.96 How to use it: When an API endpoint requires custom headers, call it with `bk api` and pass each header using `--headers`. Examples: ``` bk api --headers 'X-Header: ' / ``` - why_it_matters: Call a Buildkite API endpoint that requires a custom header. - sources: , - gotchas: "Version: v3.60.1"; "[]: API endpoint to call."; "-H, --headers=HEADERS,...: Headers to include in the request. Docs do not specify the header-value syntax."; "Prerequisite: Use Buildkite CLI (`bk`) configured with valid API authentication for the endpoint. The API command reference does not state a minimum CLI version or specific scopes." ### bk cache registry commands manage cluster cache registries (2026-09-29) - slug: bk-cache-registry-commands-manage-cluster-cache-registries-57bd85fff382 - score: 0.98 How to use it: When you need to manage a cluster cache registry, use `bk cache registry list|view|create|update|delete` with the cluster UUID and, for member commands, the registry UUID. Supply policy with `--policy-file`; use `-` for stdin, and use update clear flags to clear metadata or policy explicitly. Examples: ``` bk cache registry list --limit 200 ``` ``` bk cache registry create --name "" --policy-file ``` ``` bk cache registry update

--clear-description --clear-policy ``` - why_it_matters: Manage cluster cache registries from a coding agent's terminal workflow. - before: Manage cache registries through the REST API or UI. - sources: , , , , - gotchas: "Version: v3.59.0"; " (required): Cluster UUID; the target cluster for list/create, or the registry's cluster for view/update/delete."; " (required): Registry UUID to view, update, or delete."; "--name (required): Registry name on create; new name on update. Renaming regenerates the slug."; "--policy-file: YAML or JSON policy file path, or `-` to read stdin. Policy input must be an object; the CLI normalizes it to JSON."; "--description: Registry description on create or new description on update."; "--emoji: Registry emoji on create or new emoji on update."; "--color: Registry color on create or new color on update."; "--clear-description: Clear the registry description."; "--clear-emoji: Clear the registry emoji."; "--clear-color: Clear the registry color."; "--clear-policy: Clear policy, denying all cache saves and restores."; "--limit: Maximum registries returned by list; default 100."; "--per-page: Registries per page in list; default 30."; "--output: Output format: `json`, `yaml`, or `text`."; "policy.save: Policy section defining cache save scopes."; "policy.restore: Policy section defining cache restore scopes."; "policy.rules: Policy rules controlling actions such as save and restore."; "Prerequisite: Configure `bk` with an API access token for the target organization."; "Prerequisite: Registry operations require permission to manage the cluster. The API documentation specifies `read_clusters` for listing/getting and `write_clusters` for create/update/delete; deletion also requires permission to destroy the registry."; "Policy input accepts YAML or JSON files, or stdin, and must have an object root."; "Deletion is confirmed as a destructive action." ### bk api reads request bodies from stdin with --data - (2026-09-27) - slug: bk-api-reads-request-bodies-from-stdin-with-data-31892c3c59fe - score: 0.95 How to use it: When a large JSON body exceeds command-line limits, use a CLI built with v3.58.0’s change and pipe the file to `bk api --data -`; supplying `--data` defaults the method to POST. [Release note](https://github.com/buildkite/cli/releases/tag/v3.58.0) Examples: ``` cat | bk api --data - ``` - why_it_matters: Send a large JSON request body to a Buildkite API endpoint when it exceeds command-line limits. - before: Before the change, `bk api --data -` sent the literal JSON string `"-"`; released versions still require inline data. - sources: , , , - gotchas: "Version: v3.58.0"; "Requires Install a CLI built from this change; released versions still require inline data."; " (required): API endpoint to call; required for this task. The command reference syntax marks it optional in general."; "--data (required): Data to send in the request body; `-` reads the data from stdin. Supplying `--data` defaults the request method to POST, as stated in the v3.58.0 release note."; "- (required): Value for `--data` that selects stdin as the request body source."; "Prerequisite: Install a CLI built with the v3.58.0 change; the release note says stdin input is available only in such a CLI."; "Prerequisite: The CLI requires configuration of a Buildkite API access token."; "Stdin input is available only after installing a CLI built from this change."; "Inline `--data` behavior remains unchanged." ### bk artifacts accept repeated --path flags (2026-09-27) - slug: bk-artifacts-accept-repeated-path-flags-eff350030bb8 - score: 0.94 How to use it: When uploading multiple selected paths as Buildkite artifacts with `bk`, pass `--path` repeatedly. The official CLI reference does not document an upload command or its invocation. - why_it_matters: Upload multiple selected paths as Buildkite artifacts. - sources: - gotchas: "Version: v3.58.0" ### bk auth login --device accepts --org (2026-09-21) - slug: bk-auth-login-device-accepts-org-a3c8459266aa - score: 0.94 How to use it: When logging in through device authorization and you want to preselect an organization, run `bk auth login --device --org `. The organization is a hint; the user can select another available organization before approving. Examples: ``` bk auth login --device --org ``` - why_it_matters: When logging in to a specific organization through device authorization, pass its slug or UUID as an organization hint. - before: Before this change, `bk auth login --device` rejected `--org`, so multi-organization users had to select the intended organization manually in the browser. - sources: , , , - gotchas: "Version: v3.57.0"; "--device: Authenticate using OAuth device authorization instead of opening a browser callback."; "--org : Organization slug or UUID to request access for; used as a preselection hint."; "organization: Device authorization request hint for an organization; permits preselection if the signed-in user can authorize it."; "organization_uuid: Alternative device authorization request hint using the organization UUID. The docs do not state whether this and `organization` are mutually exclusive or which takes precedence."; "Requires additive device authorization endpoint support; older endpoints safely ignore the hint." ### bk build watch supports --timeout (2026-09-21) - slug: bk-build-watch-supports-timeout-5f6f1bcdf48b - score: 0.98 How to use it: When waiting for a build, run `bk build watch` with `--timeout` to bound build resolution and watching; expiry stops polling and returns a nonzero error without canceling the build. Examples: ``` bk build watch 429 --pipeline my-pipeline --timeout 20m ``` - why_it_matters: When waiting for a build during repository work, bound how long the watch command runs. - before: Watch without a timeout; it could run endlessly. - sources: , , - gotchas: "Version: v3.57.0"; ": Build number to watch; omit to watch the most recent build."; "--pipeline: Pipeline slug or org/pipeline slug; required when no pipeline context supplies it."; "--timeout: Maximum time to resolve and watch the build; accepts durations such as 30s or 20m. Default 0 means no timeout. Expiry does not cancel the build."; "Omitting `--timeout` or setting it to `0` preserves unlimited watching."; "Negative durations are rejected."; "Expiry does not cancel the build." ### bk job retry supports structured output (2026-09-21) - slug: bk-job-retry-supports-structured-output-b3548a9dabeb - score: 0.97 How to use it: When retrying a job to inspect or continue work on the new job, run `bk job retry --json` and use the returned `.id` as the new job UUID for a follow-on command. Use `--text` to print a human-readable confirmation. Examples: ``` retry_uuid=$(bk job retry "" --json | jq -r '.id') bk job log "$retry_uuid" ``` ``` bk job retry "" --text ``` - why_it_matters: When retrying a job to inspect or continue work on the new job, retrieve its UUID from structured output and pass it to a follow-on command. - before: `bk job retry` returned a success message and URL, so callers had to parse the URL or rediscover the new job. - sources: , , , - gotchas: "Version: v3.57.0"; " (required): UUID of the job to retry."; "--json: Output as JSON; the documented example reads the new job UUID from `.id`."; "--yaml: Output as YAML."; "--text: Output as text; documented as a human-readable confirmation."; "-o, --output: Select output format: `json`, `yaml`, or `text`."; "jq -r '.id': Extract the new job UUID from the JSON output in the documented example; requires `jq` in the shell."; "Prerequisite: Install the Buildkite CLI and configure it with an API access token and organization."; "Prerequisite: The CLI requires an API access token; the documentation does not specify a retry-specific scope."; "JSON is the default output format." ### bk secret create accepts file or stdin values (2026-08-26) - slug: bk-secret-create-accepts-file-or-stdin-values-c3daf88e763c - score: 0.98 How to use it: When automation needs a multiline secret value, use `--value-file ` or pipe the value to `bk secret create` with `--value-file -`. For stdin, include `--no-input`; do not combine `--value` and `--value-file`. Examples: ``` bk secret create --cluster-uuid --key --value-file ``` ``` printf 'line one\nline two\n' | bk secret create --no-input --cluster-uuid --key --value-file - ``` - why_it_matters: Create a secret with a multiline value in automation without placing the value inline in shell history. - before: The value was supplied inline or entered interactively. - sources: , , - gotchas: "Version: v3.55.1"; "--cluster-uuid (required): UUID of the cluster."; "--key (required): Secret key name."; "--value-file : Read the secret value from a file; use `-` for stdin. Content is preserved exactly. Mutually exclusive with `--value` per the release note."; "--no-input: Used with `--value-file -` in the documented stdin example; the reference does not list its behavior among the command flags."; "--value : Provide the secret value inline; if neither value source is provided, the command prompts for it. Mutually exclusive with `--value-file` per the release note."; "`--value` and `--value-file` are mutually exclusive."; "File and stdin content is preserved exactly, including trailing LF or CRLF."; "Empty and invalid UTF-8 file or stdin values are rejected."; "Inline and interactive behavior is preserved." ### bk adds job key filter flags (2026-07-19) - slug: bk-adds-job-key-filter-flags-2f481791b845 - score: 0.95 How to use it: When filtering jobs in a known pipeline build, run `bk job list` with `--build` and the relevant key filter flags. Use `--step-key` for a step, `--group-key` for a group, or both. Examples: ``` bk job list --pipeline --build --step-key --group-key ``` - why_it_matters: Filter jobs by job key when inspecting a Buildkite pipeline. - sources: , , , , - gotchas: "Version: v3.54.0"; "--pipeline: Pipeline slug; the command can resolve the pipeline from the current repository or config. Use it to identify the pipeline for the build."; "--build (required): Build number; required when using either key filter."; "--step-key: Filter by step key; requires `--build`."; "--group-key: Filter by group key; requires `--build`. Docs show it can be used together with `--step-key`; they do not state these flags are mutually exclusive."; "Prerequisite: Install the Buildkite CLI (`bk`)."; "Prerequisite: Configure an API access token for the CLI to access Buildkite."; "Prerequisite: Use `--build` with either key filter." ### bk build list and view support --summary metadata-only output (2026-07-15) - slug: bk-build-list-and-view-support-summary-metadata-only-output-d540beb09ade - score: 0.98 How to use it: When checking build state in polling or automation, pass `--summary` to `bk build list` or `bk build view` to request metadata-only output. Examples: ``` bk build list --summary --json ``` ``` bk build view --summary --yaml ``` - why_it_matters: Check build state in a polling loop or automation without requesting unused build payloads. - before: Build state checks downloaded jobs, expanded pipeline details, artifacts, and annotations, even when polling automation did not use them. - sources: , , , , - gotchas: "Version: v3.52.0"; "--summary: Return metadata only for fast state checks and polling; opt-in."; "--json / --yaml: Select JSON or YAML output format."; ": Build number to view; omit to view the most recent build."; "Prerequisite: CLI configured with a Buildkite API access token; the Builds API requires the `read_builds` scope. The docs do not state a minimum CLI version for `--summary`."; "Prerequisite: The `read_builds` scope is required to list builds."; "`--summary` is opt-in."; "Organization and pipeline slugs appear only when known." ### bk browse opens or prints pipeline and build URLs (2026-06-18) - slug: bk-browse-opens-or-prints-pipeline-and-build-urls-023231760d23 - score: 0.98 How to use it: When reviewing the current project’s pipeline or a build, run `bk browse` with the relevant selector and options to open the page or print its URL. Examples: ``` bk browse [] [flags] ``` ``` bk browse 420 -p monolith ``` ``` bk browse 420 -n ``` - why_it_matters: When reviewing a Buildkite pipeline or build for the current project, open its page or print its URL. - sources: , , - gotchas: "Version: v3.49.0"; ": Build number, org/pipeline/number slug, or build URL; omit to open the pipeline page."; "-b, --branch=STRING: Filter the pipeline builds list to this branch; defaults to the current git branch."; "-n, --no-browser: Print the destination URL instead of opening the browser."; "-p, --pipeline=STRING: Select a pipeline by slug or org slug/pipeline slug."; "-s, --settings: Open the pipeline’s settings page."; "--all-branches: Open the pipeline builds list without a branch filter."; "--debug: Enable debug output for REST API calls." ### bk config credential_store setting controls auth credential storage (2026-06-09) - slug: bk-config-credential-store-setting-controls-auth-credential-storage-f2078ed3559e - score: 0.96 How to use it: When configuring where `bk auth login` stores credentials, set the user-level `credential_store` key to `auto`, `keyring`, or `shm`; the CLI documents `shm` for in-memory `/dev/shm` storage. Examples: ``` bk config set credential_store shm ``` ``` bk config get credential_store ``` - why_it_matters: Configure bk's credential store for authentication commands. - before: Use `bk auth login --credential-store ` to select the store on that login invocation. - sources: , , , , - gotchas: "Version: v3.47.0"; " (required): Configuration key to set or get; use `credential_store`."; " (required): Credential store value: `auto`, `keyring`, or `shm`."; "--local: Save to local `.bk.yaml` instead of user config. The v3.47.0 source says `credential_store` is user-config-only, so this flag cannot be used for this key."; "Accepted values are `auto`, `keyring`, and `shm`."; "Precedence is `--credential-store` flag > environment > local config > user config > `auto`."; "Docs conflict: The release note says precedence includes local config. The v3.47.0 `bk config set` source marks `credential_store` as user-config-only and rejects `--local` for it." ### bk update self-updates standalone release binaries (2026-06-09) - slug: bk-update-self-updates-standalone-release-binaries-003899fdea8d - score: 0.95 How to use it: When `bk` is installed as a standalone release binary, run `bk update` to update it to the latest release. If Homebrew or mise manages the installation, run the update command `bk` prints for that tool. Examples: ``` bk update ``` - why_it_matters: Update a standalone release-binary installation of bk to the latest version. - sources: , , - gotchas: "Version: v3.47.0"; "Prerequisite: The command applies to standalone release-binary installations; Homebrew- or mise-managed installations receive tool-specific update instructions."; "The self-update command is for standalone release-binary installs; Homebrew- or mise-managed installations receive instructions to update with that tool." ### bk adds a shared-memory credential store for headless authentication (2026-06-04) - slug: bk-adds-a-shared-memory-credential-store-for-headless-authentication-4338e0f3b4f0 - score: 0.96 How to use it: For headless authentication on Linux, use device authorization and select the shared-memory store with `bk auth login --device --credential-store shm`. Examples: ``` bk auth login --device --credential-store shm ``` ``` bk config set credential_store shm bk auth login --device ``` - why_it_matters: Authenticate `bk` in a headless environment while storing credentials in shared memory. - sources: , , - gotchas: "Version: v3.46.0"; "--device: Use OAuth device authorization instead of opening a browser callback."; "--credential-store: Select the token credential store; documented values are `auto`, `keyring`, and `shm`."; "credential_store: `bk config set credential_store shm` sets the default credential store to shared memory."; "Prerequisite: Install the Buildkite CLI (`bk`)." ### bk auth login adds device authorization (2026-06-04) - slug: bk-auth-login-adds-device-authorization-1977154b26de - score: 0.96 How to use it: When logging in from a headless or remote machine where authorization happens in a separate browser, run `bk auth login --device`. Examples: ``` bk auth login --device ``` - why_it_matters: Log in to Buildkite from a headless or remote development machine where authorization happens in a separate browser. - before: Run `bk auth login` using a browser on the same machine and a reachable localhost callback. - sources: , , - gotchas: "Version: v3.45.0"; "--device (required): Authenticate using OAuth device authorization instead of opening a browser callback."; "The device flow applies to headless or remote machines where authorization can happen in another browser without relying on a loopback browser OAuth callback."; "Existing browser login and `--token` login behavior is preserved." ### bk preflight runs builds against a snapshot of local changes (2026-04-29) - slug: bk-preflight-runs-builds-against-a-snapshot-of-local-changes-4713fcefb349 - score: 0.98 How to use it: When iterating on uncommitted changes, run `bk preflight run` for the selected pipeline to snapshot the working tree and monitor the build until it starts failing. The command cleans up its temporary branch when finished. Examples: ``` bk preflight run --pipeline / --watch ``` - why_it_matters: When iterating on uncommitted repository changes against Buildkite Pipelines, run a preflight build and monitor its failures. - sources: , , , , - gotchas: "Version: v3.39.0"; "Availability: Experimental preview; enabled by default. Subject to change without notice."; "--pipeline, -p (required): Pipeline slug, or `/`; a slug can be used when the Buildkite organization is set in `bk` config."; "--watch / --no-watch: Watch the build until completion; `--no-watch` starts the build and exits immediately."; "--exit-on: Exit condition: `build-failing` (default) exits when the build enters the failing state; `build-terminal` exits when it reaches a terminal state. These values are alternatives."; "Prerequisite: The current Preflight guide requires Buildkite CLI 3.40.0 or later; this differs from the card’s v3.39.0 release."; "Prerequisite: Configure an API access token with `read_builds`, `write_builds`, and `read_pipelines` scopes."; "Prerequisite: Have Git commit and push access to the repository."; "Runs against the selected pipeline."; "Snapshots staged, unstaged, and untracked files."; "The build is monitored and the command exits as soon as the build starts failing."; "The temporary branch is cleaned up when finished."; "Docs conflict: The current guide requires CLI 3.40.0 or later, while the card describes v3.39.0. The current command reference documents `bk preflight run`; the current guide’s examples use `bk preflight` without `run`." ### bk auth token command (2026-03-31) - slug: bk-auth-token-command-ee4bc923e5c4 - score: 0.90 How to use it: When you need the stored API token for the currently selected organization, run `bk auth token`. Examples: ``` bk auth token ``` - why_it_matters: Retrieve an authentication token through the Buildkite CLI. - sources: , - gotchas: "Version: v3.34.0"; "--debug: Enable debug output for REST API calls."; "Prerequisite: A stored token must be available for the current organization. The docs describe `bk auth login` as the way to log in and store credentials." ### bk build view filters jobs by state (2026-03-31) - slug: bk-build-view-filters-jobs-by-state-84e22fd0c762 - score: 0.98 How to use it: When investigating jobs in a build, run `bk build view` with `-s`/`--job-states` and one or more documented states. For example, `bk build view -s failed,broken` filters the displayed jobs to failed and broken states. Examples: ``` bk build view -s failed,broken ``` - why_it_matters: When reviewing a build’s jobs by state, filter the output to the job states relevant to the investigation. - sources: , , , - gotchas: "Version: v3.33.1"; "-s, --job-states=JOB-STATES,...: Filters jobs by state; pass comma-separated values. Valid values: `running`, `scheduled`, `passed`, `failed`, `canceled`, `skipped`, `not_run`, `broken`."; "[]: Build number to view; omit to resolve the most recent build."; "Prerequisite: Install the Buildkite CLI (`bk`)." ### bk agent install installs an agent binary and configures a cluster token (2026-03-31) - slug: bk-agent-install-installs-an-agent-binary-and-configures-a-cluster-token-07a0850eadfe - score: 0.96 How to use it: When installing a Buildkite agent, run `bk agent install` to download the binary and create a token plus minimal config for the Default cluster. Use `--cluster-uuid` to select a cluster, `--no-token` to skip token and config creation, and `--dest` to choose the binary directory. Examples: ``` bk agent install ``` ``` bk agent install --cluster-uuid ``` ``` bk agent install --dest --no-token ``` - why_it_matters: Install a Buildkite agent binary and configure it to join a cluster. - sources: , , - gotchas: "Version: v3.33.0"; "--version : Agent version to install; defaults to `latest`."; "--dest : Destination directory for the binary; the command chooses a default if omitted."; "--cluster-uuid : Cluster UUID to create the agent token on; defaults to the `Default` cluster."; "--no-token: Skip creating an agent token and config file."; "--config-path : Path to write the agent config file; defaults to the platform-specific config path."; "Prerequisite: Token/config creation initializes the API client and creates a token for the selected cluster; the install source does not document required auth scopes or setup."; "The command is phase 1 of a two-phase onboarding process."; "Installing to `/usr/local/bin` requires `sudo`; the default destination is under `$HOME`."; "`--no-token` may be needed for OAuth scopes or when only the binary is wanted." ### bk cluster commands create, update, and delete clusters (2026-03-31) - slug: bk-cluster-commands-create-update-and-delete-clusters-e0924cbe05ee - score: 0.98 How to use it: When creating a cluster, run `bk cluster create` with a name; to change or remove one, run `bk cluster update` or `bk cluster delete` with its UUID. Updates require at least one supported field, and the UUID is a positional argument, not a `--cluster-uuid` flag. Examples: ``` bk cluster create --name "" ``` ``` bk cluster update --name "" ``` ``` bk cluster delete ``` - why_it_matters: Create, update, or delete a Buildkite cluster from the CLI. - before: The release note says the CLI supported read actions only before this change. - sources: , , , , , - gotchas: "Version: v3.33.0"; "create --name STRING (required): Name of the cluster."; "create --description STRING: Description of the cluster."; "create --emoji STRING: Emoji for the cluster."; "create --color STRING: Cluster color as a hex code."; "update (required): UUID of the cluster to update; positional argument."; "update --name STRING: New cluster name; update requires at least one supported update field."; "update --description STRING: New cluster description; update requires at least one supported update field."; "update --emoji STRING: New cluster emoji; update requires at least one supported update field."; "update --color STRING: New cluster color as a hex code; update requires at least one supported update field."; "update --default-queue-id STRING: UUID of the queue to set as the cluster default; update requires at least one supported update field."; "delete (required): UUID of the cluster to delete; positional argument."; "Prerequisite: The CLI must have valid Buildkite configuration; the command validates configuration before running."; "Prerequisite: Authenticate and configure the CLI for a Buildkite organization before use."; "Docs conflict: The card describes `--cluster-uuid` as a persistent flag. In v3.33.0 source, update and delete take the cluster UUID as a positional argument; no `--cluster-uuid` flag is documented there." ### bk stores new tokens in the system keychain by default (2026-03-05) - slug: bk-stores-new-tokens-in-the-system-keychain-by-default-7b4efcb11be0 - score: 0.95 How to use it: When authenticating with `bk`, use its auth commands; new tokens are stored in the system keychain by default. Keep existing `bk.yaml` tokens as read-only fallbacks, or manually add `organizations..api_token` if config-file storage is required. Examples: ``` bk auth login ``` ``` bk auth login --org --token ``` ``` organizations: : api_token: ``` - why_it_matters: Authenticate with `bk` while preserving existing configuration and credentials. - before: `bk` authentication commands set tokens in the config file. - sources: , , , , - gotchas: "Version: v3.32.0"; "--org : Organization slug or UUID to request access for; required when using `--token`."; "--token : API token to store for non-OAuth login; requires `--org`."; "--credential-store : Selects the token credential store. The current docs list `auto`, `keyring`, and `shm`."; "--scopes : OAuth scopes to request; current docs say the default requests available REST API scopes."; "organizations..api_token: Token value in bk.yaml for that organization; it is read as a fallback and is read-only."; "Prerequisite: The change applies from CLI v3.32.0; the release note says new tokens are stored in the system keychain by default."; "Prerequisite: OAuth login requires an organization with an active plan; the docs say to select a plan, including Free, if the organization has none."; "New tokens are stored in the system keychain by default."; "Config-file token storage requires manually adjusting `bk.yaml`."; "Existing config tokens remain a fallback and are read-only."; "Precedence is environment variable > keychain > config."; "Docs conflict: The current auth reference documents `auto`, `keyring`, and `shm` credential-store choices. It does not establish that all these options behaved the same in v3.32.0." ### bk auth login accepts organization and token (2026-03-04) - slug: bk-auth-login-accepts-organization-and-token-6db446c1c6de - score: 0.96 How to use it: When logging in with an API token, run `bk auth login` with the organization slug and token. Credentials are stored in the keychain, and `bk configure` is an alias. Examples: ``` bk auth login --org --token ``` ``` bk configure --org --token ``` - why_it_matters: Log in to Buildkite from a development environment using an organization and token. - before: Run `bk configure` and enter the organization slug and API token when prompted. - sources: , , , - gotchas: "Version: v3.31.0"; "--org (required): Organization slug or UUID to request access for; required with `--token`."; "--token (required): API token to store; selects non-OAuth login and requires `--org`."; "Prerequisite: Create an API access token with access to the target organization. You must be a member of that organization to generate and use its token."; "Prerequisite: The token’s selected scopes determine its API permissions." ### bk pipeline convert accepts piped stdin (2026-02-20) - slug: bk-pipeline-convert-accepts-piped-stdin-1736ed4f4d24 - score: 0.99 How to use it: When converting a GitHub Actions pipeline from standard input, run `bk pipeline convert` with `--vendor github` and omit `--file`. Output goes to stdout by default; use `--output`/`-o` to save it to a file. Examples: ``` cat ci.yml | bk pipeline convert --vendor github ``` ``` cat ci.yml | bk pipeline convert --vendor github -o ``` - why_it_matters: Convert a GitHub pipeline configuration supplied through standard input. - sources: , , - gotchas: "Version: v3.26.0"; "--vendor (required): Specifies the source CI/CD vendor; use `github` for GitHub Actions."; "--file: Path to the pipeline file. Omit when piping configuration from stdin."; "--output / -o: Path to save the converted pipeline; when omitted for stdin input, output is printed to stdout."; "Prerequisite: Install the Buildkite CLI; the docs show `brew install buildkite/buildkite/bk`." ### bk pipeline convert supports GitLab, Bitrise, and Harness (2026-02-18) - slug: bk-pipeline-convert-supports-gitlab-bitrise-and-harness-06536d89e031 - score: 0.97 How to use it: When converting a GitLab CI, Bitrise, or Harness CI file, run `bk pipeline convert` with the file path and specify `--vendor` if it cannot be detected from the filename. These conversions are beta; output defaults to `.buildkite/pipeline..yml`, or use `--output` to choose a path. Examples: ``` bk pipeline convert -F --vendor ``` ``` bk pipeline convert -F --vendor -o ``` - why_it_matters: Convert a GitLab CI, Bitrise, or Harness CI pipeline configuration to Buildkite format. - before: Use the existing supported vendor conversions; GitLab, Bitrise, and Harness are not listed among them. - sources: , , , - gotchas: "Version: v3.25.0"; "Availability: GitLab, Harness, and Bitrise are beta."; "-F, --file (required): Path to the pipeline file to convert."; "-v, --vendor: CI/CD vendor; auto-detected if the file name matches a vendor path and name, otherwise specify it. Supported values include gitlab, bitrise, and harness."; "-o, --output: Custom path to save the converted pipeline; default is `.buildkite/pipeline..yml`."; "Prerequisite: Install the Buildkite CLI. Official docs show `brew install buildkite/buildkite/bk`."; "Prerequisite: No API token is required; conversion uses a public conversion API."; "The command converts supported CI/CD pipeline configurations to Buildkite format."; "Vendor is automatically detected from the filename when not specified."; "By default, output is saved to `.buildkite/pipeline..yml`."; "No API token is required because the command uses a public conversion API."; "Docs conflict: The current CLI reference and converter overview do not list Harness as a supported CLI vendor, while the v3.25.0 release note does. Used the release note for v3.25.0 vendor availability; current docs may describe a later state." ### bk pipeline create can opt in to webhook creation (2026-02-18) - slug: bk-pipeline-create-can-opt-in-to-webhook-creation-b886c546d24c - score: 0.98 How to use it: When creating a Buildkite pipeline for a GitHub or GitHub Enterprise repository, add `--create-webhook` (or `-W`) to opt in to creating its SCM webhook. Examples: ``` bk pipeline create "" --description "" --repository "" --create-webhook ``` - why_it_matters: Create a Buildkite pipeline from the CLI and have it create webhooks for the pipeline's GitHub repository. - sources: , , , - gotchas: "Version: v3.25.0"; " (required): Pipeline name."; "--repository, -r: Repository URL; provide the GitHub repository URL for this task."; "--description, -d: Pipeline description."; "--create-webhook, -W: Create an SCM webhook for the pipeline; documented for GitHub and GitHub Enterprise only. Opt-in flag."; "Prerequisite: Install the Buildkite CLI and authenticate it with an API access token to use Buildkite organizations."; "Prerequisite: The webhook flag supports GitHub and GitHub Enterprise only."; "Webhook creation is opt-in." ### bk auth adds OAuth login and logout (2026-02-11) - slug: bk-auth-adds-oauth-login-and-logout-373a4d85488f - score: 0.92 How to use it: When working in a Buildkite repository, authenticate with `bk auth login --org ` to open the browser OAuth flow and store the token in the system keychain. Use `bk auth logout []` to clear credentials for an organization; the v3.24.0 command also clears its config token. Examples: ``` bk auth login --org ``` ``` bk auth login --org --scopes " " ``` ``` bk auth logout [] ``` - why_it_matters: Authenticate the bk CLI with OAuth when working in a repository that uses Buildkite. - before: The release note says the temporary `auth` alias for `configure` was removed; it does not document the earlier command invocation. - sources: , , , , - gotchas: "Version: v3.24.0"; "login --org (required): Organization slug for OAuth login."; "login --scopes : OAuth scopes to request; examples include `read_user read_organizations read_clusters write_clusters`."; "logout []: Organization slug; defaults to the currently selected organization. If neither is available, the command errors."; "Prerequisite: Install the Buildkite CLI; v3.24.0 is the version covered by the cited command source."; "Prerequisite: OAuth login opens a browser and stores the resulting token in the system keychain when available; it also writes the token to config for fallback/compatibility."; "OAuth support is initial."; "OAuth client ID is injected into built binaries."; "Tokens remain in text-based config; removing them is still to come."; "Docs conflict: Current auth documentation reflects newer CLI behavior: it lists login flags such as `--device` and `--token`, whereas v3.24.0 source requires `--org` and documents `--scopes`. Use the v3.24.0 source for this card." ### bk job adds reprioritize and priority commands (2026-02-11) - slug: bk-job-adds-reprioritize-and-priority-commands-af62e4f7c23a - score: 0.96 How to use it: When the target job is in a running Buildkite build, set its new priority with `bk job reprioritize` and the job UUID and integer priority. The `bk job priority` alias is stated in the v3.24.0 release note; the official CLI reference documents `reprioritize`. Examples: ``` bk job reprioritize ``` - why_it_matters: Change the priority of a job in a running Buildkite build. - sources: , , , , - gotchas: "Version: v3.24.0"; " (required): UUID of the job to reprioritize."; " (required): New priority value for the job. API docs specify an integer; higher values indicate higher priority."; "-p, --pipeline: Pipeline slug or `org/pipeline`; current CLI reference marks this flag deprecated and ignored."; "-b, --build-number: Build number; current CLI reference marks this flag deprecated and ignored."; "Prerequisite: Configure the Buildkite CLI with an API access token."; "Prerequisite: The REST API reprioritize operation requires the `write_builds` scope."; "The job must be in a running build."; "Docs conflict: The v3.24.0 source example shows `-b ` and says `--pipeline` and `--build` are required unless the pipeline is configured for the current Git repository; the current CLI reference says both flags are deprecated and ignored. Follow the v3.24.0 source for that version-specific invocation if needed: https://github.com/buildkite/cli/blob/v3.24.0/cmd/job/reprioritize.go"; "Docs conflict: The v3.24.0 release note names `job priority` as an alias, but the official CLI reference documents only `bk job reprioritize`; alias syntax was not found." ### bk secret adds secret management commands (2026-02-11) - slug: bk-secret-adds-secret-management-commands-28e66abe6055 - score: 0.96 How to use it: When managing Buildkite secrets, use `bk secret` with the cluster ID and the relevant `create`, `update`, `delete`, `list`, or `get` subcommand. For example, create with `--cluster-id`, `--key`, and `--value`; the value can be entered interactively when omitted. Examples: ``` bk secret create --cluster-id --key --value "" ``` ``` bk secret update --cluster-id --secret-id --description "" ``` ``` bk secret list --cluster-id ``` - why_it_matters: Manage secrets while maintaining a Buildkite pipeline. - sources: , , , , - gotchas: "Version: v3.24.0"; "--cluster-id (required): Cluster ID; the v3.24.0 create command requires it."; "--key (required): Secret key name, such as MY_SECRET."; "--value : Secret value. If omitted, the CLI prompts interactively; with `--no-input`, it is required."; "--description : Description of the secret; on update, changes the description."; "--policy : Secret access policy in YAML format."; "--secret-id (required): Secret ID used by get, update, and delete."; "--update-value: Prompt to update the secret value."; "--output, -o : Output format: json, yaml, or text."; "--cluster-uuid : Current online reference uses this cluster selector; it differs from the v3.24.0 source's `--cluster-id`."; "Docs conflict: The current Buildkite CLI reference uses `--cluster-uuid`; v3.24.0 source uses `--cluster-id`. Use `--cluster-id` for the card's stated version." ### bk adds a config command for set/get (2026-01-18) - slug: bk-adds-a-config-command-for-set-get-a14fd32736d3 - score: 0.96 How to use it: When setting or retrieving `bk` configuration, use `bk config set ` or `bk config get `. Configuration keys include `output_format`, `selected_org`, `no_pager`, `quiet`, `no_input`, and `pager`. Examples: ``` bk config get ``` ``` bk config set [--local] ``` - why_it_matters: Set or retrieve configuration using the `bk` CLI. - sources: , - gotchas: "Version: v3.22.0"; " (required): One of `selected_org`, `output_format`, `no_pager`, `quiet`, `no_input`, or `pager`."; " (required): Value for the key. `output_format` accepts `json`, `yaml`, or `text`; `no_pager`, `quiet`, and `no_input` accept `true` or `false`."; "--local: Set the value in local repo configuration. `no_input` and `pager` are user-config-only keys." ### bk adds the job log command (2026-01-15) - slug: bk-adds-the-job-log-command-6cb145be4e5c - score: 0.97 How to use it: When debugging or reviewing a Buildkite CI job, run `bk job log ` to view its logs. Replace `` with the job UUID. Examples: ``` bk job log ``` - why_it_matters: View logs for a Buildkite job while debugging or reviewing a repository’s CI run. - sources: , , , - gotchas: "Version: v3.20.0"; " (required): Job UUID to get logs for."; "Prerequisite: Install and configure the Buildkite CLI with an API access token for the organization."; "Prerequisite: The token needs the `read_build_logs` scope to retrieve job logs." ### bk organizations list adds an org alias and JSON output (2026-01-05) - slug: bk-organizations-list-adds-an-org-alias-and-json-output-281f55760887 - score: 0.92 How to use it: When you need to list organizations configured for Buildkite CLI, run `bk org list`; JSON is the default, and each organization has a `selected` value indicating whether it is active. Examples: ``` bk org list ``` - why_it_matters: List the organizations available to the current Buildkite CLI configuration. - sources: , , , , - gotchas: "Version: v3.17.0"; "org: Alias for the `organization` command group."; "-o, --output: Select `json`, `yaml`, or `text` output format; JSON is the default."; "selected: Boolean indicating whether the organization is selected in the current CLI configuration."; "Prerequisite: Install and configure the Buildkite CLI with an API access token and an organization. The command lists configured organizations."; "Docs conflict: Current CLI reference documents `bk organization list`; the v3.17.0 source confirms `org` as an alias. Current configuration docs describe `bk auth switch` as replacing deprecated `bk use`, while the v3.17.0 release note names `use`." ### bk pipeline copy adds cp and cross-organization copying (2026-01-05) - slug: bk-pipeline-copy-adds-cp-and-cross-organization-copying-9195a81df64e - score: 0.98 How to use it: When copying a pipeline within or across organizations, use `bk pipeline cp`; omit the source to select it interactively or pass its slug or `org/slug`. Set `--target` to the new pipeline name or `org/name`; for a cross-organization copy into an organization using clusters, provide `--cluster` with the target cluster ID. Examples: ``` bk pipeline cp --target ``` ``` bk pipeline cp / --target / --cluster ``` ``` bk pipeline cp --target --dry-run ``` - why_it_matters: Copy a pipeline within an organization or across configured organizations. - sources: , , , - gotchas: "Version: v3.17.0"; ": Source pipeline slug or org/slug; omitted source is resolved from current context or prompted for."; "--target, -t : New pipeline name or org/name. If omitted, prompts for a target."; "--cluster, -c : Target cluster name or ID; required for cross-organization copies if the target organization uses clusters."; "--dry-run: Show what would be copied without creating the pipeline."; "--output, -o : Output format: json, yaml, or text."; "Prerequisite: Configure the CLI with an API access token and organization. Configure an individual token for each organization you need to use."; "Prerequisite: The v3.17.0 command prompts for a target cluster ID on a cross-organization copy if `--cluster` is omitted; the cluster may be required when the target organization uses clusters."; "Cross-organization copying applies when the organizations are configured."; "Docs conflict: Current CLI reference documents `--cluster-name` and `--cluster-uuid`; v3.17.0 source documents `--cluster` instead. Use the versioned v3.17.0 flag for this card: https://buildkite.com/docs/platform/cli/reference/pipeline"