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

# forensics

> DevHelm CLI forensics commands — inspect incident timelines, check traces, rule evaluations, state transitions, and policy snapshots

Inspect the event-sourced audit trail the detection engine writes for every check. See [Incident Forensics](/incidents/forensics) for the conceptual overview.

<Tip>
  Every forensic row carries a `checkId` (the same one minted by the scheduler and stamped on check results) and a `policySnapshotHashHex` (a content-addressed SHA-256 of the policy that was active). Those two identifiers thread a single detection decision through the whole system.
</Tip>

## Commands

| Command                                             | Description                                      |
| --------------------------------------------------- | ------------------------------------------------ |
| `devhelm forensics timeline <incident-id>`          | Full timeline for an incident                    |
| `devhelm forensics trace <check-id>`                | Everything recorded for a single check execution |
| `devhelm forensics snapshot <hash-hex>`             | Fetch a policy snapshot by SHA-256 hash          |
| `devhelm forensics evaluations --monitor-id <uuid>` | List rule evaluations for a monitor (paginated)  |
| `devhelm forensics transitions --monitor-id <uuid>` | List state transitions for a monitor (paginated) |

### forensics timeline

```bash theme={null}
devhelm forensics timeline <incident-id>
```

Renders the incident's state transitions, the rule evaluations that caused each triggering transition, and the active policy snapshot. Use `--output json` to pipe the full payload into `jq`.

### forensics trace

```bash theme={null}
devhelm forensics trace <check-id>
```

Shows every evaluation and transition emitted for a single `checkId`. Useful when a webhook or support ticket references a specific execution ID.

### forensics snapshot

```bash theme={null}
devhelm forensics snapshot <hash-hex>
```

Fetches the policy JSON that was active at evaluation time. Hashes are stable — an old transition always resolves back to the exact policy that fired it, even if the monitor has since been edited.

### forensics evaluations

```bash theme={null}
devhelm forensics evaluations --monitor-id <monitor-id> --only-matched
devhelm forensics evaluations --monitor-id <monitor-id> \
  --rule-type consecutive_failures --region us-east \
  --from 2026-04-01T00:00:00Z --to 2026-04-07T00:00:00Z
```

| Flag             | Type     | Description                                                        |
| ---------------- | -------- | ------------------------------------------------------------------ |
| `--monitor-id`   | uuid     | **Required.** Monitor to query                                     |
| `--rule-type`    | string   | Filter by rule type (e.g. `consecutive_failures`, `response_time`) |
| `--region`       | string   | Filter by probe region                                             |
| `--only-matched` | boolean  | Return only evaluations that fired (`outputMatched = true`)        |
| `--from`         | ISO-8601 | Lower bound (`occurredAt >= from`)                                 |
| `--to`           | ISO-8601 | Upper bound (`occurredAt < to`)                                    |
| `--page`         | integer  | 0-based page index (default `0`)                                   |
| `--size`         | integer  | Page size (default `50`)                                           |

### forensics transitions

```bash theme={null}
devhelm forensics transitions --monitor-id <monitor-id>
devhelm forensics transitions --monitor-id <monitor-id> --from 2026-04-01T00:00:00Z
```

Same pagination flags as `evaluations`. Each row includes `fromStatus → toStatus`, `reason`, the `checkId` that caused it, and (when the transition was part of an incident lifecycle) the `incidentId`.

## Output formats

All `forensics` commands accept `--output table|json|yaml` (default `table`). The rendered table is deliberately terse — for the full DTO use `--output json` and pipe to `jq`.

## Next steps

<CardGroup cols={2}>
  <Card title="Incident Forensics" icon="magnifying-glass" href="/incidents/forensics">
    Concepts, retention, and use cases for the forensic model.
  </Card>

  <Card title="Incidents CLI" icon="circle-exclamation" href="/cli/commands/incidents">
    Pair `forensics timeline` with `incidents get` for the full picture.
  </Card>
</CardGroup>