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

> Search and analyze CI logs across your organization 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.