Command Line Interface (CLI)

BRIDGE contains a very simple command line interface (CLI), currently providing two command line project scripts/executables/entry points (defined in the [project.scripts] section of the project TOML) for paperlike CRF generation in PDF and Word formats, that become available once the project is installed locally in editable mode:

pip install -e .

This will install the project locally in a package named isaric-bridge, and set up two executables for command line use:

  • generate-paperlike-crf-pdf - Generates a paperlike CRF in PDF format.

  • generate-paperlike-crf-word - Generates a paperlike CRF in Word format.

These are described in more detail below. After using the executables, it is advisable to uninstall the editable project installation using:

pip uninstall -y isaric-bridge

Note

For more information on project CLI executables see this and this.

Generate Paperlike CRF PDF

The generate-paperlike-crf-pdf generates a paperlike CRF in PDF format given a local data dictionary CSV and either an ARC version string or custom local CSVs for the paperlike form details and supplemental phrases. An optional output file path, including the filename with extension, can also be provided: if not then the output file is written to a timestamped PDF file in an output subfolder in the working directory. The executable help context can be accessed using the --help option and an excerpt is displayed below:

Options:
  --data-dictionary-csv TEXT      Path (absolute or relative) to the data
                                  dictionary CSV  [required]
  --arc-version TEXT              Optional ARC version if not using custom
                                  paperlike details and supplemental phrases,
                                  defaults to the latest (currently `1.2.2`)
  --redcap-db-name TEXT           Optional REDCap project DB name, defaults to
                                  `Generic`
  --language TEXT                 Optional PDF language, defaults to English
  --paperlike-details-csv TEXT    Optional path (absolute or relative) to a
                                  custom paperlike form details CSV
  --supplemental-phrases-csv TEXT
                                  Optional path (absolute or relative) to a
                                  custom supplemental phrases CSV
  --output-path TEXT              Optional path to write the PDF file,
                                  defaults to ./output/CRF-<redcap_db_name>-<l
                                  anguage>-<timestamp>.pdf
  --help                          Show this message and exit.

The data dictionary CSV is required, while all other arguments are optional: if custom local CSV filepaths for both the paperlike form details and supplemental phrases are provided then these are used, otherwise ARC is used with the given (or default) version.

An example run is given below to generate a Hantavirus CRF PDF in Spanish, where the default ARC version (1.2.2) is used to load the paperlike form details and supplemental phrases:

$ generate-paperlike-crf-pdf --data-dictionary-csv ~/Downloads/CCPUKHantavirus_DataDictionary_2026-05-15\(in\).csv \
                             --arc-version 1.2.2 \
                             --redcap-db-name HANTA \
                             --language Spanish
2026-05-19 07:25:24 [INFO] bridge.cli: Data dictionary /Users/smurthy/Downloads/CCPUKHantavirus_DataDictionary_2026-05-15(in).csv loaded with 586 rows.
2026-05-19 07:25:25 [INFO] bridge.cli: Paperlike CRF PDF (size 1818080 bytes) generated.
2026-05-19 07:25:25 [INFO] bridge.cli: Paperlike CRF PDF written to file output/CRF-HANTA-1.2.2-Spanish-2026-05-19-072525.pdf.

Generate Paperlike CRF Word

The generate-paperlike-crf-word executable can generate a paperlike CRF in Word format given a local data dictionary CSV and an optional output file path. If no output file path is provided then the output file is written to a timestamped Word (docx) file in an output subfolder in the working directory. The executable help context can be accessed using the --help option and an excerpt is displayed below:

Options:
  --data-dictionary-csv TEXT  Path (absolute or relative) to the data
                              dictionary CSV  [required]
  --include-descriptive-rows  Include source rows with descriptive field type, defaults to `False`
  --output-path TEXT          Optional path to write the Word file, defaults
                              to ./output/CRF-<timestamp>.docx
  --help                      Show this message and exit.

The data dictionary CSV is required, while the output file path is optional:

An example run is given below to generate an Ebola CRF Word document in English:

$ generate-paperlike-crf-word --data-dictionary-csv ~/Downloads/Ebola_DataDictionary_2026-05-18.csv \
                              --include-descriptive-rows
2026-05-19 07:25:32 [INFO] bridge.cli: Data dictionary /Users/smurthy/Downloads/Ebola_DataDictionary_2026-05-18.csv loaded with 236 rows.
2026-05-19 07:25:32 [INFO] bridge.cli: Paperlike CRF Word document (size 43593 bytes) generated, with option to include descriptive rows set to True.
2026-05-19 07:25:32 [INFO] bridge.cli: Paperlike CRF Word document written to file output/CRF-2026-05-19-072532.docx.