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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.