Command Line Interface (CLI)¶

The package installs an imednet command that wraps common SDK features. The CLI reads authentication details from environment variables. See Configuration for the full list and details on using an .env file.

iMednet SDK Command Line Interface

usage: imednet [-h] [--high-contrast]
               {studies,queries,variables,record-revisions,sites,export,subjects,intervals,jobs,records,validate-package-consumption,validate-diagrams,aggregate-verification,validate-docs,typecheck-docs,ci-plan,check-root-files,post-smoke-record,tighten-dependencies,build-docs,subject-data,workflows,dashboard}
               ...

Positional Arguments¶

command: Possible choices: studies, queries, variables, record-revisions, sites, export, subjects, intervals, jobs, records, validate-package-consumption, validate-diagrams, aggregate-verification, validate-docs, typecheck-docs, ci-plan, check-root-files, post-smoke-record, tighten-dependencies, build-docs, subject-data, workflows, dashboard

Named Arguments¶

--high-contrast

Enable high-contrast mode for accessibility.

Default: False

Sub-commands¶

studies¶

Manage studies.

imednet studies [-h] {list} ...

Positional Arguments¶

command: Possible choices: list

Sub-commands¶

list¶

List all items of type studies.

imednet studies list [-h]

queries¶

Manage queries.

imednet queries [-h] {list} ...

Positional Arguments¶

command: Possible choices: list

Sub-commands¶

list¶

List all items of type queries.

imednet queries list [-h] study_key

Positional Arguments¶

study_key: The key identifying the study.

variables¶

Manage variables.

imednet variables [-h] {list} ...

Positional Arguments¶

command: Possible choices: list

Sub-commands¶

list¶

List all items of type variables.

imednet variables list [-h] study_key

Positional Arguments¶

study_key: The key identifying the study.

record-revisions¶

Manage record revisions.

imednet record-revisions [-h] {list} ...

Positional Arguments¶

command: Possible choices: list

Sub-commands¶

list¶

List all items of type record revisions.

imednet record-revisions list [-h] study_key

Positional Arguments¶

study_key: The key identifying the study.

sites¶

Manage sites.

imednet sites [-h] {list} ...

Positional Arguments¶

command: Possible choices: list

Sub-commands¶

list¶

List all items of type sites.

imednet sites list [-h] study_key

Positional Arguments¶

study_key: The key identifying the study.

export¶

Export study data to various formats.

imednet export [-h]
               {parquet,csv,excel,json,duckdb,sql,mongodb,neo4j,snowflake} ...

Positional Arguments¶

command: Possible choices: parquet, csv, excel, json, duckdb, sql, mongodb, neo4j, snowflake

Sub-commands¶

parquet¶

Export study records to a Parquet file.

imednet export parquet [-h] study_key path

Positional Arguments¶

study_key: The key identifying the study.
path: Destination Parquet file.

csv¶

Export study records to a CSV file.

imednet export csv [-h] study_key path

Positional Arguments¶

study_key: The key identifying the study.
path: Destination CSV file.

excel¶

Export study records to an Excel workbook.

imednet export excel [-h] study_key path

Positional Arguments¶

study_key: The key identifying the study.
path: Destination Excel workbook.

json¶

Export study records to a JSON file.

imednet export json [-h] study_key path

Positional Arguments¶

study_key: The key identifying the study.
path: Destination JSON file.

duckdb¶

Export study records to a DuckDB table.

imednet export duckdb [-h] [--vars VARS_] [--forms FORMS] [--use-labels]
                      study_key table_name db_path

Positional Arguments¶

study_key: The key identifying the study.
table_name: Destination DuckDB table name.
db_path: Path to DuckDB database file.

Named Arguments¶

--vars

Comma-separated list of variable names to include.

--forms

Comma-separated list of form IDs to include.

--use-labels

Use variable labels instead of names as column headers.

Default: False

sql¶

Export study records to a SQL table.

imednet export sql [-h] [--single-table] [--long-format] [--vars VARS_]
                   [--forms FORMS]
                   study_key table connection_string

Positional Arguments¶

study_key: The key identifying the study.
table: Destination table name.
connection_string: Database connection string.

Named Arguments¶

--single-table

Store all records in a single table even when using SQLite.

Default: False

--long-format

Export normalized long-format table.

Default: False

--vars

Comma-separated list of variable names to include.

--forms

Comma-separated list of form IDs to include.

mongodb¶

Export study records to MongoDB document envelopes.

imednet export mongodb [-h] [--batch-size BATCH_SIZE] [--insert-only]
                       study_key uri database collection

Positional Arguments¶

study_key: The key identifying the study.
uri: MongoDB connection URI.
database: MongoDB database name.
collection: MongoDB collection name.

Named Arguments¶

--batch-size

Records per batch.

Default: 500

--insert-only

Use insert-only mode instead of idempotent upserts.

Default: True

neo4j¶

Export study records to Neo4j nodes and relationships.

imednet export neo4j [-h] [--database DATABASE] [--batch-size BATCH_SIZE]
                     [--create-only]
                     study_key uri username password

Positional Arguments¶

study_key: The key identifying the study.
uri: Neo4j URI.
username: Neo4j username.
password: Neo4j password.

Named Arguments¶

--database

Neo4j database name.

Default: 'neo4j'

--batch-size

Records per batch.

Default: 500

--create-only

Use CREATE-only writes instead of idempotent MERGE.

Default: True

snowflake¶

Export study records to Snowflake using staged Parquet + COPY INTO.

imednet export snowflake [-h] [--stage-prefix STAGE_PREFIX]
                         [--local-staging-dir LOCAL_STAGING_DIR]
                         [--manifest-path MANIFEST_PATH]
                         [--batch-size BATCH_SIZE] [--force-reload]
                         study_key account user password database schema
                         warehouse stage table

Positional Arguments¶

study_key: The key identifying the study.
account: Snowflake account identifier.
user: Snowflake username.
password: Snowflake password.
database: Target Snowflake database.
schema: Target Snowflake schema.
warehouse: Snowflake warehouse.
stage: Internal stage name.
table: Target table name.

Named Arguments¶

--stage-prefix

Path prefix in stage.

Default: 'imednet'

--local-staging-dir

Local directory for staged Parquet files.

--manifest-path

Optional JSONL manifest output path.

--batch-size

Records per batch.

Default: 500

--force-reload

Force reloading already-loaded files.

Default: True

subjects¶

Manage subjects within a study.

imednet subjects [-h] {list} ...

Positional Arguments¶

command: Possible choices: list

Sub-commands¶

list¶

List subjects for a specific study.

imednet subjects list [-h] [-f SUBJECT_FILTER] study_key

Positional Arguments¶

study_key: The key identifying the study.

Named Arguments¶

-f, --filter: Filter criteria (e.g., ‘subject_status=Screened’). Repeat for multiple filters.

intervals¶

Manage intervals.

imednet intervals [-h] {list} ...

Positional Arguments¶

command: Possible choices: list

Sub-commands¶

list¶

List all items of type intervals.

imednet intervals list [-h] study_key

Positional Arguments¶

study_key: The key identifying the study.

jobs¶

Manage background jobs.

imednet jobs [-h] {status,wait} ...

Positional Arguments¶

command: Possible choices: status, wait

Sub-commands¶

status¶

Fetch a job’s current status.

imednet jobs status [-h] study_key batch_id

Positional Arguments¶

study_key: The key identifying the study.
batch_id: Job batch ID.

wait¶

Wait for a job to reach a terminal state.

imednet jobs wait [-h] [--interval INTERVAL] [--timeout TIMEOUT]
                  study_key batch_id

Positional Arguments¶

study_key: The key identifying the study.
batch_id: Job batch ID.

Named Arguments¶

--interval

Polling interval in seconds.

Default: 5

--timeout

Maximum time to wait.

Default: 300

records¶

Manage records within a study.

imednet records [-h] {list} ...

Positional Arguments¶

command: Possible choices: list

Sub-commands¶

list¶

List records for a study.

imednet records list [-h] [-o OUTPUT] study_key

Positional Arguments¶

study_key: The key identifying the study.

Named Arguments¶

-o, --output: Save records to the given format (json or csv)

validate-package-consumption¶

Run validate_package_consumption script.

imednet validate-package-consumption [-h] ...

Positional Arguments¶

args: Arguments passed to the script.

validate-diagrams¶

Run validate_diagrams script.

imednet validate-diagrams [-h] ...

Positional Arguments¶

args: Arguments passed to the script.

aggregate-verification¶

Run aggregate_verification script.

imednet aggregate-verification [-h] ...

Positional Arguments¶

args: Arguments passed to the script.

validate-docs¶

Run validate_docs script.

imednet validate-docs [-h] ...

Positional Arguments¶

args: Arguments passed to the script.

typecheck-docs¶

Run typecheck_docs script.

imednet typecheck-docs [-h] ...

Positional Arguments¶

args: Arguments passed to the script.

ci-plan¶

Run ci_plan script.

imednet ci-plan [-h] ...

Positional Arguments¶

args: Arguments passed to the script.

check-root-files¶

Run check_root_files script.

imednet check-root-files [-h] ...

Positional Arguments¶

args: Arguments passed to the script.

post-smoke-record¶

Run post_smoke_record script.

imednet post-smoke-record [-h] ...

Positional Arguments¶

args: Arguments passed to the script.

tighten-dependencies¶

Run tighten_dependencies script.

imednet tighten-dependencies [-h] ...

Positional Arguments¶

args: Arguments passed to the script.

build-docs¶

Run build_docs script.

imednet build-docs [-h] ...

Positional Arguments¶

args: Arguments passed to the script.

subject-data¶

Retrieve all data for a single subject.

imednet subject-data [-h] study_key subject_key

Positional Arguments¶

study_key: The key identifying the study.
subject_key: The key identifying the subject.

workflows¶

Execute common data workflows.

imednet workflows [-h] {extract-records,sync-worker,state} ...

Positional Arguments¶

wf_command: Possible choices: extract-records, sync-worker, state

Sub-commands¶

extract-records¶

Extract records based on criteria spanning subjects, visits, and records.

imednet workflows extract-records [-h] [--record-filter RECORD_FILTER]
                                  [--subject-filter SUBJECT_FILTER]
                                  [--visit-filter VISIT_FILTER]
                                  study_key

Positional Arguments¶

study_key: The key identifying the study.

Named Arguments¶

--record-filter: Record filter criteria (e.g., ‘form_key=DEMO’). Repeat for multiple filters.
--subject-filter: Subject filter criteria (e.g., ‘subject_status=Screened’). Repeat for multiple filters.
--visit-filter: Visit filter criteria (e.g., ‘visit_key=SCREENING’). Repeat for multiple filters.

sync-worker¶

Run an idempotent background cache refresh worker.

imednet workflows sync-worker [-h] [--interval INTERVAL] [--once] study_key

Positional Arguments¶

study_key: The key identifying the study.

Named Arguments¶

--interval

Polling interval in seconds.

Default: 900

--once

Run a single sync cycle and exit.

Default: False

state¶

Manage high-water mark execution ledger state.

imednet workflows state [-h] {show,set,reset} ...

Positional Arguments¶

state_command: Possible choices: show, set, reset

Sub-commands¶

show¶

Show the current high-water mark records and stream metadata.

imednet workflows state show [-h] [-l LEDGER_PATH] [-s STUDY_KEY]

Named Arguments¶

-l, --ledger-path

Path to the pipeline ledger JSON file.

Default: '/var/lib/imednet/pipeline_ledger.json'

-s, --study-key

Filter the ledger by a specific study key.

set¶

Manually set a high-water mark timestamp for a study and stream.

imednet workflows state set [-h] -s STUDY_KEY -m STREAM -t TIMESTAMP
                            [-r RECORDS_PROCESSED] [-l LEDGER_PATH]

Named Arguments¶

-s, --study-key

The study key.

-m, --stream

The stream name.

-t, --timestamp

The ISO-8601 timestamp (UTC).

-r, --records-processed

Number of records processed.

Default: 0

-l, --ledger-path

Path to the pipeline ledger JSON file.

Default: '/var/lib/imednet/pipeline_ledger.json'

reset¶

Reset (clear) high-water mark state for a study/stream.

imednet workflows state reset [-h] -s STUDY_KEY [-m STREAM] [-l LEDGER_PATH]

Named Arguments¶

-s, --study-key

The study key.

-m, --stream

The stream name. If omitted, all streams for the study will be reset.

-l, --ledger-path

Path to the pipeline ledger JSON file.

Default: '/var/lib/imednet/pipeline_ledger.json'

dashboard¶

Launch the iMednet Streamlit reporting dashboard.

imednet dashboard [-h] [-p PORT] [--no-browser]

Named Arguments¶

-p, --port

Port to run the dashboard on.

Default: 8501

--no-browser

Suppress automatic browser launch.

Default: False