@fhir-dsl/cli

CLI tool for generating type-safe FHIR TypeScript types from official HL7 specifications and Implementation Guides.

Generates the FhirSchema type used by @fhir-dsl/core for compile-time query safety.

Install

# Global install
npm install -g @fhir-dsl/cli

# Or use with npx
npx @fhir-dsl/cli generate --version r4 --out ./src/fhir

Usage

Generate types from base FHIR R4

fhir-gen generate \
  --version r4 \
  --out ./src/fhir

Generate with US Core profiles

fhir-gen generate \
  --version r4 \
  --ig [email protected] \
  --out ./src/fhir

Generate specific resources only

fhir-gen generate \
  --version r4 \
  --resources Patient,Observation,Condition \
  --out ./src/fhir

Use a local FHIR definitions directory

fhir-gen generate \
  --version r4 \
  --src ./local-fhir-definitions \
  --out ./src/fhir

Emit markdown spec for AI assistants

fhir-gen generate \
  --version r4 \
  --resources Patient,Observation \
  --include-spec \
  --out ./src/fhir

Writes a parallel spec/ tree with one markdown file per resource (and per profile when --ig is used), plus an index.md. Intended as context for AI coding assistants: they get the properties table, cardinality, terminology bindings, and search parameters in a format that's easy to embed or attach.

Commands

fhir-gen generate

Generate TypeScript types from FHIR specification.

| Flag | Required | Default | Description | |---|---|---|---| | --version <version> | Yes | r4 | FHIR version (r4, r4b, r5, r6) | | --out <dir> | Yes | - | Output directory for generated types | | --ig <packages...> | No | - | IG packages to include (e.g., [email protected]) | | --resources <list> | No | all | Comma-separated resource names to generate | | --src <path> | No | - | Local path to FHIR definitions (skips download) | | --cache <dir> | No | - | Cache directory for downloaded specs | | --expand-valuesets | No | false | Generate typed unions from FHIR ValueSet bindings | | --resolve-codesystems | No | false | Generate CodeSystem namespace objects for IntelliSense | | --include-spec | No | false | Emit markdown spec files alongside types (for AI/LLM context) |

What gets generated

out/
  index.ts           # FhirSchema type and re-exports
  primitives.ts      # FHIR primitive types (string, uri, dateTime, etc.)
  datatypes.ts       # Complex datatypes (HumanName, Address, CodeableConcept, etc.)
  registry.ts        # Resource type registry mapping
  search-params.ts   # Typed search parameters per resource
  resources/
    patient.ts       # Patient interface
    observation.ts   # Observation interface
    ...              # One file per resource
  profiles/          # (when --ig is used)
    uscore-patient-profile.ts
    uscore-vital-signs-profile.ts
    ...
  spec/              # (when --include-spec is used)
    index.md
    resources/*.md
    profiles/*.md    # (when --ig is also used)
  client.ts          # Pre-configured FhirClient type

The generated FhirSchema type wires everything together so that @fhir-dsl/core can provide full type safety for queries, includes, and profile narrowing.

License

MIT