Fidryn

Docs CLI

§ 4 · Run

Fidryn CLI

On this page
  1. 4.1 Install
  2. 4.2 Exit status
  3. 4.3 Source checking and trust
  4. 4.4 fmt
  5. 4.5 check
  6. 4.6 run
  7. 4.7 explore
  8. 4.8 explain
  9. 4.9 verify
  10. 4.10 diff
  11. 4.11 render
  12. 4.12 file
  13. 4.13 ui
  14. 4.14 See also

The binary name is fidryn. It is the v0.1 reference interpreter: parse a .fr module, check it, and evaluate a named query against a case record. It is not legal advice and does not file anything unless you opt into live HTTP as described under file.

From a clone of this repository:

shell
cargo run -p fidryn-cli -- <subcommand> ...

After install, the same arguments work as fidryn <subcommand> .... fidryn --help and fidryn <subcommand> --help print clap usage.

4.1 Install #

From the repository root:

shell
cargo install --path crates/fidryn-cli

That places fidryn on your Cargo bin path. Workspace rust-version is 1.98.

4.2 Exit status #

Success is exit 0. Failures are exit 1. Compiler diagnostics, engine errors, adapter errors, and usage problems go to stderr. Successful payloads (formatted source, the word ok, evaluation-report JSON, rendered text, diff JSON, filing receipts) go to stdout.

A legal Outcome is not a process failure. run and explore print a fidryn.evaluation-report/v0.1 document (with nested outcomeDocument of schema fidryn.outcome/v0.1) and exit 0 even when the nested outcome kind is suspended, contingent, normConflict, outsideCompetence, or inconsistent. Unknown queries, invalid timestamps, missing files, and check errors are engine or compiler failures and exit 1.

4.3 Source checking and trust #

check, run, explore, verify, diff (when a snapshot is a .fr file), and render compile through Driver::check_path. That call loads the module’s source_manifest (or a sources/ fallback) and then check_with_sources with source_root set to the directory that contains the .fr file. Hex import digests are authenticated against artifact bytes next to the module:

  • a 64-digit hex digest must equal the full blake3 of the file at artifact.path relative to source_root;
  • a 32-digit hex digest must equal the first 16 bytes of that hash.

A missing file or a mismatch is diagnostic E200 for digest-required imports.

The digest string "fixture" is a test trust profile. It permits the import in this corpus; it is not byte verification of the artifact. Most example manifests under examples/ use "digest": "fixture".

Pasted source in the mill is different: it compiles in memory with an empty default manifest and does not read artifact files.

4.4 fmt #

Rewrite a module’s trailing whitespace to stdout. The file on disk is not modified.

Arguments

NameRequiredType
PATHyespath to a .fr file

Example

shell
fidryn fmt examples/trust/bryan-revocable-trust.fr

Success. The formatted source is printed to stdout, including a trailing newline.

Failure. Exit 1. Unreadable files print cannot read PATH: ... to stderr. Parse errors print a diagnostic (E100 ParseError: ...).

4.5 check #

Parse, elaborate, and type-check a module, including source-manifest authentication as described above.

Arguments

NameRequiredType
PATHyespath to a .fr file

Example

shell
fidryn check examples/trust/bryan-revocable-trust.fr

Success. Prints ok and exits 0.

Failure. Exit 1. Each diagnostic is printed to stderr as CODE Title: message (for example E310 PropAsGuard: ...). A module that cannot check:

shell
fidryn check tests/diagnostics/e310-prop-as-guard.fr

4.6 run #

Evaluate one query against one case record at a pair of bitemporal instants. run never chooses a completion. It does not search admissibleCompletions, pick an interpretation, or fill in missing evidence. --arg KEY=VALUE writes a string fact onto the case (case.facts[KEY]).

Arguments

NameRequiredType
PATHyespath to a .fr file
--query NAMEyesquery name (string)
--case RECORD.jsonyespath to a fidryn.case-record/v0.1 JSON file
--valid-at TIMEyesISO 8601 / RFC 3339 instant
--known-at TIMEyesISO 8601 / RFC 3339 instant
--arg KEY=VALUEno, repeatablesets case.facts[KEY] to the string VALUE
--scenarionoflag; evaluate with case.assumptions as a scenario overlay (executionMode: scenario)

--valid-at is valid time. --known-at is record time. Both accept a Z suffix or a numeric offset (+00:00, -04:00). Example spellings: 2033-01-01T00:00:00Z and 2033-01-01T00:00:00+00:00. --arg provision=ChildSupportWaiver writes case.facts["provision"]. A binding without = is an error. Without --scenario, evaluation is operative: case.assumptions are not applied as an overlay. With --scenario, the report keeps executionMode: scenario and serializes assumptions (an empty array when the case has none).

Example

shell
fidryn run examples/trust/bryan-revocable-trust.fr \
  --query acting_trustee \
  --case examples/trust/cases/one-certificate.json \
  --valid-at 2026-08-23T12:00:00Z \
  --known-at 2026-08-23T12:00:00Z

Override a fact without editing the case file:

shell
fidryn run examples/prenup/ava-noah.fr \
  --query provision_result \
  --case examples/prenup/cases/divorce-record.json \
  --valid-at 2026-08-23T12:00:00-07:00 \
  --known-at 2026-08-23T12:00:00-07:00 \
  --arg provision=ChildSupportWaiver

Success. Canonical JSON for schema fidryn.evaluation-report/v0.1 on stdout: schema, executionMode (operative or scenario), sourceTrust, verificationMethod, assumptions, optional coverage, and outcomeDocument. Nested outcomeDocument is the fidryn.outcome/v0.1 projection (module, sourceSnapshot, query, asOf, modelBoundary, outcome). Exit 0. See Outcomes.

Failure. Exit 1, stderr only. Check diagnostics; cannot read PATH; invalid case record: ...; --valid-at / --known-at parse errors; or an engine failure such as UnknownQuery: unknown query .... Those engine errors are not rewritten as outcome.kind = inconsistent.

4.7 explore #

Evaluate a query under an explicit finite completion space. The space must already be on the case as admissibleCompletions, or you must pass --bounds to merge more completions into the case. explore still does not invent interpretations; it only examines the declared finite bounds.

Arguments

NameRequiredType
PATHyespath to a .fr file
--query NAMEyesquery name (string)
--case RECORD.jsonyespath to a case-record JSON file
--bounds BOUNDS.jsonnoJSON file merged into case.admissibleCompletions
--valid-at TIMEyesRFC 3339 instant
--known-at TIMEyesRFC 3339 instant

--bounds may be an AdmissibleCompletions object (interpretations, evidence, choices) or a wrapper that contains admissibleCompletions / admissible_completions. A case-record JSON file that already carries that object is accepted. Entries are merged (extended), not replaced wholesale.

If neither the case nor --bounds supplies a nonempty completion space, exploration yields an inconsistent outcome whose core includes empty completion set. That is still a successful CLI run (exit 0) with an outcome document on stdout.

Example (case already declares admissibleCompletions; --bounds merges another copy of the same family from a second record in the repo):

shell
fidryn explore examples/trust/bryan-revocable-trust.fr \
  --query acting_trustee \
  --case examples/trust/cases/one-certificate.json \
  --bounds examples/trust/cases/two-certificates-open-eligibility.json \
  --valid-at 2026-08-23T12:00:00Z \
  --known-at 2026-08-23T12:00:00Z

Omit --bounds when the case record is already admissible, as examples/trust/cases/one-certificate.json is.

Success. The same fidryn.evaluation-report/v0.1 envelope as run, on stdout. If case.assumptions is nonempty, explore labels the report executionMode: scenario (there is no separate --scenario flag on explore).

Failure. Exit 1. Same compile, case, and timestamp failures as run; cannot read / invalid bounds JSON for --bounds; or bounds JSON must be AdmissibleCompletions or {interpretations, evidence, choices}: .... Engine failures print kind: message to stderr.

4.8 explain #

Render a trace as text, JSON, or Graphviz DOT.

Arguments

NameRequiredType
TRACE_IDyesfile path, PATH.json, or an opaque id string
--format FORMATnotext (default), json, or dot

If TRACE_ID is an existing file, or TRACE_ID.json exists, that JSON is loaded. An evaluation-report or outcome document from a prior run / explore is wrapped as a small DAG (nested outcomeDocument is used when present). If no such file exists, the argument is hashed as a TraceId and the node list is empty. JSON always includes a nodes array; emptiness means no persisted DAG was loaded, not an omitted field. Unknown --format values are treated as text.

Example

shell
fidryn run examples/trust/bryan-revocable-trust.fr \
  --query acting_trustee \
  --case examples/trust/cases/one-certificate.json \
  --valid-at 2026-08-23T12:00:00Z \
  --known-at 2026-08-23T12:00:00Z \
  > /tmp/fidryn-outcome.json

fidryn explain /tmp/fidryn-outcome.json --format text

Without a file, the id is hashed and the DAG is empty:

shell
fidryn explain 00000000000000000000000000000000 --format json

Success. Formatted trace on stdout. Text with no nodes is trace <hex>. JSON is a canonical TraceDocument. DOT is a digraph.

Failure. Exit 1. cannot read PATH: ... or invalid trace JSON PATH: ....

4.9 verify #

Check a declared verify property on a module. Query names are not properties. The name must appear in the module’s verify blocks.

Arguments

NameRequiredType
PATHyespath to a .fr file
--property NAMEyesdeclared verification name

Example

shell
fidryn verify examples/trust/bryan-revocable-trust.fr --property TrusteeContinuity

TrusteeContinuity is declared on that module. A bounded check that does not obtain a covering proof is not success: the CLI prints the verdict to stderr and exits 1. Only a proved verdict is exit 0 (today that is a declared true or assert true formula). Passing a query name such as acting_trustee is invalid.

Success. Stdout, for example proved NAME (persons=..., events=..., time_points=...).

Failure. Exit 1, stderr. Check diagnostics, or a verdict such as unknown NAME: ..., counterexample for NAME: ..., `NAME` is a query, not a declared verification property, or unknown property NAME.

4.10 diff #

Compare two snapshots and print canonical JSON with two named operations: result (outcomeDocument / compiled query bodies) and assurance (executionMode, sourceTrust, assumptions, verificationMethod). Each is {added, removed, changed}. Changing only qualifications is an assurance diff, not a silent equal. A .fr path is compiled; any other path is read as JSON (an evaluation report, mill {ok, report} wrapper, outcome document, or serialized module).

Arguments

NameRequiredType
OLD_SNAPSHOTyes.fr path or JSON file
NEW_SNAPSHOTyes.fr path or JSON file
--query NAMEyesquery name used when JSON has no embedded names

Example

shell
fidryn diff \
  examples/trust/bryan-revocable-trust.fr \
  examples/california/final-pay/final-pay.fr \
  --query acting_trustee

Identical snapshots (the same file twice) print empty arrays under both result and assurance.

Success. One canonical JSON object on stdout:

json
{"assurance":{"added":[],"changed":[],"removed":[]},"result":{"added":[],"changed":[],"removed":[]}}

Each of result and assurance has keys added, removed, and changed (sorted arrays of strings).

Failure. Exit 1. Compile diagnostics for .fr inputs; cannot read PATH; invalid snapshot JSON PATH: ...; or cannot encode diff: ....

4.11 render #

Interpolate Core fields into a template. Available keys from the compiled module are module, version, and outside_scope. Missing keys fail closed. A directory named certified does not approve legal content; templates/certified/ files are interpolation fixtures only.

Arguments

NameRequiredType
PATHyespath to a .fr file
--template TEMPLATEyespath to a template file

Example

shell
fidryn render examples/trust/bryan-revocable-trust.fr \
  --template templates/certified/instrument-outline.txt

Success. Rendered text on stdout (no extra newline beyond the template).

Failure. Exit 1. Check diagnostics; cannot read TEMPLATE; or missing template key \...``.

4.12 file #

Submit a JSON filing packet through an adapter. Dry-run is the default. Live HTTP requires both --live and the environment variable FIDRYN_ALLOW_LIVE_FILING=1. A successful transport receipt is not a Filed legal fact.

Arguments

NameRequiredType
PACKET.jsonyesJSON file parsed as the packet body
--adapter NAMEnodry-run (default), ma-corporations, or massachusetts
--livenoflag; enable live HTTP when the adapter and env allow it
--endpoint URLnolive POST URL for the Massachusetts adapter

--adapter massachusetts is an alias of ma-corporations. Any other adapter name uses dry-run. The dry-run adapter refuses --live even if the environment variable is set. The Massachusetts adapter’s default endpoint is https://www.sec.state.ma.us/filing.

There is no dedicated packet fixture in-tree; any JSON value is accepted. The LLC case record is a realistic dry-run body:

shell
fidryn file examples/massachusetts-llc/cases/transmitted-without-official-record.json

Live shape (does not establish Filed):

text
FIDRYN_ALLOW_LIVE_FILING=1 fidryn file \
  examples/massachusetts-llc/cases/transmitted-without-official-record.json \
  --adapter ma-corporations \
  --live \
  --endpoint https://www.sec.state.ma.us/filing

Success. Adapter JSON on stdout (kind is camelCase): dryRun with the packet echoed; or, for live Massachusetts HTTP, accepted (with filingId and raw), rejected, transportFailure, or submissionUncertain. accepted is a transport receipt.

Failure. Exit 1. cannot read PACKET; invalid packet JSON; or live filing is disabled (set FIDRYN_ALLOW_LIVE_FILING=1 and pass --live).

The mill has no filing route.

4.13 ui #

Serve the localhost mill. See mill for routes and the HTML page. The process binds 127.0.0.1 only and does not live-file.

Arguments

NameRequiredType
--port Nnou16 TCP port on loopback (default 8751)
--no-opennoflag; do not attempt to open a browser

This build does not link an opener crate. Without --no-open, stderr notes that browser auto-open is not linked. With --no-open, that line is omitted.

Example

shell
fidryn ui --port 8751 --no-open

Success. The server runs until Ctrl-C. Stderr includes fidryn mill on http://127.0.0.1:PORT and 127.0.0.1 only. live filing is disabled. Exit 0 after shutdown.

Failure. Exit 1. 127.0.0.1:PORT is already in use. Stop that process or pass --port. Other bind or runtime errors are printed to stderr.

4.14 See also #

Edit this page on GitHubView as Markdown

The modules, records, and examples here are research fixtures. They are not legal advice, not operative instruments, and not a complete statement of any jurisdiction’s law.