/ Development View source
Projects/ImmuKnow/Command Reference
Development documentation from main. Features may not be released. Read the current release.

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.