CLI Usage
Task-oriented walkthroughs for the nudo CLI on .js, .mjs, and .ts files. Install via npx — see Installation. Full flag / exit-code tables: CLI Reference.
Primary verbs
nudo — JavaScript types, computed
nudo check <path> [--watch|-w] # gate contracts + entry throws; print signatures
nudo test <path> [--watch|-w] # report every inferred case; assert declared expectations
nudo contract <path> # draft / emit contracts
nudo export <path> # project dts / guard / schema / standard
nudo health [paths] # project health & drift
Observation lives in the output of check / test and in IDE hover — not a separate primary command.
Setup: nudo init [path] — write an adoption baseline (nudo.check.profile: "adoption") into the nearest package.json. Idempotent: an existing nudo key is printed, never overwritten. An invalid nudo value (null / scalar / array) is replaced by the baseline with a warning; an inheritable ancestor nudo config is never shadowed (refused, exit 1); a workspace / container root is never written across (refused, exit 1). An explicit nudo init <container-root> writes the baseline into that root with a scope warning; only writing across the boundary from a subdirectory is refused. In a zero-config, zero-directive project, a failing nudo check prints an onboarding block pointing here.
Observation: nudo check (signatures + gate). Optional debug: nudo test (case witnesses).
Contracts: nudo contract + nudo check.
Ecosystem: nudo export.
Off tsc: nudo migrate (one-way status → strip → verify → retire).
| Want to know | Run |
|---|---|
| Entry signatures / any / unknown / throws | nudo check <path> (prints signatures even on success) |
| Per-call-site ground truth / narrowing | nudo test <path> (prints every case, including synthetic call@ / entry@) |
| Usage-site argument shapes | nudo check / test / contract --from <paths…> |
Algebra face (shape + conf; --generalize adds term/pred α) | nudo check --abs (or test --abs) |
| Machine-readable | nudo check --json / nudo test --json |
| Interactive | IDE hover / inlay |
nudo check
Gate contracts and entry throws. On success and failure, check prints signatures — it is not silent.
nudo check <path> [--watch|-w] [--json] [--quiet] [--verbose] [--abs]
[--from paths…] [--ignore-throws names] [--entry-throws error|warning|off]
[--profile adoption|strict] [--capabilities strict|trusted] [--gha] [--gitlab] [--what-if name:type… [--target name]]
Further flags, one line each (full tables in the CLI Reference):
--profile adoption|strict— gate profile (defaultstrict):adoptiondemotes L2 entry may-throw to warning, L1 stays error; an explicit--entry-throwsvalue overrides.--quiet— suppress the signature table (issues + summary + gate exit unchanged; a clean run prints one summary line) for large CI logs.--gha— GitHub Actions inline annotations (::error/::warning); auto-enabled whenGITHUB_ACTIONS=true.--gitlab— GitLab Code Quality JSON array on stdout; redirect togl-code-quality-report.jsonin CI.--what-if <name:type…>— assumename:typebindings (e.g.raw:string); with--target <name>, print that binding's inferred type (AI3).
nudo check user.js
nudo check user.js
FAILED
2 error · 0 warning · 0 info · 3 fn
signatures
getName(user: any) => any throws TypeError
subtract(a: any, b: any) => number throws TypeError
clamp(n: any, lo: any, hi: any) => any
issues
[ERROR L1 getName] getName (export): may throw TypeError (nudo:entry-may-throw)
…
[ERROR L5 subtract] subtract (export): may throw TypeError (nudo:entry-may-throw)
…
Excerpt — the full transcript, its user.js source, and remediation paths: nudo check.
Unconstrained entry parameters display as any. unknown means inference failed (engine debt) — it is never the default for an unconstrained entry parameter. In [ERROR L# name], L# is the line number of the offending call/declaration — not a contract layer (L1/L2 are the layers). The sample above prints L1 because getName is declared on line 1 of that file — its layer is L2.
- Semantics (L1 explicit contracts / L2 entry throws, exit codes, filtering): nudo check
- Options & config (
--watch/--json/--quiet/--abs/--from/--ignore-throws/--entry-throws/--profile/--gha/--gitlab/--what-if,package.json#nudo.check): CLI Reference
nudo check is the CI gate.
nudo test
Report every inferred case and run declared @nudo:case assertions.
nudo test <path> [--watch|-w] [--from paths…] [--freeze[=mode]] [--dry-run] [--exit-on-diff] [--json] [--abs]
Given math.js:
export function subtract(a, b) {
return a - b;
}
subtract(5, 3);
subtract(1, 10);
nudo test math.js
=== subtract ===
call@L5 (5, 3) => 2
call@L6 (1, 10) => -9
assertions
— 0 passed · 0 failed · 0 unchecked (no declared @nudo:case expectations; 2 synthetic case(s) printed above)
- Synthetic
call@/entry@cases print by default — that is the call-site observation surface. - When usage-site
call@cases exist, the analyzer does not also synthesizeentry@for that function. - Only
@nudo:casedirectives with=> expectedenter pass/fail; failures affect the exit code. --from <paths…>harvest usage-site call shapes.--freeze[=mode]solidifies synthesized cases as directives:--freeze(no value, add mode) adds new witnesses;--freeze=updatere-synchronizes previously generated directives.--dry-run(with--freeze) prints a unified diff instead of writing;--exit-on-diff(with--freeze --dry-run) exits 1 when the diff is non-empty.--json/--absmirrorcheck;test --jsonalso carries anassertionssummary (passed/failed/unchecked) and still exits 1 when a declared assertion fails.
Full walkthrough — synthetic-case lifecycle, --freeze workflows, assertion authoring: nudo test.
Example with declared assertions
/**
* @nudo:case "double" (2) => 4
*/
export function double(x) {
return x * 2;
}
nudo test file.js
=== double ===
debug "double" (2) => 4
assertions
✓ 1 passed · 0 failed · 0 unchecked
[ok] double case "double" → 4
nudo contract
Draft, print, or emit effective contracts (handwritten / generated / implicit layers).
nudo contract <path> [--emit] [--draft] [--write] [--fn name] [--all]
[--dry-run] [--exit-on-diff] [--from paths…] [--from-dts]
nudo contract src/lib.js # print effective contracts
nudo contract --draft src/lib.js # reviewable *.nudo.draft.js
nudo contract --draft --write src/lib.js # write the draft
nudo contract --from-dts ./my-pkg/src/index.ts # reverse .d.ts / TS annotations into a reviewable draft
nudo contract --emit src/lib.js --fn add2 # persist @generated sidecar segment
nudo contract --emit src/lib.js --all --dry-run --exit-on-diff # CI drift gate
- Handwritten sidecar bindings always win over generated segments.
--emit --exit-on-diffexits1when the write would produce a diff.- Usage-site evidence:
--from <paths…>. --from-dts <paths…>reverses TypeScript.d.ts/ package types into a reviewable@nudo:draft— not enforced until you copy accepted exports into*.nudo.js(the contracts step of TS retirement; see Migrate from TypeScript).
nudo export
Project Abs into ecosystem artifacts. This is the only CLI path for .d.ts, guards, and schema projections.
nudo export <path> [--format dts|guard|schema|standard|all] [--dialect zod] [--out dir]
nudo export src/user.js --format dts --out dist/types
nudo export src/user.js --format schema --dialect zod
nudo export src/user.js --format standard --out dist
nudo export src/user.js --format all --out dist
| Format | Artifact |
|---|---|
dts | TypeScript declarations (one widened signature per function; case precision in JSDoc) |
guard | Runtime type-guard functions |
schema | Schema source projection for a dialect (default dialect: zod) → *.nudo.schema.<dialect>.ts |
standard | Standard Schema v1 runtime modules (~standard, vendor nudo) → <fn>.nudo.standard.ts |
all | dts + guard + schema + standard |
Full per-format semantics and exit codes: CLI Reference.
nudo health
Project health: analysis errors and solidification drift.
nudo health [paths…] [--watch] [--from paths…] [--json]
Exit 1 on drift, analysis errors, or missing --from paths. Under --json, --from path errors land in top-level pathErrors[] and force ok: false. Uncovered functions are informational only.
nudo health src/ --from tests/
When generated call@ directives would change, health reports drift and suggests:
nudo test lib.js --from test.js --freeze=update
Typical workflows
Observation — read types from existing JS
nudo check src/app.js # signatures + L2 entry throws (the gate)
nudo test src/app.js # optional debug: every call-site case
Contracts — explicit contracts
nudo contract --draft src/lib.js --write # reviewable draft
nudo check src/lib.js # L1 + L2 gate
CI
nudo check src/ --json
# optional: ignore noisy L2 types while migrating
nudo check src/ --ignore-throws TypeError
Ecosystem types
nudo export src/api.js --format dts --out dist/types
Continuous development
nudo check src/ --watch
# or
nudo test src/ --watch
any vs unknown
Unconstrained entry params display as any; unknown means inference failed (engine debt) and must never be described as the default for unconstrained params. The full contract (sources, operations, narrowing, product story) lives in Abs — any vs unknown.
Exit codes
Per-command exit contracts: CLI Reference. CI gates only on check (plus test declared assertions and health drift).
Next
- Mental model
- nudo check — the CI gate in detail
- CLI Reference — every flag and exit code
- Examples — real check/test output