CLI Reference

CLI Reference

Full reference for the synthea command line interface.

Usage

uv run synthea [OPTIONS] [LOCATION]...

LOCATION is an optional positional argument in the form [STATE] [CITY] (e.g., Massachusetts Boston).

Options

Option	Type	Default	Description
-p, --population	INTEGER	1	Number of patients to generate
-s, --seed	INTEGER	random	Seed for the random number generator
--clinician-seed	INTEGER	random	Separate seed for clinician generation
-g, --gender	M or F	both	Restrict to a single gender
-a, --age	TEXT	all ages	Age range, e.g. 20-40
-m, --module	TEXT	all	Run only specific module(s); repeatable
-c, --config	PATH	built-in	Path to a custom synthea.properties file
-d, --modules-dir	PATH	built-in	Path to a custom modules directory
-o, --output-dir	PATH	./output	Output directory for generated files
-r, --reference-date	TEXT	today	Reference date in YYYYMMDD format
--state	TEXT	—	State to generate patients for
--city	TEXT	—	City to generate patients for
--threads	INTEGER	1	Number of threads for parallel generation
--log-level	TEXT	info	Log verbosity: debug, info, warning, error
--only-dead	flag	off	Only emit deceased patients
--keep-patients	PATH	—	File with patient IDs to preserve across runs
--overflow	INTEGER	—	Extra overflow population size
--graphviz	TEXT	—	Write a Graphviz .dot file for the named module
--list-modules	flag	—	Print all available module names and exit
--version	flag	—	Show version and exit
--help	flag	—	Show help and exit

Examples

Basic generation

# 100 patients, default settings
uv run synthea -p 100

# 1 000 patients in a specific location
uv run synthea -p 1000 Massachusetts Boston

# Reproducible run (same seed → same patients)
uv run synthea -s 12345 -p 50 --state California

Demographics filters

# Only female patients aged 25–35, 4 threads
uv run synthea -p 100 -g F -a 25-35 --threads 4

# Pediatric population (0–17)
uv run synthea -p 200 -a 0-17 --state Texas

# Elderly cohort only (65+), deceased included
uv run synthea -p 500 -a 65-99 --only-dead

Module selection

# Run only the diabetes and hypertension modules
uv run synthea -p 50 -m diabetes -m hypertension

# Visualise a module's state machine
uv run synthea --graphviz atrial_fibrillation
dot -Tpng atrial_fibrillation.dot -o atrial_fibrillation.png

Custom configuration

# Use a custom properties file
uv run synthea -c ./my-config.properties -p 200

# Write output to a specific directory
uv run synthea -p 100 -o /data/synthetic --state New\ York --city Albany

Debugging

# Verbose debug output
uv run synthea -p 5 --log-level debug

# List all 231 available modules
uv run synthea --list-modules

# Use an isolated UV environment (no caching)
uv run --isolated synthea -p 10

Environment Variables

Variable	Description
SYNTHEA_CONFIG	Default path to synthea.properties (overridden by -c)
SYNTHEA_OUTPUT	Default output directory (overridden by -o)
SYNTHEA_MODULES	Default modules directory (overridden by -d)

Exit Codes

Code	Meaning
0	Success
1	General error (bad options, missing files)
2	Generation failed (check --log-level debug)