Skip to main content

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 knowRun
Entry signatures / any / unknown / throwsnudo check <path> (prints signatures even on success)
Per-call-site ground truth / narrowingnudo test <path> (prints every case, including synthetic call@ / entry@)
Usage-site argument shapesnudo check / test / contract --from <paths…>
Algebra face (shape + conf; --generalize adds term/pred α)nudo check --abs (or test --abs)
Machine-readablenudo check --json / nudo test --json
InteractiveIDE 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 (default strict): adoption demotes L2 entry may-throw to warning, L1 stays error; an explicit --entry-throws value 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 when GITHUB_ACTIONS=true.
  • --gitlab — GitLab Code Quality JSON array on stdout; redirect to gl-code-quality-report.json in CI.
  • --what-if <name:type…> — assume name:type bindings (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:

engine-verifiedRun in Playground
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 synthesize entry@ for that function.
  • Only @nudo:case directives with => expected enter 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=update re-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 / --abs mirror check; test --json also carries an assertions summary (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​

engine-verifiedRun in Playground
/**
* @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-diff exits 1 when 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
FormatArtifact
dtsTypeScript declarations (one widened signature per function; case precision in JSDoc)
guardRuntime type-guard functions
schemaSchema source projection for a dialect (default dialect: zod) → *.nudo.schema.<dialect>.ts
standardStandard Schema v1 runtime modules (~standard, vendor nudo) → <fn>.nudo.standard.ts
alldts + 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​