CLI reference

tier, runtimes, features, channels, nodes, retention, bundle#

Seven read-only commands that answer "what does this install have, and what would it take to have more?" All of them take --json, and all of the --why forms mirror an HTTP endpoint exactly.

tier#

clawmetry tier
clawmetry tier --json | jq '{tier, grace, enforced}'

The resolved entitlement: which tier, whether grace mode is on, whether enforcement is active, and the full feature and runtime sets that follow.

runtimes#

clawmetry runtimes
clawmetry runtimes --json
clawmetry runtimes --why claude_code

--json emits {tier, grace, enforced, runtimes: [...]}. Each runtime row carries its id, label, whether it is detected on this machine, and whether this install can unlock it.

--why <id> prints the lock-reason payload — the same shape as GET /api/entitlement/lock-reason?runtime=<id> — which tells you what tier would unlock it and why it is locked now.

# what is detected but locked?
clawmetry runtimes --json \
  | jq '[.runtimes[] | select(.detected and (.allowed | not)) | .id]'

features#

clawmetry features
clawmetry features --why anomaly_detection

Same shape, for features rather than runtimes.

channels#

clawmetry channels
clawmetry channels --json | jq '{channel_limit, tier}'
clawmetry channels --why 8

The channels axis is capacity-scoped: every adapter is free, and what a tier bounds is how many you may run concurrently. So --why takes a count, not an adapter id.

nodes#

clawmetry nodes
clawmetry nodes --why 5

Also capacity-scoped: --why takes a node count.

retention#

clawmetry retention
clawmetry retention --json
clawmetry retention --why 90

--json returns {tier, grace, enforced, retention_days, effective_retention_days, override_env_name, override_env_value} — note the distinction between the tier's cap and the effective window after CLAWMETRY_RETENTION_DAYS is applied. An override cannot exceed what the tier allows, and this is where you see both numbers.

bundle#

The one that answers a real purchasing question: given everything I want, what is the cheapest tier that covers it?

clawmetry bundle \
  --runtimes claude_code,cursor,codex \
  --features anomaly_detection,cost_optimizer \
  --channels 6 --retention-days 90 --nodes 4 --json

--json emits {tier, grace, enforced, perspective, constraints, required_tier, affordable_tiers, error?}, mirroring /api/entitlement/required-tier and /affordable-tiers on the shared keys.

Grace mode#

If grace is true in any of these payloads, checks currently answer "allowed" regardless of the resolved tier. That is the current default, and it is why a locked-looking runtime may still be ingesting. enforced tells you whether that has changed on this node.

→ Plans and entitlements