@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.