Package Exports

fhir-runtime-cli
fhir-runtime-cli/package.json

Readme

fhir-runtime-cli

A powerful command-line tool for working with FHIR R4 resources. Validate, inspect, query, convert, and analyze FHIR data without writing code.

Built on fhir-runtime v0.8.0 + fhir-definition v0.4.0.

Features

✅ Validate FHIR resources against StructureDefinitions
🔍 Query with FHIRPath expressions
📊 Inspect resource structure and fields
📦 Bundle analysis and manipulation
🔄 Convert between JSON and YAML formats
📋 Profile management and snapshot generation
📚 Package loading for FHIR IG support
🛠️ Compose resources from templates
🔎 Search parameter extraction and validation

Installation

# Install globally
npm install -g fhir-runtime-cli

# Or use directly with npx
npx fhir-runtime-cli --help

# Verify installation
fhir-runtime --version

Quick Start

# Validate a FHIR resource
fhir-runtime validate patient.json

# Query with FHIRPath
fhir-runtime fhirpath "Patient.name.given" patient.json

# Inspect resource structure
fhir-runtime inspect patient.json --tree

# Analyze a Bundle
fhir-runtime bundle analyze bundle.json

# Convert JSON to YAML
fhir-runtime convert patient.json patient.yaml

# View a Profile
fhir-runtime profile show http://hl7.org/fhir/StructureDefinition/Patient

Commands

`fhir-runtime validate <file>`

Validate a FHIR R4 resource against its StructureDefinition.

fhir-runtime validate patient.json
fhir-runtime validate patient.json --json
fhir-runtime validate patient.json --strict

Option	Description
`--json`	Output in JSON format
`--strict`	Treat warnings as errors (exit code 1)

`fhir-runtime fhirpath <expression> <file>`

Evaluate a FHIRPath expression against a FHIR resource.

fhir-runtime fhirpath "Patient.name.given" patient.json
fhir-runtime fhirpath "Patient.gender = 'male'" patient.json --boolean
fhir-runtime fhirpath "Patient.name.family" patient.json --json

Option	Description
`--boolean`	Evaluate as boolean expression
`--json`	Output in JSON format

`fhir-runtime inspect <file>`

Display the structure and fields of a FHIR resource.

fhir-runtime inspect patient.json
fhir-runtime inspect patient.json --tree
fhir-runtime inspect patient.json --json

Option	Description
`--tree`	Display as tree structure
`--json`	Output in JSON format

`fhir-runtime bundle <subcommand>`

Analyze and manipulate FHIR Bundles.

`fhir-runtime bundle analyze <file>`

fhir-runtime bundle analyze bundle.json
fhir-runtime bundle analyze bundle.json --json
fhir-runtime bundle analyze bundle.json --verbose

Option	Description
`--json`	Output in JSON format
`--verbose`	Show each entry's id and resourceType

`fhir-runtime bundle extract <file>`

fhir-runtime bundle extract bundle.json --type Patient
fhir-runtime bundle extract bundle.json --type Patient --output ./out/
fhir-runtime bundle extract bundle.json --json

Option	Description
`--type <resourceType>`	Filter by resource type
`--output <dir>`	Write each resource to a separate file
`--json`	Output as JSON array

`fhir-runtime bundle refs <file>`

fhir-runtime bundle refs bundle.json
fhir-runtime bundle refs bundle.json --json
fhir-runtime bundle refs bundle.json --type literal

Option	Description
`--json`	Output in JSON format
`--type <refType>`	Filter by reference type (literal/absolute/contained/logical)

`fhir-runtime convert <input> <output>`

Convert FHIR resources between JSON and YAML formats.

fhir-runtime convert patient.json patient.yaml
fhir-runtime convert patient.yaml patient.json
fhir-runtime convert patient.json patient.out --from json --to yaml

Option	Description
`--from <format>`	Source format (json/yaml, auto-detected)
`--to <format>`	Target format (json/yaml)

`fhir-runtime profile <subcommand>`

View and manipulate FHIR StructureDefinition profiles.

`fhir-runtime profile show <url-or-file>`

fhir-runtime profile show http://hl7.org/fhir/StructureDefinition/Patient
fhir-runtime profile show my-profile.json
fhir-runtime profile show my-profile.json --full
fhir-runtime profile show my-profile.json --json

Option	Description
`--full`	Show full metadata
`--json`	Output in JSON format

`fhir-runtime profile snapshot <file>`

fhir-runtime profile snapshot my-profile.json
fhir-runtime profile snapshot my-profile.json --output snapshot.json

Option	Description
`--output <file>`	Write output to file
`--canonical`	Also output CanonicalProfile representation

`fhir-runtime profile validate <file>`

fhir-runtime profile validate my-profile.json
fhir-runtime profile validate my-profile.json --json

Option	Description
`--json`	Output in JSON format

`fhir-runtime package <subcommand>`

Manage FHIR IG packages.

`fhir-runtime package load <path>`

fhir-runtime package load ./hl7.fhir.us.core/
fhir-runtime package load ./hl7.fhir.us.core-9.0.0.tgz

Option	Description
`--json`	Output in JSON format

`fhir-runtime package list`

fhir-runtime package list
fhir-runtime package list --verbose
fhir-runtime package list --json

Option	Description
`--json`	Output in JSON format
`--verbose`	Show profile URLs for each package

`fhir-runtime package resolve <url>`

fhir-runtime package resolve http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient
fhir-runtime package resolve <url> --show
fhir-runtime package resolve <url> --json

Option	Description
`--json`	Output in JSON format
`--show`	Show the full StructureDefinition content

`fhir-runtime compose <template>`

Compose a normalized FHIR R4 JSON resource from a YAML or JSON template.

fhir-runtime compose patient-template.yaml
fhir-runtime compose patient-template.yaml --validate
fhir-runtime compose patient-template.yaml --output patient.json

Option	Description
`--validate`	Validate the composed resource
`--output <file>`	Write output to file

`fhir-runtime search <subcommand>`

FHIR SearchParameter tools.

`fhir-runtime search extract <resource-file> <search-params-file>`

fhir-runtime search extract patient.json search-param-name.json
fhir-runtime search extract patient.json search-param-name.json --json

Option	Description
`--param <code>`	Only extract the specified parameter
`--json`	Output in JSON format

`fhir-runtime search validate <file>`

fhir-runtime search validate search-param-name.json
fhir-runtime search validate search-param-name.json --json

Option	Description
`--json`	Output in JSON format

`fhir-runtime search capability <profile-files...>`

fhir-runtime search capability my-patient-profile.json
fhir-runtime search capability profile1.json profile2.json --search-params sp-bundle.json

Option	Description
`--search-params <file>`	SearchParameter Bundle to associate
`--mode <mode>`	REST mode: server or client (default: server)
`--output <file>`	Write output to file

Exit Codes

Code	Meaning
`0`	Success
`1`	Validation failure
`2`	File error (not found, unreadable, bad format)
`3`	Input error (bad arguments/options)
`4`	Internal error

Supported Formats

JSON (.json)
YAML (.yaml, .yml)

All commands that accept files support both JSON and YAML input.

Documentation

Requirements

Node.js >= 18
fhir-runtime >= 0.8.0
fhir-definition >= 0.4.0

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

# Clone the repository
git clone https://github.com/YOUR_USERNAME/fhir-runtime-cli.git
cd fhir-runtime-cli

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

Running Tests

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run in watch mode
npx vitest

Publishing

This package is published to npm. To publish a new version:

# Update version in package.json
npm version patch  # or minor, or major

# Build and test
npm run prepublishOnly

# Publish to npm
npm publish

License

MIT © Fangjun

Acknowledgments

Built on fhir-runtime by Nicholas Gasior.