> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blacksmith.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Jobs

> Inspect job runs and aggregate CPU/memory metrics

The `blacksmith jobs` commands expose the same job observability data as the dashboard: recent runs, logs, workflow steps, structured test timings, per-run CPU/memory/OOM metrics, and cross-run aggregates.

## `blacksmith jobs list`

Browse recent job runs for your organization. Returns one row per completed job with labels, runner SKU, duration, billable minutes, conclusion, and the GitHub job URL.

```bash theme={"system"}
blacksmith jobs list --repo my-org/my-repo --conclusion failure --since 7d --format table
```

| Flag                  | Description                                                   |
| :-------------------- | :------------------------------------------------------------ |
| `--repo`              | Filter by repository (owner/name or bare name).               |
| `--workflow`          | Filter by workflow name.                                      |
| `--job-name`          | Filter by job name (exact match).                             |
| `--runner-label`      | Filter by runner SKU (e.g. `blacksmith-8vcpu-ubuntu-2204`).   |
| `--conclusion`        | `success`, `failure`, `cancelled`, `skipped`, or `timed_out`. |
| `--since`             | Lookback window: `24h`, `7d`, `14d`, `30d`.                   |
| `--limit`, `--cursor` | Pagination.                                                   |

The numeric GitHub job ID in the output is the handle for the per-job commands below.

## Per-job inspection

| Command                                    | Description                                                                                                         |
| :----------------------------------------- | :------------------------------------------------------------------------------------------------------------------ |
| `blacksmith jobs logs <job_id>`            | Fetch a job's logs. Filter with `--step`, `--search`, or fetch container logs with `--source-type`/`--source-name`. |
| `blacksmith jobs steps <job_id>`           | List workflow steps with line counts and timestamps.                                                                |
| `blacksmith jobs tests <job_id>`           | Structured test timings (JUnit or auto-parsed), slowest first.                                                      |
| `blacksmith jobs containers <job_id>`      | Docker service containers that ran alongside the job.                                                               |
| `blacksmith jobs stats <job_id>`           | Full per-run metrics: CPU utilization timeseries with p50/p90/p95/p99, memory timeseries, and OOM events.           |
| `blacksmith jobs thread-profiles <job_id>` | Per-thread scheduling snapshots (D-state debugging).                                                                |

```bash theme={"system"}
blacksmith jobs logs 12345678 --step "Run tests" --search "FAILED"
```

## Cross-run analysis

### `blacksmith jobs aggregate`

Cross-run CPU/memory percentiles grouped by `(repo, workflow, job_name, runner_label)`: run counts, CPU average and busy-fraction percentiles, peak-memory percentiles, OOM totals, duration percentiles, and billable minutes.

```bash theme={"system"}
blacksmith jobs aggregate --repo my-org/my-repo --group-by workflow,job_name --since 14d
```

### `blacksmith jobs sample`

Returns one representative run per percentile (min / p25 / p50 / p75 / p90 / max by default) along a chosen axis — `duration`, `cpu_avg`, `cpu_busy_frac_80`, `mem_peak_pct`, `billable_minutes`, or `oom_events` — each with a clickable `job_url`.

```bash theme={"system"}
blacksmith jobs sample --workflow ci.yml --axis duration
```

### `blacksmith jobs diagnose rightsize`

Right-sizing recommendations: scale-up / scale-down runner SKU candidates with confidence scores and estimated savings.