synthea-cli
0.2.0
dotnet tool install --global synthea-cli --version 0.2.0
dotnet new tool-manifest
dotnet tool install --local synthea-cli --version 0.2.0
#tool dotnet:?package=synthea-cli&version=0.2.0
nuke :add-package synthea-cli --version 0.2.0
Synthea-CLI
synthea-cli
is a cross-platform .NET 8 command-line wrapper around Synthea™ — MITRE’s open-source synthetic health-record generator.
The tool downloads the latest Synthea JAR on first use, caches it locally, and gives you a simple, typed interface plus first-class scripting and container support.
Table of Contents
Features
Feature | Details |
---|---|
Zero-install JAR | Automatically fetches the newest synthea-with-dependencies.jar from GitHub releases and verifies its SHA-256 checksum. |
Configurable cache | Stores the JAR under %LOCALAPPDATA%\synthea-cli / $XDG_CACHE_HOME/synthea-cli ; refresh anytime with --refresh . |
Friendly flags | --state OH , --city "Columbus" , --output ./data , --seed 42 , --initial-snapshot snap.json , --format FHIR map directly to Synthea flags. |
Portable | Runs on Windows, macOS, Linux, containers—wherever .NET 8 + Java 17+ are available. |
Docker image | Multi-stage Dockerfile builds a slim runtime with OpenJDK 17 and publishes the tool. |
Unit-tested | ≥ 90 % line coverage via xUnit and Coverlet; network & process calls are fully mocked. |
Quick Start
Prerequisites
- .NET 8 SDK — https://dotnet.microsoft.com/download
- Java ≥ 17 in your
PATH
(java -version
) – only required at runtime.
Install as a global tool
dotnet tool install --global synthea-cli --version 0.2.0
Run
# Generate 10 synthetic patients from Ohio into ./output using a fixed seed
synthea run --output ./output --population 10 --state OH --seed 12345
# Same, but force-refresh the cached JAR
synthea --refresh run -o ./output --population 10 --state TX --city Austin
# Advance 30 days from an initial snapshot and limit to CSV output only
synthea run -o ./output --initial-snapshot snap.json --days-forward 30 --format CSV
Short alias:
syn
works everywheresynthea
does.
Developer Guide
Clone & Build
git clone https://github.com/Kmanley1/synthea-cli.git
cd synthea-cli
dotnet restore
dotnet build
dotnet run -- run -o ./out --population 5 --state AK
Unit Tests
dotnet test --collect:"XPlat Code Coverage"
# Coverage report in ./TestResults/**/coverage.cobertura.xml
Docker
./build.sh # builds image synthea-cli:latest
./run.sh # runs CLI, mounts ./output as /data
Manual example:
docker build -t synthea-cli .
docker run --rm -v "$PWD/out":/data synthea-cli -- --state CA --population 100 # args after --
setup.sh
for CI / Codex
setup.sh
(with a wrapper at run/setup.sh
) does:
- Installs OpenJDK 17 and .NET 8 on Ubuntu runners
- Restores & publishes
Synthea.Cli
to/workspace/synthea-cli/bin
GitHub Actions example
steps:
- uses: actions/checkout@v4
- run: ./setup.sh
- run: dotnet /workspace/synthea-cli/bin/Synthea.Cli.dll -- --help
Project Layout
synthea-cli/
├─ .gitattributes # enforce LF for shell scripts
├─ .gitignore
├─ README.md
├─ synthea-cli.code-workspace # VS Code workspace file
├─ setup.sh # CI / Codex build script
├─ docs/
│ └─ Architecture.md # CLI flow diagrams & overview
├─ scripts/
│ ├─ synthea-cli-create.ps1 # helper to scaffold new CLI repo
│ └─ windows/
│ └─ install-vscode-extensions.ps1
├─ run/
│ └─ setup.sh # thin wrapper for Codex harness
├─ Synthea.Cli.sln # Visual Studio solution
├─ Synthea.Cli/ # main CLI project
│ ├─ Program.cs # System.CommandLine entry point
│ ├─ JarManager.cs # JAR download & cache helper
│ └─ Synthea.Cli.csproj
├─ Synthea.Cli.Tests/ # unit tests (xUnit)
│ ├─ CliTests.cs
│ ├─ JarManagerTests.cs
│ ├─ ProgramHandlerTests.cs
│ └─ Synthea.Cli.Tests.csproj
└─ synthea-output/ # default data output (git-ignored)
Contributing
- Fork → feature branch → PR.
- Ensure
dotnet test
passes and coverage ≥ 90 %. - If you add new dependencies, update both
.csproj
files andsetup.sh
. - Follow
dotnet format
/.editorconfig
(4-space indents, C# latest).
Issues and feature requests welcome!
License & Credits
Tool code © 2025 Ken Manley — MIT License (
LICENSE
).Synthea™ is © MITRE, Apache-2.0. This CLI downloads the official Synthea JAR but is not an official MITRE project.
Uses System.CommandLine (
2.0.0-beta4
) under MIT.
Happy generating! 🎉
Architecture
See docs/Architecture.md for diagrams of the CLI flow and a high-level overview of the Synthea JAR.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 was computed. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
This package has no dependencies.
Version | Downloads | Last Updated |
---|---|---|
0.2.0 | 77 | 5/23/2025 |
0.1.0 | 142 | 5/20/2025 |
0.0.0-aa84ec6 | 137 | 5/21/2025 |