Preview

Records CLI

Validate FHIR data from your terminal. Add conformance gates to your CI pipeline in under 5 minutes.

npm · Node.js 18+

Get notified at launch

The CLI is in active development and not yet published on npm.

Quick start

One command. No installation.

Terminal

npx @records-fhir/cli validate \
  --server=https://your-fhir-server.com/fhir \
  --ig=hl7.fhir.us.core \
  --ig=de.medizininformatikinitiative.kerndatensatz.person

Runs via npx — no global install required. Works on any machine with Node.js 18+.

Commands

The full DataOps loop — validate, compare, export — from your terminal.

Command	Description
`records validate <server-id>`	Run validation against a FHIR server with configured profiles
`records baseline set <run-id>`	Promote a validation run to the known-good baseline
`records baseline compare`	Compare the latest run against the current baseline (delta)
`records server list`	List all registered FHIR servers
`records server add <url>`	Register a new FHIR server endpoint
`records profile install <package>`	Install an IG package (e.g., hl7.fhir.us.core, de.basisprofil.r4)
`records export <run-id\|latest>`	Export validation results as JSON, CSV, or evidence PDF
`records status`	Show connection status and current configuration

All commands support --json for machine-readable output and --quiet for silent operation. Full Unix composability.

Exit codes

CI-native. The exit code IS the signal.

0PASS

All validations passed within configured thresholds

1FAIL

Validation errors exceed configured thresholds

2WARN

Warnings present but within acceptable bounds

3ERROR

Execution error (connection failure, invalid config)

No parsing required. if records validate 1; then deploy; fi — the exit code follows Unix convention and integrates with any CI system.

CI/CD integration

Add FHIR validation to your pipeline in under 5 minutes.

GitHub Actions

# .github/workflows/fhir-gate.yml
- name: FHIR Validation Gate
  run: npx @records-fhir/cli validate \
    --server=${{ secrets.FHIR_URL }} \
    --ig=hl7.fhir.us.core \
    --baseline=latest \
    --json

GitLab CI

# .gitlab-ci.yml
fhir-validation:
  stage: test
  image: node:20
  script:
    - npx @records-fhir/cli validate
        --server=$FHIR_URL
        --ig=hl7.fhir.us.core
        --baseline=latest

Works with GitHub Actions, GitLab CI, Azure Pipelines, Jenkins, CircleCI, Bitbucket Pipelines — any CI system that runs Node.js.

IG author workflow

Regression-test your Implementation Guide on every pull request.

Validate IG against defect corpus

records validate \
  --ig=./ \
  --corpus=./test-corpus/ \
  --baseline=latest

Point --ig=./ at your local IG directory and --corpus=./test-corpus/ at a set of test resources. Records validates your profiles against real data on every PR. Constraint regressions surface in the PR check — not in downstream implementations weeks later.

Zero install

npx @records-fhir/cli — working gate in under 5 minutes. No packages to install, no dependencies to manage.

PR-level delta

Every PR compared against test baseline. New conformance errors block the merge. Resolved errors tracked.

Defect corpus testing

Validate your IG against known-bad resources. Catch constraint regressions before they reach downstream implementers.

Deterministic output

Same inputs → same results. Exit codes follow Unix convention. JSON output for scripting and automation.

Design principles

API-first

Every CLI command maps to a documented REST API call. The CLI never bypasses the API.

Signals, not enforcement

Reports pass/warn/fail via exit codes. Never blocks, rejects, or mutates. Pipelines decide.

Deterministic

Same inputs produce same outputs. No hidden state, no interactive prompts in non-interactive mode.

Unix-composable

Output formats support piping. --json, --quiet, --no-color. Exit codes follow convention.

Try it on your own data.

We'll set up a validation gate in your pipeline — live, in 30 minutes.

CI/CD Use Case