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