---
title: diagnose / verify-integrity
description: clawmetry diagnose shows every input the entitlement resolver used; clawmetry verify-integrity checks the tamper-evident hash chain over local events.
keywords: clawmetry diagnose, entitlement troubleshooting, agent event integrity, tamper evident audit log
eyebrow: CLI reference
---

# `clawmetry diagnose` / `verify-integrity`

Two diagnostic commands. The first explains entitlement decisions; the second
proves your event history has not been altered.

## `diagnose`

```bash
clawmetry diagnose
clawmetry diagnose --json
```

Prints every input the entitlement resolver used to reach its verdict:

- The license file — present, valid, what it grants
- The cached cloud plan, and how old the cache is
- The enforce environment variable
- The in-process cache state

`--json` emits the same shape as `GET /api/entitlement/diagnostic`.

This is the command for "why does it think I am on the free tier?" — which is
almost always one of: a license file that did not activate, a cloud plan cache
that has not refreshed, or a machine fingerprint that changed.

```bash
clawmetry diagnose --json | jq '{license: .license.status, plan: .cloud_plan.tier, enforce: .enforce}'
```

## `verify-integrity`

```bash
clawmetry verify-integrity
clawmetry verify-integrity --json
clawmetry verify-integrity --node-id build-runner-07
```

| Flag | Effect |
|---|---|
| `--node-id` | Verify a single node (default: all nodes) |
| `--json` | Emit the result as JSON |

Events are written into a hash chain: each event's hash covers the previous
one. Verification walks the chain and reports whether it holds.

A broken chain means one of three things, and the output distinguishes them:

| Result | Meaning |
|---|---|
| `ok` | The chain verifies end to end |
| Break at a specific event | Events were altered or removed after the fact |
| `store_open_failed` | The store could not be opened — a problem with access, not with integrity |
| `daemon_too_old` | The daemon predates the chain feature; there is nothing to verify yet |

The synthetic statuses matter: "could not check" and "check failed" are very
different answers to an auditor, and conflating them would be the worst possible
behaviour for a tool whose job is to be believed.

Exit codes are unchanged by `--json`, so this works in a pipeline:

```bash
clawmetry verify-integrity --json > integrity.json || {
  echo "integrity check failed"; jq '.' integrity.json; exit 1
}
```

`CLAWMETRY_INTEGRITY` controls whether the chain is maintained at all.

→ [Tamper-evident integrity](/docs/data/integrity/)

## Which to reach for

| Symptom | Command |
|---|---|
| A feature or runtime is locked and you do not know why | `diagnose` |
| A license activated but nothing changed | `diagnose` |
| An auditor asks whether the log could have been edited | `verify-integrity` |
| The store looks wrong after a crash | `verify-integrity`, then [Troubleshooting](/docs/ops/troubleshooting/) |