Command and facts reference¶
The standalone immuknow executable is the integration boundary. It embeds Typst 0.15.1 and its shared resources; no Python runtime or separate Typst command is needed.
immuknow project sync [--project DIR] [--replace]
immuknow project check [--project DIR] [--sample [--template FILE]]
immuknow run --sample [--project DIR] [--template FILE] [--output DIR]
immuknow prepare --sample [--project DIR] [--template FILE]
immuknow run CSV --project DIR (--notices JSON | --template FILENAME)
immuknow prepare CSV --project DIR (--notices JSON | --template FILENAME)
immuknow run CSV (--notice-assignments JSON [--templates DIR] | --template FILE)
[--config DIR] [--output DIR] [--input-encoding utf-8-sig|cp1252|latin-1]
[--compile-workers 1|2] [--encryption-workers N] [--bundle-workers N] [--timestamp UNIX]
immuknow prepare CSV (--notice-assignments JSON [--templates DIR] | --template FILE)
[--config DIR] [--input-encoding utf-8-sig|cp1252|latin-1]
immuknow resources --output DIR
immuknow rebundle RUN_DIR [--policy policy.json] [--withhold ROW_KEY --reason TEXT]
[--release ROW_KEY] [--bundle-workers N] [--filenames filenames.json]
immuknow refresh-exports RUN_DIR
With --notices and no explicit project or templates path, ImmuKnow uses templates/ and config/ in the working directory. Without --project, relative --template paths are resolved from the working directory.
--project DIR supplies DIR/templates and DIR/config. An explicit --config overrides the configuration folder. With an assignment file, --templates overrides the templates folder; it conflicts with --template. With a project, relative single-template names are resolved inside its templates folder; absolute template paths retain their existing meaning. CSV and assignment-file paths are always relative to the working directory. Selection stays explicit. --notices is a visible alias for --notice-assignments. The same project shortcut works with prepare.
Global display options are --progress auto|plain|off and --emoji. Progress and summaries use stderr; redirected stdout remains a single saved-record path for run and rebundle, or JSON for prepare and resources. The terminal summary prints the selected CSV paths, while stdout retains the saved-record path. Auto mode redraws a throttled progress line only on a capable terminal; elsewhere it writes plain stage announcements and occasional counts. Plain mode avoids redraws and styling; off hides all progress and summary output. NO_COLOR disables styling. Progress receipts contain only counts, not client information.
refresh-exports regenerates paired CSVs from the last readable checkpoint without compiling notices; failed and running .incomplete runs are accepted. See PDF review for recovery.
Run results¶
run saves source data, resource snapshots, originals, canonical facts and
validated evidence in a run directory. Facts remain in run.json rather than
separate per-row files. Final reporting publishes the paired CSVs and any
requested grouped PDFs. Warnings alone do not fail the command; a failed notice
or requested encryption produces a nonzero exit status. Readable originals with
failed checks go to review bundles. See PDF review
for export fields, routing and saved-run changes.
Prepared facts¶
prepare writes JSON to standard output without rendering PDFs. The envelope
has schema_version: 2, engine and resource identity, input.sha256, top-level
checks and entries. Every entry contains source identity, exact source
values, its validated explicit assignment, observed checks and a separate
deferred_checks list. Ready entries also contain notice and blocked_checks;
failed source preparation has no invented notice. Row keys preserve identity
even when client IDs are absent or repeated.
Invalid history or intended-reader values fail only their source rows. A
successfully written preparation envelope exits 0 even when it contains failed
rows; run and project checks retain failure exits. Requirements and coverage
checks stay deferred until compilation. Validated reports resolve them or
explicitly block dependent checks; corrupt evidence is rejected.
Worker options¶
| Option | Values | Default |
|---|---|---|
--compile-workers |
1 or 2 | 2 on four or more available CPUs; otherwise 1 |
--encryption-workers |
0 through 16; 0 runs inline | Same CPU-based default as compilation |
--bundle-workers |
1 through 16 | 4 |
Compilation may finish out of order, but facts, findings, originals and progress
are committed in source-row order. rebundle also accepts --bundle-workers.
Resources for authoring tools¶
The exported schemas/input_schema.json describes CSV fields and schemas/rendering.json describes notice facts (schema version 2). Compiled reports follow typst/report.json (schema version 4). The schema filenames are unversioned; each payload's schema_version identifies its format. The exported typst/ directory is the shared library used by authored projects; copy it intact to the project's templates/lib/immuknow/ directory. The shared report contract and Typst components remain part of that library. Projects provide their own configuration, reference data, notices, Settings, translations and assets.
The template guide describes fields and component behavior. Studio and Template are separate projects with their own integration requirements.
Resource compatibility¶
immuknow resources --output DIR exports schemas/, typst/ and
resource-manifest.json. Export into a new folder when updating ImmuKnow, then replace
the project's complete templates/lib/immuknow/ copy. Existing identical files
are accepted; different files are not overwritten. Do not mix releases.
The manifest identifies resource contents, rather than a source commit; keep
the executable's source identity separately when pinning integrations.
Use project sync below to install the library directly. Project configuration
and reference lists are described in configuration;
projects and contracts defines resource ownership.
Native project setup and samples¶
immuknow project sync --project project
immuknow project check --project project
immuknow project check --project project --sample
immuknow prepare --sample --project project
immuknow run --sample --project project
project sync installs the complete embedded Typst library into
templates/lib/immuknow/. It accepts identical files and refuses a different
library unless --replace is supplied. Replacement affects only that directory;
authored notices and configuration are preserved. Linked library paths are
rejected. project check compares the complete library and validates config/parameters.yaml
without requiring fictional inputs. With --sample, it prepares and renders the
project's fictional sample in a temporary folder and removes the output afterwards.
Use run --sample to retain output and inspect its report. Warnings alone do
not fail a check; failures return a nonzero status. Check and sync print a short
text result; the existing run/prepare stdout formats are unchanged.
Project commands default to the current folder. run and prepare accept
--sample instead of a CSV and explicit notice selection. The project's
sample.json contains exactly csv and template paths relative to the project
root. Both must name existing files inside the project; absolute paths, parent
traversal and links outside the project are rejected. Use --template with --sample to
override the sample notice with a path relative to the project’s templates/ folder, or an absolute path inside the project. A collection
can include clients for whom the selected notice is inapplicable; inspect its
eligibility findings. --sample cannot be combined with an explicit CSV,
assignment file, templates directory or configuration override. --output remains relative to the current working
folder, defaulting to runs/, just as for an explicit CSV run.
Template owns the sample records, authored notices, settings and reference lists; ImmuKnow supplies the generic setup and sample-selection behavior.