

# Buildkite CLI job command

The `bk job` command allows you to manage jobs within builds from the command line.

## Commands

| Command | Description |
| --- | --- |
| `bk job cancel` | Cancel a job. |
| `bk job flaky-tests` | List failed tests currently labeled flaky by Test Engine for a failed job. |
| `bk job list` | List jobs. |
| `bk job log` | Get logs for a job. |
| `bk job reprioritize` | Reprioritize a job. |
| `bk job retry` | Retry a job. |
| `bk job ssh` | Connect to a running hosted job over SSH. |
| `bk job unblock` | Unblock a job. |
| `bk job vnc` | Connect to a running hosted macOS job over VNC. |

## Cancel a job

Cancel a job.

Other jobs in the build keep running; to cancel the whole build, use bk build
cancel. A running job is canceling until its agent stops it. If the agent stops
responding, Buildkite finishes the cancellation without it.

```bash
bk job cancel <job-id> [flags]
```

### Arguments

| Argument | Description |
| --- | --- |
| `<job-id>` | Job UUID to cancel |

### Flags

| Flag | Description |
| --- | --- |
| `-w`, `--web` | Open the job in a web browser after it has been cancelled |
| `--debug` | Log HTTP API traffic to stderr; bodies may contain sensitive data |
| `--org=STRING` | Organization slug for this invocation (overrides environment and configuration) |

### Examples

Cancel a job (with confirmation prompt):

```bash
bk job cancel 0190046e-e199-453b-a302-a21a4d649d31
```

Cancel a job without confirmation (useful for automation):

```bash
bk job --yes cancel 0190046e-e199-453b-a302-a21a4d649d31
```

Cancel a job and open it in browser:

```bash
bk job --yes cancel 0190046e-e199-453b-a302-a21a4d649d31 --web
```

## List flaky test failures

List failed tests currently labeled flaky by Test Engine for a failed job.

List tests with failed executions for this job that Test Engine currently labels
flaky. All result pages are fetched. Requires `read_builds` and `read_suites`
token scopes. Executions must have the build.`job_id` tag matching the job UUID.
Collectors normally derive this from `BUILDKITE_JOB_ID`; overridden or missing job
metadata may prevent matches.

These are current test labels, not a verdict that flakiness caused the job to
fail. No matches does not mean not flaky: Test Engine data may be missing or
incomplete.

```bash
bk job flaky-tests <job-id> [flags]
```

### Arguments

| Argument | Description |
| --- | --- |
| `<job-id>` | Failed job UUID to inspect |

### Flags

| Flag | Description |
| --- | --- |
| `-o`, `--output=""` | Output format. One of: json, yaml, text |
| `--debug` | Log HTTP API traffic to stderr; bodies may contain sensitive data |
| `--json` | Output as JSON |
| `--org=STRING` | Organization slug for this invocation (overrides environment and configuration) |
| `--text` | Output as text |
| `--yaml` | Output as YAML |

### Examples

```bash
bk job flaky-tests 0190046e-e199-453b-a302-a21a4d649d31 --text
```

```bash
bk job flaky-tests 0190046e-e199-453b-a302-a21a4d649d31 --json
```

## List jobs

List jobs.

This command supports both server-side filtering (fast) and client-side
filtering. When a build number is known, use --build to fetch its jobs directly.
The pipeline can be passed with --pipeline or resolved from the current
repository or config.

Server-side filters: --pipeline, --build, --step-key, --group-key, --since,
--until, --queue, --state

Client-side filters: --duration, and --state without --queue or --build

Without --build, the command fetches up to 200 builds for filtering by default.
Use --no-limit to search further.

Jobs can be filtered by queue, state, duration, 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).

```bash
bk job list [flags]
```

### Flags

| Flag | Description |
| --- | --- |
| `-o`, `--output=""` | Output format. One of: json, yaml, text |
| `-p`, `--pipeline=STRING` | Pipeline slug (uses the selected organization), org/pipeline, or Buildkite pipeline URL. |
| `--build=STRING` | Filter by build number (requires a resolvable pipeline) |
| `--debug` | Log HTTP API traffic to stderr; bodies may contain sensitive data |
| `--duration=STRING` | Filter by duration (e.g. >10m, <5m, 20m) - supports >, <, >=, <= operators |
| `--group-key=STRING` | Filter by group key (requires --build) |
| `--json` | Output as JSON |
| `--limit=100` | Maximum number of jobs to return |
| `--no-limit` | Fetch all jobs (overrides --limit) |
| `--order-by=STRING` | Order results by field (`start_time`, duration) |
| `--org=STRING` | Organization slug for this invocation (overrides environment and configuration) |
| `--queue=STRING` | Filter by queue name |
| `--since=STRING` | Filter jobs from builds created since this time (e.g. 1h, 30m) |
| `--state=STATE,...` | Filter by job state |
| `--step-key=STRING` | Filter by step key (requires --build) |
| `--text` | Output as text |
| `--until=STRING` | Filter jobs from builds created before this time (e.g. 1h, 30m) |
| `--yaml` | Output as YAML |

### Examples

List recent jobs (100 by default):

```bash
bk job list
```

List jobs from a specific queue:

```bash
bk job list --queue test-queue
```

List running jobs in a queue (both filters applied by the server):

```bash
bk job list --queue test-queue --state running
```

List running jobs:

```bash
bk job list --state running
```

List failed jobs from a known build (recommended when the build is known):

```bash
bk job list --pipeline my-app --build 429 --state failed
```

List jobs for step and group keys from a known build:

```bash
bk job list --pipeline my-app --build 429 --step-key test --group-key verification
```

List jobs that took longer than 10 minutes:

```bash
bk job list --duration ">10m"
```

List jobs from the last hour:

```bash
bk job list --since 1h
```

Combine filters:

```bash
bk job list --queue test-queue --state running --duration ">10m"
```

Fetch all jobs matching filters (no limit):

```bash
bk job list --duration ">10m" --no-limit
```

Order by duration (longest first):

```bash
bk job list --order-by duration
```

Get JSON output for bulk operations:

```bash
bk job list --queue test-queue -o json
```

## Log job

Get logs for a job.

```bash
bk job log <job-id> [flags]
```

### Arguments

| Argument | Description |
| --- | --- |
| `<job-id>` | Job UUID to get logs for |

### Flags

| Flag | Description |
| --- | --- |
| `-b`, `--build-number=STRING` | Deprecated; ignored because job UUIDs no longer require pipeline or build context |
| `-p`, `--pipeline=STRING` | Deprecated; ignored because job UUIDs no longer require pipeline or build context |
| `--agent` | Format output to be optimal for LLM consumption (strips ANSI, deduplicates loops) |
| `--debug` | Log HTTP API traffic to stderr; bodies may contain sensitive data |
| `--format="plain"` | Output rendering for --agent: plain or Markdown |
| `--max-tokens=INT` | Hard ceiling on the estimated token count of --agent output (0 = unlimited) |
| `--no-timestamps` | Strip timestamp prefixes from log output |
| `--no-window` | Disable failure-focused windowing in --agent output (keep all lines) |
| `--org=STRING` | Organization slug for this invocation (overrides environment and configuration) |

### Examples

Get a job's logs by UUID:

```bash
bk job log 0190046e-e199-453b-a302-a21a4d649d31
```

Strip timestamp prefixes from output:

```bash
bk job log 0190046e-e199-453b-a302-a21a4d649d31 --no-timestamps
```

Format for LLM consumption:

```bash
bk job log 0190046e-e199-453b-a302-a21a4d649d31 --agent
```

Format for LLM as Markdown, capped at 2000 tokens, keeping all lines:

```bash
bk job log 0190046e-e199-453b-a302-a21a4d649d31 --agent --format markdown --max-tokens 2000 --no-window
```

## Reprioritize job

Reprioritize a job.

```bash
bk job reprioritize <job-id> <priority> [flags]
```

### Arguments

| Argument | Description |
| --- | --- |
| `<job-id>` | Job UUID to reprioritize |
| `<priority>` | New priority value for the job |

### Flags

| Flag | Description |
| --- | --- |
| `-b`, `--build-number=STRING` | Deprecated; ignored because job UUIDs no longer require pipeline or build context |
| `-p`, `--pipeline=STRING` | Deprecated; ignored because job UUIDs no longer require pipeline or build context |
| `--debug` | Log HTTP API traffic to stderr; bodies may contain sensitive data |
| `--org=STRING` | Organization slug for this invocation (overrides environment and configuration) |

### Examples

Reprioritize a job by UUID:

```bash
bk job reprioritize 0190046e-e199-453b-a302-a21a4d649d31 1
```

## Retry a job

Retry a job.

Use this command to retry build jobs. Structured output contains the new job
returned by the API; use its id to follow the retry.

```bash
bk job retry <job-id> [flags]
```

### Arguments

| Argument | Description |
| --- | --- |
| `<job-id>` | Job UUID to retry |

### Flags

| Flag | Description |
| --- | --- |
| `-o`, `--output=""` | Output format. One of: json, yaml, text |
| `--debug` | Log HTTP API traffic to stderr; bodies may contain sensitive data |
| `--json` | Output as JSON |
| `--org=STRING` | Organization slug for this invocation (overrides environment and configuration) |
| `--text` | Output as text |
| `--yaml` | Output as YAML |

### Examples

Retry a job by UUID:

```bash
bk job retry 0190046e-e199-453b-a302-a21a4d649d31
```

Get the new job UUID:

```bash
bk job retry 0190046e-e199-453b-a302-a21a4d649d31 --json | jq -r '.id'
```

Print a human-readable confirmation:

```bash
bk job retry 0190046e-e199-453b-a302-a21a4d649d31 --text
```

## Connect to a job using SSH

Connect to a running hosted job over SSH.

```bash
bk job ssh <job-uuid>
```

### Arguments

| Argument | Description |
| --- | --- |
| `<job-uuid>` | UUID of the hosted agent job |

### Flags

| Flag | Description |
| --- | --- |
| `--debug` | Log HTTP API traffic to stderr; bodies may contain sensitive data |
| `--org=STRING` | Organization slug for this invocation (overrides environment and configuration) |

### Examples

Open an interactive shell on a running hosted job:

```bash
bk job ssh 0190046e-e199-453b-a302-a21a4d649d31
```

## Unblock a job

Unblock a job.

Use this command to unblock build jobs.

```bash
bk job unblock <job-id> [flags]
```

### Arguments

| Argument | Description |
| --- | --- |
| `<job-id>` | Job UUID to unblock |

### Flags

| Flag | Description |
| --- | --- |
| `--data=STRING` | JSON formatted data to unblock the job |
| `--debug` | Log HTTP API traffic to stderr; bodies may contain sensitive data |
| `--org=STRING` | Organization slug for this invocation (overrides environment and configuration) |

### Examples

Unblock a job by UUID:

```bash
bk job unblock 0190046e-e199-453b-a302-a21a4d649d31
```

Unblock with JSON data:

```bash
bk job unblock 0190046e-e199-453b-a302-a21a4d649d31 --data '{"field": "value"}'
```

Unblock with data from stdin:

```bash
echo '{"field": "value"}' | bk job unblock 0190046e-e199-453b-a302-a21a4d649d31
```

## Connect to a job using VNC

Connect to a running hosted macOS job over VNC.

```bash
bk job vnc <job-uuid>
```

### Arguments

| Argument | Description |
| --- | --- |
| `<job-uuid>` | UUID of the hosted agent job |

### Flags

| Flag | Description |
| --- | --- |
| `--debug` | Log HTTP API traffic to stderr; bodies may contain sensitive data |
| `--org=STRING` | Organization slug for this invocation (overrides environment and configuration) |

### Examples

Connect a local VNC client to a running hosted macOS job:

```bash
bk job vnc 0190046e-e199-453b-a302-a21a4d649d31
```
