buildkite-cli

What this skill does

# Buildkite CLI

The Buildkite CLI (`bk`) provides terminal access to builds, jobs, pipelines, secrets, artifacts, clusters, and packages. Use it to trigger builds, tail logs, manage secrets, and automate CI/CD workflows without leaving the command line.

## Quick Start

```bash
# Install
brew tap buildkite/buildkite && brew install buildkite/buildkite/bk

# Authenticate
bk configure

# Trigger a build on the current branch
bk build create --pipeline my-app

# Watch it run
bk build watch 42 --pipeline my-app

# View logs for a failed job
bk job log <job-id> --pipeline my-app --build 42
```

## Installation

```bash
brew tap buildkite/buildkite && brew install buildkite/buildkite/bk
```

For binary downloads, shell completion, and verification, see `references/command-reference.md`.

## Authentication

Run `bk configure` to set the organization slug and API access token. This creates `$HOME/.config/bk.yaml` on first run.

```bash
bk configure
# Non-interactive (CI/Docker): bk configure --org my-org --token "$BUILDKITE_API_TOKEN" --no-input
```

Or use keychain-based auth (v3.31+): `bk auth login`

### Token creation

1. Open Buildkite > user avatar > **Personal Settings** > **API Access Tokens**
2. Select **New API Access Token**
3. Grant scopes: `read_builds`, `write_builds`, `read_pipelines`, `read_artifacts` at minimum
4. Copy the token and pass it to `bk configure`

For the full `bk auth` subcommand reference and organization switching (`bk use`), see `references/command-reference.md`.

## Builds

Manage pipeline builds — create, view, list, cancel, retry, and watch.

### Create a build

```bash
# Build the current branch and commit (pipeline auto-detected from repo)
bk build create

# Explicit pipeline
bk build create --pipeline my-app

# Build with environment variables and metadata
bk build create -e "FOO=BAR" -e "BAR=BAZ"
bk build create --branch feature/auth --commit abc1234 --env "DEPLOY_ENV=staging"
```

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--pipeline` | `-p` | auto-detected | Pipeline slug; resolved from repo context when omitted |
| `--branch` | `-b` | current branch | Git branch to build |
| `--commit` | `-c` | HEAD | Git commit SHA |
| `--message` | `-m` | — | Build message |
| `--env` | `-e` | — | Environment variables (repeatable) |
| `--env-file` | `-f` | — | Load environment variables from a file |
| `--metadata` | `-M` | — | Build metadata key=value (repeatable) |

### View a build

```bash
bk build view 42 --pipeline my-app
```

### List builds

```bash
# List recent builds for a pipeline
bk build list --pipeline my-app

# List only failed builds
bk build list --pipeline my-app --state failed
```

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--pipeline` | `-p` | — | Pipeline slug (omit for org-wide listing) |
| `--state` | `-s` | — | Filter by state: `running`, `scheduled`, `passed`, `failed`, `blocked`, `canceled`, `canceling`, `skipped`, `not_run`, `finished` |
| `--output` | `-o` | `text` | Output format: `text`, `json` |

### Watch a build

Stream real-time build progress to the terminal. Blocks until the build completes or is canceled.

```bash
bk build watch 42 --pipeline my-app
```

### Cancel a build

```bash
bk build cancel 42 --pipeline my-app
```

The build must be in a `scheduled`, `running`, or `failing` state.

### Retry a build

```bash
bk build retry 42 --pipeline my-app
```

### Build workflow: trigger and watch

Combine `create` and `watch` for a complete trigger-and-follow workflow:

```bash
# Trigger a build and immediately stream progress
bk build create --pipeline my-app --branch main && bk build watch --pipeline my-app
```

## Jobs

Manage individual jobs within a build — view logs, retry failures, cancel running jobs.

### View job logs

```bash
bk job log <job-id> --pipeline my-app --build 42 --follow
```

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--pipeline` | `-p` | — | Pipeline slug (required) |
| `--build` | `-b` | — | Build number (required) |
| `--follow` | `-f` | `false` | Stream logs in real-time |

### Retry a job

Each job ID can only be retried once — subsequent retries must use the new job ID returned by the first retry.

```bash
bk job retry <job-id> --pipeline my-app --build 42
```

### Cancel a job

```bash
bk job cancel <job-id> --pipeline my-app --build 42
```

### Debugging workflow: find failures and read logs

```bash
# Find failed builds
bk build list --pipeline my-app --state failed

# View the build to identify which jobs failed
bk build view 42 --pipeline my-app

# Read logs for the failed job
bk job log <job-id> --pipeline my-app --build 42
```

## Pipelines

Manage pipeline configuration — list, create, and update pipelines.

> For converting pipelines from other CI systems, see the **buildkite-migration** skill.

### Convert a pipeline from another CI system

Convert a GitHub Actions, Jenkins, CircleCI, Bitbucket, GitLab, Harness, or Bitrise pipeline to Buildkite YAML. No login required — uses a public API.

```bash
# Auto-detect vendor from file path and save to .buildkite/pipeline.<vendor>.yml
bk pipeline convert -F .github/workflows/ci.yml
bk pipeline convert -F .circleci/config.yml
bk pipeline convert -F Jenkinsfile

# Specify vendor explicitly (required for gitlab, harness, bitrise)
bk pipeline convert -F .gitlab-ci.yml --vendor gitlab

# Custom output path
bk pipeline convert -F .github/workflows/ci.yml --output .buildkite/pipeline.yml

# Read from stdin
cat .github/workflows/ci.yml | bk pipeline convert --vendor github
```

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--file` | `-F` | — | Path to source pipeline file (required unless using stdin) |
| `--vendor` | `-v` | auto-detected | Source CI vendor: `github`, `bitbucket`, `circleci`, `jenkins`, `gitlab`, `harness`, `bitrise` |
| `--output` | `-o` | `.buildkite/pipeline.<vendor>.yml` | Output file path |
| `--timeout` | — | `300` | Cancellation timeout in seconds |

### List pipelines

```bash
bk pipeline list
```

### Create a pipeline

```bash
bk pipeline create --name "My App" --repository "[email protected]:org/my-app.git"
```

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--name` | `-n` | — | Pipeline name (required) |
| `--repository` | `-r` | — | Git repository URL (required) |
| `--cluster` | | — | Cluster UUID to assign the pipeline to |
| `--description` | `-d` | — | Pipeline description |

> For pipeline YAML configuration after creation, see the **buildkite-pipelines** skill.

### Update a pipeline

```bash
bk pipeline update my-app --description "Production application pipeline"
```

## Secrets

Manage cluster-scoped secrets for pipelines. Secrets are encrypted and accessible to all agents within a cluster.

> For using secrets inside pipeline YAML (`secrets:` key) and inside job steps (`buildkite-agent secret get`), see the **buildkite-pipelines** skill and **buildkite-agent-runtime** skill respectively.

### Create a secret

```bash
bk secret create MY_SECRET --cluster my-cluster --value "$TOKEN"
```

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--cluster` | | — | Cluster UUID or slug (required) |
| `--value` | | — | Secret value (omit for interactive prompt) |
| `--description` | `-d` | — | Human-readable description |

**Naming rules:**
- Keys must contain only letters, numbers, and underscores
- Keys cannot begin with `buildkite` or `bk` (case-insensitive)
- Exception: `BUILDKITE_API_TOKEN` is allowed

### List secrets

```bash
bk secret list --cluster my-cluster
```

### Update a secret

```bash
bk secret update MY_SECRET --cluster my-cluster --value "$NEW_TOKEN"
```

### Delete a secret

```bash
bk secret delete MY_SECRET --cluster my-cluster
```

## Artifacts

Upload and download build artifacts from the terminal.

### Download artifacts

```bash
bk arti