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#
clawmetry diagnose
clawmetry diagnose --jsonPrints 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.
clawmetry diagnose --json | jq '{license: .license.status, plan: .cloud_plan.tier, enforce: .enforce}'verify-integrity#
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:
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.
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 |