CLI Reference
The nudo CLI runs type inference on .js, .mjs, and .ts files. Install it globally or run via npx — see Installation.
npx nudojs check ./src/utils.js
# or, after global install:
nudo check ./src/utils.js
This page is the canonical flag / option / exit-code specification. Tutorial-style walkthroughs live in CLI Usage.
Commands
| Command | Purpose |
|---|---|
nudo check | Gate contracts + entry throws; print signatures on success and failure (CI gate) |
nudo test | Report every inferred case; assert declared @nudo:case expectations |
nudo contract | Print / draft / emit effective contracts — [handwritten] / [generated] / [implicit] layers |
nudo export | Project Abs into dts / guard / schema / standard artifacts |
nudo health | Health-check files: analysis errors, call-site solidification drift |
nudo migrate | One-way retire-tsc door: status / strip / verify / retire |
nudo init | Setup: write an adoption baseline nudo config into package.json (idempotent) |
There is no observation verb. Observation is check signatures, test case reports, and IDE hover.
Observation: check / test. Contracts: contract + check. Ecosystem: export. Leaving tsc: migrate.
nudo check
Gate contracts (L1) and entry throws (L2). Prints signatures even when the run succeeds.
nudo check <paths...> [options]
Arguments:
| Argument | Description |
|---|---|
<paths...> | One or more .js, .mjs, or .ts files or directories (scanned recursively; .d.ts excluded). TypeScript annotations are stripped; analysis uses JS semantics. |
Options:
| Option | Description |
|---|---|
--watch / -w | Re-run on file changes (flag, not a verb) |
--json | Structured diagnostics + signatures — CheckJson (1 file) or CheckJsonMulti envelope (N files); cannot combine with --abs |
--quiet | Suppress the signature table — issues + summary + gate exit unchanged; a clean run prints one summary line. Human text face only (--json / --gitlab machine contracts unaffected) |
--gha | GitHub Actions inline annotations (::error / ::warning); auto-enabled when GITHUB_ACTIONS=true |
--gitlab | GitLab Code Quality JSON array for gl-code-quality-report.json (emitted on stdout — redirect to the file in CI) |
--verbose | Expand Abs signatures (term/pred/conf detail) |
--explain-unknown | After the human report, list why values became unknown / any (budget truncation, missing env, unmodeled construct, eval failure, no contract). Observation-only: default output is byte-identical, and --json / --gitlab machine contracts are unaffected |
--abs | Per-function algebra face (shape + conf); --generalize adds the symbolic term/pred α |
--fn <name> | With --abs: restrict to one function |
--assume <pred…> | With --abs: assume constraints, e.g. x>0 y>=1 |
--generalize | With --abs: polymorphic signatures via symbolic execution |
--from <paths…> | Usage-site files (tests/apps); their call records join the analysis |
--ignore-throws <names> | Comma-separated L2 throw types to ignore (e.g. TypeError,RangeError). Does not swallow L1 contract violations. |
--entry-throws error|warning|off | Severity for L2 entry may-throw (default error) |
--profile adoption|strict | Gate profile (default strict). adoption = L2 entry may-throw demoted to warning; L1 stays error. An explicit --entry-throws value overrides the profile |
--capabilities strict|trusted | Capability policy for untrusted source (default strict): side-effectful host globals and node: modules are hidden (nudo:capability-denied, value unknown); trusted restores the legacy surface. Not a sandbox |
--what-if <binding...> | AI3: assume name:type bindings and report --target (same semantics as LSP nudo.whatIf) |
--target <name> | With --what-if: binding whose inferred type to print |
--fix | Materialize one fix/adjust edit per issue (default dry-run: print unified diff). Silence/review actions are never auto-applied |
--only <codes…> | With --fix: only these diagnostic codes (e.g. nudo:entry-may-throw) |
--write | With --fix: apply edits to disk (default dry-run) |
--dry-run | With --fix: print diffs only (default; kept for explicitness) |
Configuration (package.json):
{
"nudo": {
"check": {
"profile": "strict",
"ignoreThrows": ["TypeError"],
"entryThrows": "error"
}
}
}
Every package.json#nudo key and NUDO_* variable on one page: the configuration reference.
Output format:
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.
L1in the issue header is the line number (the function is declared on line 1 here) — the layer is L2.
- Unconstrained entry parameters print as
any, neverunknown. - True
unknownmeans inference failed (engine debt) and is annotated with conf. - The throws domain is always shown when present.
- Success still prints
signatures—checkis not silent.
Obligation layers:
| Layer | Source | Behavior |
|---|---|---|
| L1 explicit | *.nudo.js / @nudo:contract | Violation → error |
| L2 default JS contract | Runtime boundary on entry/export functions | Undigested may-throw → error (nudo:entry-may-throw); filter with --ignore-throws |
L2 does not gate internal helpers. try/catch and refine can clear L2.
Example:
nudo check user.js
nudo check src/lib.js --ignore-throws TypeError --from tests/
# --json: one file → bare CheckJson; multiple files / directories → CheckJsonMulti envelope
nudo check src/lib.js --json
nudo check src/ --json
Exit codes:
| Code | Meaning |
|---|---|
0 | No error-level diagnostics |
1 | Any error-level diagnostic (L1 or non-ignored L2). --abs still gates. |
nudo test
Report every inferred case (including synthetic call@ / entry@) and run declared assertions.
nudo test <paths...> [options]
Options:
| Option | Description |
|---|---|
--watch / -w | Re-run on file changes |
--from <paths…> | Usage-site files whose calls become call@L cases |
--freeze[=mode] | Write synthesized cases back as @nudo:case directives. Mode: update re-synchronizes previously generated directives; no value = add mode, keeps existing directives |
--both-paths | Print directive witnesses and synthesized call@/entry@ witnesses for the same function in one round (teaching comparison face; exit semantics unchanged; cannot combine with --freeze). Default runs are mutually exclusive: when a function has both @nudo:case and call-site records, nudo test prints a both-paths hint naming those functions |
--only <names> | With --both-paths: limit synthesis to the named functions (comma-separated); without --both-paths it is a usage error |
--json | Structured case report (single file; cannot combine with --abs or --freeze) |
--abs | Print Abs algebra for cases |
--dry-run | With --freeze: print a unified diff instead of writing |
--exit-on-diff | With --freeze --dry-run: exit 1 when the diff is non-empty |
Output format:
=== getName ===
call@L42 ({ name: "Ada" }) => "Ada"
debug "empty" ({}) => undefined
assertions
— 0 passed · 0 failed · 0 unchecked (no declared @nudo:case expectations; 1 synthetic case(s) printed above)
When no usage-site call is found for an entry export:
=== getName ===
entry@L6 (any) => any throws TypeError
- Synthetic
call@/entry@cases print by default — this is call-site observation. - When usage-site
call@cases exist, the analyzer does not also synthesizeentry@for that function. - Only
@nudo:casewith=> expectedenter pass/fail. - Failures of declared assertions set exit
1; synthetic cases do not. test --jsonincludes anassertionssummary (passed/failed/unchecked) and still exits 1 on declared assertion failure.
A failing declared assertion (nudo:case-expected) renders as:
=== double ===
debug "bad" (2) => 4
assertions
✗ 0 passed · 1 failed · 0 unchecked
[FAIL] double case "bad"
expected: 5
actual: 4
Example:
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)
nudo test lib.js --from test.js --freeze=update
Exit codes:
| Code | Meaning |
|---|---|
0 | All declared assertions passed (or none declared) |
1 | Any declared assertion failed |
nudo contract
Print, draft, or emit each function's effective contract with its source layer.
nudo contract <paths...> [--from <paths...>]
nudo contract --emit <paths...> [--fn <name>] [--all] [--dry-run] [--exit-on-diff] [--from <paths...>]
nudo contract --draft <paths...> [--write] [--json] [--fn <name>] [--dry-run] [--from <paths...>]
nudo contract --from-dts <paths...> [--write] [--dry-run] [--force]
Layers:
[handwritten]— source@nudo:contract/ sidecar binding (product term: contract)[generated]— persisted@generatedsidecar segment[implicit]— call-site inference
Options:
| Option | Description |
|---|---|
--emit | Persist inferred domains as sidecar @generated segments |
--draft | Generate a reviewable contract draft from existing code (code-first / migration) |
--from-dts | Reverse TypeScript .d.ts / annotated .ts sources, or an npm package's types (the positional <paths...>), into a reviewable @nudo:draft (*.nudo.draft.js). Not enforced until you review it and copy accepted exports into a *.nudo.js sidecar — the contracts step of the TypeScript-retirement path (Migrate from TypeScript) |
--write | With --draft / --from-dts: write *.nudo.draft.js to disk. With --from-dts, the draft is written next to the source .d.ts (not into the current directory) and an existing draft that differs is never silently overwritten — the command refuses and exits 1. |
--force | With --from-dts --write: overwrite an existing machine-generated draft that differs (same escape hatch as NUDO_DRAFT_FORCE=1). A hand-edited draft is never overwritten — merge it manually or delete it to regenerate (exit 1). |
--fn <name> | Restrict to one function (repeatable; may name a downstream derivation target when a handwritten root exists) |
--all | Emit all eligible functions |
--dry-run | Print a unified diff instead of writing |
--exit-on-diff | With --emit --dry-run: exit 1 when the diff is non-empty |
--from <paths…> | Usage-site evidence for domain projection |
--json | Machine face for print / --draft / --emit: the top level is always a JSON array (one element per input). --draft elements are { file, draftPath, draftSource, diff, entries[] }, --emit elements are { file, sidecar, changed, written, skipped[], issues[], diff? }, print elements are { file, entries[] } (AI4) |
Examples:
nudo contract calc.js
nudo contract --draft double.js --write
nudo contract --from-dts ./my-pkg/src/index.ts
nudo contract --emit lib.js --fn add2
Generated sidecar comment form:
// @generated by nudo — do not edit; regenerate with `nudo contract --emit`
Handwritten bindings always win; emit refuses to overwrite them (nudo:contract-name-clash). Re-running emit with unchanged evidence is a no-op.
Exit codes:
| Code | Meaning |
|---|---|
0 | Success |
1 | Usage / IO error; or --exit-on-diff with a non-empty would-be write |
nudo export
Project Abs into ecosystem artifacts. The only CLI path for .d.ts, guards, and schema projections.
nudo export <path> [--format dts|guard|schema|standard|all] [--dialect zod] [--out dir]
Options:
| Option | Description |
|---|---|
--format | dts (default) | guard | schema | standard | all |
--dialect | Schema dialect; currently zod. Valid with schema / all |
--out <dir> | Write artifacts under this directory instead of stdout |
Formats:
| Format | Artifact |
|---|---|
dts | TypeScript declarations — one widened signature per function; case precision preserved in JSDoc |
guard | Runtime type-guards (prefer lossless Abs path when available) |
schema | Zod JS module for --dialect (default zod) → *.nudo.schema.<dialect>.ts |
standard | Standard Schema v1 modules (~standard, vendor nudo) → <fn>.nudo.standard.ts |
all | dts + guard + schema + standard |
Schema projections carry Abs pred fidelity when expressible (gt/ge/lt/le, int, string length); symbolic preds are reported as dropped preds comments. standard enforces the same refinements at runtime via validate and remains a one-way projection — nudo check is still the CI gate.
.d.ts / schema projections are one-way, lossy views of Abs. Export does not take --watch.
Examples:
nudo export src/user.js --format schema --dialect zod
nudo export src/user.js --format standard --out dist
nudo export src/user.js --format dts --out dist/types
nudo export src/api.js --format all --out dist
Exit codes:
| Code | Meaning |
|---|---|
0 | Success |
1 | Usage / IO errors |
nudo health
Health-check source files: analysis errors and call-site solidification drift.
nudo health [paths...] [--watch] [--from <paths...>] [--capabilities strict|trusted] [--json]
Options:
| Option | Description |
|---|---|
--watch | Re-run on file changes |
--from <paths…> | Usage-site files; health re-runs the same re-solidify chain as test --freeze=update and reports drift when generated call@ directives would change |
--capabilities strict|trusted | Capability policy for untrusted source (default strict): side-effectful host globals and node: modules are hidden (nudo:capability-denied); trusted restores the legacy surface. Not a sandbox |
--json | Structured health report |
Example:
nudo health src/ --from tests/
src/lib.js
· 1 function(s)
✗ drift: 3 witness directive(s) changed (+2 new, -1 removed) — refresh: nudo test src/lib.js --from tests/ --freeze=update
Summary: 1 file(s) · 3 case drift · 0 contract drift · 0 error(s) · 0 uncovered function(s) · 0 unknown signature(s) · 0 #widened witness(es)
Result: FAIL (drift or errors found)
case driftcounts changed witness directives (added + removed) summed over all files — the same unit as the per-filedrift: N witness directive(s) changedline. The precision counts (unknown signature(s)/#widened witness(es)) are informational only — they never gate the exit code.
Exit codes:
| Code | Meaning |
|---|---|
0 | No drift, no analysis errors |
1 | Drift or analysis errors (uncovered functions are informational only) |
nudo migrate
One-way door off TypeScript: audit → strip annotations → gate with nudo check → retire tsc. Coexistence is a migration tactic; the exit is retire.
nudo migrate <status|strip|verify|retire> [paths...] [options]
| Action | Purpose |
|---|---|
status <pkg-or-dir> | Audit .ts/.tsx counts, tsconfig, typescript dep, tsc scripts, workflow tsc lines, and blockers |
strip <paths...> | .ts → .js (type annotations stripped; runtime stays). Dry-run by default |
verify <paths...> | Run nudo check on the JS surface — must pass before retire |
retire <pkg-or-dir> | Drop typescript dep, rewrite tsc scripts → nudo check, rewrite .github/workflows tsc lines, write .nudo/migrate-retired.json |
retire --all | Every workspace package that still has tsc / typescript (monorepo batch) |
Options:
| Option | Description |
|---|---|
strip --write | Write stripped .js next to the source (default is dry-run print) |
strip --no-draft | Skip best-effort sidecar draft (draft is on with --write) |
strip --backup | Rename original .ts to .ts.bak after write |
verify --with-tsc | Also run tsc --noEmit baseline on .ts inputs (migration dual-run only) |
retire --dry-run | Print the rewrite plan without touching package.json / workflows |
retire --all | Batch every workspace package that still carries tsc/typescript |
retire --no-workflows | Leave .github/workflows untouched |
--json | Machine-readable output |
Convert annotations into reviewable contracts with contract --from-dts (@nudo:draft is not enforced until accepted into *.nudo.js).
Samples: docs/examples/migrate/ · docs/examples/retire-real/. Walkthrough: Migrate from TypeScript.
Exit codes:
| Code | Meaning |
|---|---|
0 | Action completed (including dry-runs) |
1 | Usage / IO errors; verify fails when nudo check fails |
nudo init
nudo init [path]
Setup verb (aligned with tsc's init command): write an adoption baseline into the nearest package.json — "nudo": { "check": { "profile": "adoption" } } (L2 entry may-throw demoted to warning; L1 contract violations stay error).
Idempotent: re-running on a package.json that already has a nudo key prints the current config without writing. An invalid nudo value (null / scalar / array) is replaced by the baseline with a warning; an inheritable ancestor nudo config is never shadowed (refused); a workspace / container root is never written across (refused).
An explicit nudo init <container-root> writes the baseline into that root with a scope warning (the nudo key then applies to every package below it); only writing across the boundary from a subdirectory is refused.
Exit codes: 0 on success and idempotent re-runs; 1 on usage / IO errors (no package.json found, malformed JSON, shadowing an inheritable ancestor config, writing across a workspace / container root).
JSON output
check --json and test --json are the machine-readable faces.
- check --json — signatures (including
anyentry params and throws), diagnostics with codes such asnudo:entry-may-throw, summary counts,budget(call/fork usage +truncated), and per-issueactions[](structured next steps:draft/relax/callsite/assume/mock/ … with optional executablecommand). - test --json — per-function cases (
entry@/call@/ directive), anassertionssummary (passed/failed/unchecked), diagnostics, and optional Abs intension blocks. Declared assertion failures still exit 1. - check --json file counts — one file emits bare
CheckJson; multiple files (or a directory expanding to several) emit aCheckJsonMultienvelope:kind:"multi", aggregatesummary(addsfiles, optionalbudgetTruncated), andreports[]of per-fileCheckJson.test --jsonstays single-file (--json requires a single file).
Exit codes summary
| Command | Exit 1 |
|---|---|
check | Any error-level diagnostic (L1 or non-ignored L2) |
test | Any declared assertion failure |
contract / export (read-only) | Usage / IO errors |
contract --emit --exit-on-diff | Would write and a diff exists |
health | Drift or analysis errors |
migrate verify | nudo check fails on the target |
migrate (other) | Usage / IO errors |