CLI Command Surface

stratt beginner 4 min read

ELI5

The CLI is the single front door. Nine commands ship today: create, check, hash, ship, run, deprecate, re-verify, see-impact, run-CI. Anything else (graph, diff, export-n8n) is parked behind Phase 2.

Technical Deep Dive

Phase 1 Commands

flowchart LR
    NEW["new"] --> VAL["validate"]
    VAL --> FP["fingerprint"]
    FP --> PUB["publish"]
    PUB --> RUN["run"]
    PUB --> IMP["impact"]
    PUB --> DEP["deprecate"]
    PUB --> VER["verify"]
    VER --> CI["ci"]
    IMP --> CI

Command Catalogue

Command	Reads	Writes	Phase
`new`	templates	local file	1
`validate`	local YAML	–	1
`fingerprint`	local YAML	–	1
`publish`	local YAML	registry	1
`run`	registry	execution log	1
`impact`	DAG	–	1
`deprecate`	registry	registry status	1
`verify`	registry	–	1
`ci`	DAG + gates	CI report	1
`graph`, `diff`, `export-n8n`, `council`, `merge`, `history`, `gate`, `import-veritas`, `analytics`, `auth`, `compile`, `regression`, `xp`, `namespace`, `export-dspy`	–	–	2+

The packages/cli/src/commands/ directory has 24 files; only the nine above are Phase-1 implemented per the TAD.

Read vs Write

validate and fingerprint are file-local; publish and deprecate are the only Phase-1 commands that mutate the registry. CI pipelines should run validate → fingerprint → verify → ci before invoking publish.

Key Terms

Registry → the published-unit store (R2-backed in Phase 2); publish writes here.
Gate → a CI check (FM-01..FM-08) executed by ci.
Impact → the blast-radius command; dry-run for a hypothetical change.

Q&A

Q: What’s the difference between validate and verify? A: validate runs Zod against a local YAML file. verify re-hashes a registry-resident unit and compares against the stored fingerprint.

Q: Why isn’t graph in Phase 1? A: Phase 1 ships the DAG library (L3) but not the user-facing visualisation; that lands with MERIDIAN (L6) in Phase 2.

Examples

A typical pre-merge hook: stratt validate ./units && stratt fingerprint ./units && stratt impact strat://dev/rule/no-secrets@1.1.0 — all three are non-mutating and safe in untrusted CI.

neighbors on the map

Unit Lifecycle States deciding whether a unit can be imported
Dependency DAG & Blast Radius estimating the impact of changing a shared rule