RareLink CLI

The RareLink Command Line Interface (CLI) is a tool that allows you to interact with the RareLink framework. The CLI provides a set of commands that allow you to set up and manage the RareLink framework, as well as to interact with the data stored in the framework. The CLI is designed to be user-friendly and intuitive, and it provides a simple and efficient way to work with the RareLink framework.

Overview

1. Framework Setup (framework)
2. REDCap Setup (setup)
3. REDCap Tools (redcap)
4. FHIR configuration and pipelines (fhir)
5. Phenopacket Export (phenopackets)

1. Framework Setup (`framework`)

Commands related to setting up and managing the overall RareLink framework:

rarelink framework reset

This command clears all framework configurations and reverts it to its initial setup state.

rarelink framework status

This command provides a summary of the framework’s current status and version installed.

rarelink framework update

This command updates the framework, submodules and other components to the latest version.

2. REDCap Setup (`setup`)

Commands focused on configuring REDCap, setting up projects, and initializing API access:

rarelink setup --help

guided project setup, documentation links, admin instructions

rarelink setup redcap-project

Start here if you want to set up your local REDCap Project for RareLink!

rarelink setup keys

Configure the RareLink framework by setting up API keys and variables. This process ensures the .env file contains necessary configurations - see Set up the REDCap API for more details, functionalities, and instructions.

rarelink setup dictionary-dictionary

Upload the most current RareLink-CDM Data Dictionary to an existing REDCap project.

rarelink setup view

View the current RareLink API configuration and its location.

rarelink setup reset

Reset all RareLink configuration by wiping the .env and JSON files.

Note

The API Keys are sensitive information and should be stored securely. Do not share them with anyone outside your organisation. Within this repository the .env file and the JSON files are ignored by the .gitignore file to prevent accidental sharing of sensitive information.

3. REDCap Tools (`redcap`)

Commands for interacting with an already-configured REDCap instance, i.e. your local REDCap project.

rarelink redcap --help

The overview of all redcap-tools functionalities and commands.

Download REDCap Records Command

rarelink redcap download-records [OPTIONS]

Options:

-o, --output-dir PATH: Directory to save fetched and processed records
-r, --records TEXT: Record IDs to fetch (comma-separated, e.g. “101,102”)
-i, --instruments TEXT: Instruments/forms to fetch (comma-separated)
-l, --linkml PATH: Custom LinkML schema for validation –rarelink-cdm Use RareLink-CDM instruments and schema –filter TEXT REDCap filter logic to apply (e.g. “[age] > 30”)
--help: Show this message and exit

Description

Download REDCap records, arms, and events, process them into the RareLink-CDM schema, validate the result against a LinkML schema (either RareLink-CDM or a custom one), and save JSON outputs.

Attention

If your project is in PRODUCTION mode, the downloaded data may be sensitive. Store it only in approved, secure storage. See the REDCap “Project Status” docs for more guidance.

Hint

If your dataset includes genetic HGVS mutations, please run rarelink redcap validate-hgvs after downloading records to ensure proper phenopackets and genomics quality of the genetic data.

Validate HGVS Strings CLI Command

Command

rarelink redcap validate-hgvs [OPTIONS]

Options

Option	Description
`-i, --input-file <PATH>`	Path to the specific JSON file containing REDCap records. If omitted, the command will prompt or use the default download directory.
`-d, --input-dir <DIR>`	Directory containing REDCap records; looks for `<PROJECT_NAME>-records.json` inside.
`-v, --hgvs-variable <FIELD_NAME>`	(Repeatable) Name of an HGVS field to validate. You can specify this flag multiple times to validate custom HGVS fields. If omitted, defaults to the built-in `HGVS_VARIABLES` list.
`--help`	Show this message and exit.

Examples

Validate using the default HGVS fields:

rarelink redcap validate-hgvs

Specify a custom set of HGVS fields:

rarelink redcap validate-hgvs \\
  -i ~/Downloads/MyProject-records.json \\
  -v loinc_81290_9 \\
  -v CUSTOM_HGVS_FIELD \\
  -v OTHER_HGVS_FIELD

rarelink redcap fetch-metadata

Fetch all metadata from your current REDCap project.

rarelink redcap upload-records

Upload records to your REDCap project from JSON files stored locally.

Warning

This command will overwrite existing records with the same record_id in your REDCap project. Make sure have unique ``record_id``s or back up your data before running this command, e.g. by running rarelink redcap download-records.

4. FHIR configuration and pipelines (`fhir`)

Setup, manage, and execute the REDCap-FHIR module.

rarelink fhir --help

The overview of all FHIR functionalities and commands.

rarelink fhir setup

Configure the toFHIR pipeline for the RareLink framework.

rarelink fhir hapi-server

Set up a local HAPI FHIR server with Docker, avoiding conflicts.

rarelink fhir restart-dockers

Stop, remove, and restart all relevant Docker containers.

rarelink fhir export

Export data to the configured FHIR server using the toFHIR pipeline.

Note

For this you need your REDCap project running and API access configured. Run rarelink redcap-setup redcap-project-setup and rarelink redcap-setup redcap-api-setup start to set up a REDCap project and API access.

download-records (fetch records as JSON files)

5. Phenopacket Export (`phenopackets`)

Export data to Phenopackets using the ToPhenopacket pipeline.

rarelink phenopackets export

Exports REDCap from your configured project data to local Phenopackets.

RareLink CLI

1. Framework Setup (framework)

2. REDCap Setup (setup)

3. REDCap Tools (redcap)