Skip to main content

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​

CommandPurpose
nudo checkGate contracts + entry throws; print signatures on success and failure (CI gate)
nudo testReport every inferred case; assert declared @nudo:case expectations
nudo contractPrint / draft / emit effective contracts — [handwritten] / [generated] / [implicit] layers
nudo exportProject Abs into dts / guard / schema / standard artifacts
nudo healthHealth-check files: analysis errors, call-site solidification drift
nudo migrateOne-way retire-tsc door: status / strip / verify / retire
nudo initSetup: 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:

ArgumentDescription
<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:

OptionDescription
--watch / -wRe-run on file changes (flag, not a verb)
--jsonStructured diagnostics + signatures — CheckJson (1 file) or CheckJsonMulti envelope (N files); cannot combine with --abs
--quietSuppress the signature table — issues + summary + gate exit unchanged; a clean run prints one summary line. Human text face only (--json / --gitlab machine contracts unaffected)
--ghaGitHub Actions inline annotations (::error / ::warning); auto-enabled when GITHUB_ACTIONS=true
--gitlabGitLab Code Quality JSON array for gl-code-quality-report.json (emitted on stdout — redirect to the file in CI)
--verboseExpand Abs signatures (term/pred/conf detail)
--explain-unknownAfter 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
--absPer-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
--generalizeWith --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|offSeverity for L2 entry may-throw (default error)
--profile adoption|strictGate profile (default strict). adoption = L2 entry may-throw demoted to warning; L1 stays error. An explicit --entry-throws value overrides the profile
--capabilities strict|trustedCapability 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
--fixMaterialize 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)
--writeWith --fix: apply edits to disk (default dry-run)
--dry-runWith --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.

L1 in 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, never unknown.
  • True unknown means inference failed (engine debt) and is annotated with conf.
  • The throws domain is always shown when present.
  • Success still prints signatures — check is not silent.

Obligation layers:

LayerSourceBehavior
L1 explicit*.nudo.js / @nudo:contractViolation → error
L2 default JS contractRuntime boundary on entry/export functionsUndigested 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:

CodeMeaning
0No error-level diagnostics
1Any 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:

OptionDescription
--watch / -wRe-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-pathsPrint 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
--jsonStructured case report (single file; cannot combine with --abs or --freeze)
--absPrint Abs algebra for cases
--dry-runWith --freeze: print a unified diff instead of writing
--exit-on-diffWith --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 synthesize entry@ for that function.
  • Only @nudo:case with => expected enter pass/fail.
  • Failures of declared assertions set exit 1; synthetic cases do not.
  • test --json includes an assertions summary (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:

CodeMeaning
0All declared assertions passed (or none declared)
1Any 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 @generated sidecar segment
  • [implicit] — call-site inference

Options:

OptionDescription
--emitPersist inferred domains as sidecar @generated segments
--draftGenerate a reviewable contract draft from existing code (code-first / migration)
--from-dtsReverse 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)
--writeWith --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.
--forceWith --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)
--allEmit all eligible functions
--dry-runPrint a unified diff instead of writing
--exit-on-diffWith --emit --dry-run: exit 1 when the diff is non-empty
--from <paths…>Usage-site evidence for domain projection
--jsonMachine 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:

CodeMeaning
0Success
1Usage / 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:

OptionDescription
--formatdts (default) | guard | schema | standard | all
--dialectSchema dialect; currently zod. Valid with schema / all
--out <dir>Write artifacts under this directory instead of stdout

Formats:

FormatArtifact
dtsTypeScript declarations — one widened signature per function; case precision preserved in JSDoc
guardRuntime type-guards (prefer lossless Abs path when available)
schemaZod JS module for --dialect (default zod) → *.nudo.schema.<dialect>.ts
standardStandard Schema v1 modules (~standard, vendor nudo) → <fn>.nudo.standard.ts
alldts + 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:

CodeMeaning
0Success
1Usage / 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:

OptionDescription
--watchRe-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|trustedCapability 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
--jsonStructured 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 drift counts changed witness directives (added + removed) summed over all files — the same unit as the per-file drift: N witness directive(s) changed line. The precision counts (unknown signature(s) / #widened witness(es)) are informational only — they never gate the exit code.

Exit codes:

CodeMeaning
0No drift, no analysis errors
1Drift 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]
ActionPurpose
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 --allEvery workspace package that still has tsc / typescript (monorepo batch)

Options:

OptionDescription
strip --writeWrite stripped .js next to the source (default is dry-run print)
strip --no-draftSkip best-effort sidecar draft (draft is on with --write)
strip --backupRename original .ts to .ts.bak after write
verify --with-tscAlso run tsc --noEmit baseline on .ts inputs (migration dual-run only)
retire --dry-runPrint the rewrite plan without touching package.json / workflows
retire --allBatch every workspace package that still carries tsc/typescript
retire --no-workflowsLeave .github/workflows untouched
--jsonMachine-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:

CodeMeaning
0Action completed (including dry-runs)
1Usage / 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 any entry params and throws), diagnostics with codes such as nudo:entry-may-throw, summary counts, budget (call/fork usage + truncated), and per-issue actions[] (structured next steps: draft / relax / callsite / assume / mock / … with optional executable command).
  • test --json — per-function cases (entry@ / call@ / directive), an assertions summary (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 a CheckJsonMulti envelope: kind:"multi", aggregate summary (adds files, optional budgetTruncated), and reports[] of per-file CheckJson. test --json stays single-file (--json requires a single file).

Exit codes summary​

CommandExit 1
checkAny error-level diagnostic (L1 or non-ignored L2)
testAny declared assertion failure
contract / export (read-only)Usage / IO errors
contract --emit --exit-on-diffWould write and a diff exists
healthDrift or analysis errors
migrate verifynudo check fails on the target
migrate (other)Usage / IO errors