---
title: tier, runtimes, features…
description: The entitlement inspection commands — tier, runtimes, features, channels, nodes, retention and bundle — with their JSON shapes and --why lock-reason payloads.
keywords: clawmetry tier, clawmetry runtimes, clawmetry features, entitlement CLI, why is this locked
eyebrow: 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`

```bash
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`

```bash
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.

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

## `features`

```bash
clawmetry features
clawmetry features --why anomaly_detection
```

Same shape, for features rather than runtimes.

## `channels`

```bash
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`

```bash
clawmetry nodes
clawmetry nodes --why 5
```

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

## `retention`

```bash
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?

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

| Flag | Axis |
|---|---|
| `--features CSV` | Feature ids |
| `--runtimes CSV` | Runtime ids |
| `--channels N` | Concurrent-channel count |
| `--retention-days N` | Desired retention window |
| `--nodes N` | Registered-node count |
| `--tier TIER` | Resolve from a hypothetical perspective tier |

`--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](/docs/ops/plans/)