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

• Getting Started
• Command Reference
• Examples

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.