> ## 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.

# Logs and usage

> Search CI logs and report usage from the terminal

## `blacksmith logs`

Organization-wide log search and analysis over all your CI logs, using the Blacksmith query language:

```
error                     substring match in message
"connection refused"      exact phrase match
level:error               filter by log level (error, warn, info, debug)
repo:my-org/my-repo       filter by repository
workflow:ci.yml           filter by workflow file
branch:main               filter by branch
job_name:test             filter by job name
step_name:"Run tests"     filter by step name
pr:42                     filter by pull request number
-error                    exclude lines matching 'error'
error AND timeout         both must match
(error OR warn) AND db    grouping with parentheses
```

### `blacksmith logs search`

Full-text log search returning matching lines with metadata (repo, workflow, job, step, branch). Cursor-paginated.

```bash theme={"system"}
blacksmith logs search --query 'level:error repo:my-org/my-repo "connection refused"' --since 24h
```

### `blacksmith logs histogram`

Time-bucketed log counts broken down by level. Useful as a first pass to identify windows with elevated error rates before drilling in with `search`.

```bash theme={"system"}
blacksmith logs histogram --query 'level:error' --since 7d
```

Both support `--since` (`1h`, `6h`, `24h`, `7d`, `14d`, `30d`) or absolute `--start-time`/`--end-time` RFC3339 ranges.

## `blacksmith usage`

Billing-oriented Actions usage for the authenticated organization: jobs, billable minutes, billing minutes, runtime minutes, estimated cost, daily totals, and requested breakdowns.

```bash theme={"system"}
blacksmith usage --since 30d --breakdown-by runner_type,repo --format table
```

| Flag                                                   | Description                                                                    |
| :----------------------------------------------------- | :----------------------------------------------------------------------------- |
| `--since`                                              | Relative time range: `24h`, `7d`, `30d`, `90d`. Defaults to `30d`.             |
| `--start-time`, `--end-time`                           | Absolute RFC3339 time range.                                                   |
| `--breakdown-by`                                       | CSV subset of `day`, `runner_type`, `repo`, `workflow`, `job`, `workflow_job`. |
| `--repo`, `--workflow`, `--job-name`, `--runner-label` | Filters.                                                                       |

### `blacksmith usage storage`

Sticky disk storage usage for a time range: current/peak/average GB, GB-hours, and estimated cost from the hourly storage billing ledger.

```bash theme={"system"}
blacksmith usage storage --since 30d --breakdown-by repo,type
```

## `blacksmith runners catalog`

Lists every Blacksmith runner SKU as a deterministic table of metadata: label, vCPUs, memory, architecture, OS, and cost per minute. This is a global endpoint — the same catalog for every caller — intended for humans and tooling to reason about SKU ladders.

```bash theme={"system"}
blacksmith runners catalog --format table
```