> Source: https://vitna.ai/docs/cli/aperture/watchdog
> Raw Markdown: https://vitna.ai/docs/cli/aperture/watchdog.md
> Corpus index: https://vitna.ai/llms.txt

# Rollout and decision watchdog CLI

Evaluate standing-decision drift, shadow rule promotion readiness, and routed
canary health across an organisation's active workloads or offline against a
checked-in Stackfile and runtime ledger.

```bash
DATABASE_MIGRATE_URL=... npm run aperture:watchdog -- --org convexity
```

```bash
npm run aperture:watchdog -- --stackfile vitna.stack.json --policy policy.json --ledger ./ledger.jsonl --fail-on-rollback
```

Nothing is written to the database or disk. Every finding prints the exact
operator command (`aperture:decide`, `aperture:rule:promote`, `aperture:rule:add`,
or `aperture:rule:remove`) required to advance or roll back a rollout. See
[Rollout and decision watchdog](../../routing/watchdog.md) for how each verdict
is derived.

## Modes and flags

- **Register mode** (`--org <slug>` or `--workload <org/slug>`): reads active
  workloads, standing decisions (recovering decision-time unit costs from pinned
  `pricePeriodIds` and `enteredPriceIds`), lane rules, fallback chains, pushed
  `deployment_observation` windows, `evidence` rows, live Witness and entered
  rates, provider compliance terms, and three-provenance SKU capabilities. May
  optionally pair a local runtime `.jsonl` file via `--ledger <path>`.
- **Offline Stackfile mode** (`--stackfile <vitna.stack.json>`): runs with zero
  database connection for CI pipelines and GitOps checks, pairing the Stackfile
  with an optional signed `--policy <policy.json>`, `--ledger <file.jsonl>`,
  `--evidence <evals.json>`, and `--terms <terms.json>`.

| Flag | Meaning |
|---|---|
| `--org <slug>` | Evaluate all active workloads in `<slug>` |
| `--workload <org/slug>` | Narrow evaluation to one active workload |
| `--window YYYY-MM-DD..YYYY-MM-DD` | Restrict observation and ledger rows to one closed UTC date range |
| `--ledger <file.jsonl>` | Summarize per-request `vitna-runtime` ledger rows (`shadowRule`, `serve`, `cohort`, `latencyMs`) |
| `--stackfile <file>` | Run offline against a `vitna.stackfile.v1` file with no database |
| `--policy <policy.json>` | Pair offline Stackfile evaluation with a signed `policy.json` |
| `--evidence <evals.json>` | Supply offline evaluation rows in `--stackfile` mode |
| `--min-shadow-matches <n>` | Minimum shadow matches before `promote_ready` (default `50`) |
| `--min-canary-units <n>` | Minimum served canary units before `expand_or_adopt_ready` (default `100`) |
| `--max-unserved-pct <n>` | Maximum unserved attempt rate percentage (default `5`) |
| `--max-fallback-pct <n>` | Maximum fallback share of served traffic percentage (default `10`) |
| `--max-price-drift-pct <n>` | Maximum unit-cost increase vs standing decision percentage (default `10`) |
| `--json` | Emit structured JSON report |
| `--fail-on-rollback` | Exit `4` if any workload verdict is `rollback_recommended` or `decision_drifted` |

## Exit codes

| Code | Meaning |
|---|---|
| `0` | Evaluation succeeded (and no rollback or decision drift occurred when `--fail-on-rollback` is set) |
| `1` | Register mode requested with neither `DATABASE_MIGRATE_URL` nor `DATABASE_URL` set |
| `2` | Invalid flags, malformed date window, unreadable input file, or unknown organisation/workload |
| `4` | `--fail-on-rollback` was passed and at least one workload returned `rollback_recommended` or `decision_drifted` |
