@records-fhir/cli

Command-line FHIR validation for local files, CI pipelines, and Records-powered data-quality workflows.

The public CLI has two modes:

• Free local mode validates FHIR JSON files without a Records server. It is designed for fast developer feedback and lightweight CI gates.
• Records mode connects to a commercial Records instance for advanced workflows: full configured validation, baselines, drift comparison, profile management, multi-server runs, and evidence exports.

Records itself is a commercial MedVertical product. The CLI is an open distribution surface for local validation and for integrating with Records.

Install

# Run without installing
npx @records-fhir/cli validate-file ./patient.json

# Project-local install
npm install --save-dev @records-fhir/cli

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

Quick Start

# Free local structural validation
records validate-file ./patient.json

# Richer local validation using @records-fhir/validator
records validate-file ./patient.json --engine

# Machine-readable CI output
records validate-file ./fhir-resources --format junit > fhir-validation.xml
records validate-file ./fhir-resources --format json

What Works Without Records

records validate-file <path> runs locally and requires no API key.

Local mode checks:

• known FHIR R4 resourceType
• required fields
• primitive type correctness
• scalar vs. array cardinality
• unknown elements
• JSON parse failures

Use --engine to run the local @records-fhir/validator engine path for a richer check without connecting to a Records API.

records validate-file ./bundle.json --engine --format json
records validate-file ./resources --format junit > test-results.xml

What Requires Records

The commands below require a Records instance and, for protected deployments, RECORDS_API_URL plus RECORDS_AUTH_TOKEN:

• records status
• records validate <server-id>
• records run list
• records run show <run-id>
• records server list
• records server add <url>
• records server status
• records baseline set <run-id>
• records baseline compare
• records profile list
• records profile install <package>
• records export <run-id|latest>

Records mode adds:

• configured 8-aspect validation
• profile and terminology validation
• server-side run history
• baselines and drift comparison
• evidence reports
• deployment and environment context

export RECORDS_API_URL="https://records.example.com/api"
export RECORDS_AUTH_TOKEN="..."

records validate 1 --environment prod --json
records baseline compare --server-id 1
records export latest --server-id 1 --output evidence.json

CI Example

- name: FHIR local validation
  run: npx @records-fhir/cli validate-file ./fhir --format junit > fhir-validation.xml

- name: Records full validation
  run: npx @records-fhir/cli validate-file ./fhir --format junit > fhir-validation.xml
  env:
    RECORDS_API_URL: ${{ secrets.RECORDS_API_URL }}
    RECORDS_AUTH_TOKEN: ${{ secrets.RECORDS_AUTH_TOKEN }}

Global Options

Option	Short	Description
--api-url <url>		Records API base URL
--server-id <id>	-s	Default FHIR server ID
--environment <env>	-e	Environment label (dev, test, staging, prod)
--json	-j	JSON output
--quiet	-q	Suppress non-essential output
--verbose	-v	Detailed output
--no-color		Disable colored output
--timeout <ms>		HTTP request timeout
--auth-token <token>		Records authentication token

Exit Codes

Code	Signal	Meaning
0	PASS	All checks passed
1	FAIL	Critical validation failure
2	WARN	Warning threshold breached
3	ERROR	CLI, configuration, or infrastructure error

Configuration

The CLI reads configuration from .recordsrc:

{
  "apiUrl": "http://localhost:3000/api",
  "defaultServerId": 1,
  "defaultEnvironment": "prod",
  "outputFormat": "human",
  "authToken": null,
  "timeout": 30000,
  "retryAttempts": 3
}

Resolution order:

1. CLI flags
2. Environment variables
3. Project .recordsrc
4. User ~/.recordsrc
5. Built-in defaults

License

Apache-2.0.