The regression command discovers every example manifest under manifests/, runs each through execute → validate → test, and writes a consolidated report. It's the shipping gate — a passing regression run on a clean PDI is the release signal. Use --subset to target a single example during development.
regression
Run all example manifests end-to-end and report pass/fail.
sn regression [--subset <names>] [--clean] [--include-destructive] [--json] [--fail-fast] [--health-check] [--force] [--no-lock] [--fail-on-overlap] [--run-id <id>] [--output <dir>] [--timeout-ms <ms>] Run the full example suite and report pass/fail.
Flags
| Flag | Default | Description |
|---|---|---|
| --subset <names> | — | Comma-separated example directory names (run only these). |
| --clean | — | Back out every update set created during the run, even on success. |
| --include-destructive | — | Include examples tagged as destructive (skipped by default). |
| --json | — | Emit a machine-readable JSON result instead of the text report. |
| --fail-fast | — | Stop at the first failing example. |
| --health-check | — | Run `sn instance health` as a pre-flight — abort on CRITICAL (use `--force` to override). |
| --force | — | Proceed past a failing `--health-check` (the run still records the pre-flight result). |
| --no-lock | — | Skip the instance overlap lock (advanced — two regression runs on the same instance can corrupt each other). |
| --fail-on-overlap | — | Treat a held overlap lock as a hard error instead of a warning. |
| --run-id <id> | reg-<timestamp> | Override the auto-generated run ID. |
| --output <dir> | .sn-regression | Output directory for the run report. |
| --timeout-ms <ms> | 600000 | Per-example timeout in milliseconds. |
| --fresh-names | — | Suffix every `upsertKeys` input field with the run ID so each record is created cold instead of upserting onto the same name. Exercises the cold-create code path. Also settable via `REGRESSION_FRESH_NAMES=1`. |
Examples
sn regression --subset business-rule,script-include --health-check✓ instance health OK (errors: 0, slow: 1, active jobs: 34)
▶ running 2 example(s)
✓ business-rule (8.1s)
✓ script-include (6.4s)
All 2 example(s) passed.
Report: .sn-regression/reg-2026-04-18-10-22/report.md
sn regression --clean --fail-fast▶ running 14 example(s) (fail-fast)
✓ business-rule (7.9s)
✗ decision-table (12.4s) — structural test: missing input choice 'low'
Stopped on first failure. 1/14 ran.
Backing out update sets (--clean)…
✓ 2 update sets reverted
sn regression --fresh-names --subset business-ruleRegression run reg-2026-04-20-02-17
Mode: FRESH NAMES (upsertKeys suffixed with runId — cold creates)
▶ running 1 example(s)
✓ business-rule (9.2s)
All 1 example(s) passed.
--health-check is available on both sn regression and sn test — it short-circuits a run against a CRITICAL instance before any writes happen. Pair it with --force only when you're knowingly running against a degraded environment (e.g. reproducing an incident).
Upsert vs fresh names. Default mode (UPSERT) reuses stable names so a regression run is idempotent — re-running updates the same records. --fresh-names (or REGRESSION_FRESH_NAMES=1) suffixes the fields declared in each op's upsertKeys with the run ID, forcing a cold create every time. Use it before a release to prove the create path still works, not as the default loop.
The overlap lock (on by default) prevents two regression runs on the same SN_INSTANCE from stomping on each other's update sets. Disable it with --no-lock only for throwaway PDIs.