Skip to main content
CFDL

CLI reference

cfdl [--json] <command>

--json (global) prints diagnostics as structured JSON — use it in scripts and CI. It changes diagnostics only: the IR and results are always JSON files at --out.

cfdl compile

cfdl compile <model_dir> --out <ir.json> [--packs <packs_dir>]

Compiles a model to canonical IR JSON. The argument is the model's folder, which must contain model.cfdl (plus any imported files), or that model.cfdl itself. The four domain packs are built into the binary, so --packs is optional: a local packs/ directory is used automatically when present, --packs names another directory, and the built-in packs are used otherwise. A --packs path that does not exist, or a directory with no pack in it, is refused with E4004_MISSING_PACK naming the path; it never falls back to the built-in packs.

cfdl validate

cfdl validate <model_dir> [--packs <packs_dir>]

Compile-checks without writing IR — it runs the same pipeline as compile and discards the result, so the two can never disagree. Pass --packs for a model that uses one: pack-lowered contracts have no effects block of their own, and a pack's domain validations only resolve with the registry available. Exit code is nonzero on any error diagnostic; combine with --json for machine-readable diagnostics (code, message, file, span).

cfdl parse

cfdl parse <model_dir>

Dumps the typed AST — useful for debugging grammar-level surprises and for tooling.

cfdl run

cfdl run <ir.json> --out <results.json> \
  [--config <run.json>] [--rate <f64>] [--as-of <YYYY-MM-DD>] \
  [--packs <packs_dir>] [--pack <name>]

Evaluates compiled IR and writes Results JSON.

  • --config — a run-config file: discount rate, parameter overrides, scenarios, Monte Carlo.
  • --rate — annual discount rate when the config does not set one. Without a rate from either, the run publishes no model.npv.
  • --as-of — valuation as-of date.
  • --pack <name> — computes that pack's domain metrics in addition to the core set, reading the pack from --packs, a local packs/, or the packs built into the binary, in that order.

Precedence: run-config values win over --rate/--as-of fallbacks.

cfdl pack list

cfdl pack list --path <packs_dir>

Lists the packs (id, version) visible in a packs directory.

Exit codes and diagnostics

Commands exit 0 on success and nonzero when errors were emitted. A successful compile still prints its warnings to stderr. Each diagnostic prints its severity and code, the message, the file, line and column, and the hint when there is one:

error[E2103_SCHEDULE_OUT_OF_BOUNDS]: Stream 'debt.principal' schedule is outside model timeline (timeline: 2026-01-01 to 2026-12-01).
  --> fixtures/invalid/bad_schedule_out_of_bounds/model.cfdl:7:12

A hint follows as = hint: and a note as = note:. With --json the same diagnostics print as JSON objects on stdout. Diagnostics carry codes (E1202, E5008, …) cataloged in the Diagnostics reference. Before 1.0 a code may be renamed or retired, and a retired code's number returns to the pool; from 1.0 a code is never renamed or reused.