Command line

This page is generated from the help text in the source when the site is built, so it is what refhir --help prints. Every flag also has a place in the configuration file, and a flag overrides the file. Configuration explains each flag in a table, and Environment variables lists the variables the server reads.

refhir

refhir [--config path] [--sqlite path | --memory | --postgres url] [--bind 127.0.0.1:8080]
[--package dir|name@version] [--references strict|fhir] [--smart]
[--public-url url] [--smart-patient id] [--smart-encounter id]
[--smart-fhir-user Resource/id] [--smart-dcr-token token] [--update-as-create]
[--smart-confidential-secret secret]
[--oidc-issuer url --oidc-client-id id] [--smart-demo-login]
[--export-dir path] [--terminology url] [--trace-engine] [--sdc-archiver]
[--role primary|standby|replica] [--standby] [--primary-url url] [--db-pool n]
refhir migrate --status | --dry-run   (schema versions; see refhir migrate --help)
refhir --version | -V                 (print the version and exit)

Config file (optional): refhir.toml in the working directory, /etc/refhir/refhir.toml,
or REFHIR_CONFIG. CLI flags override the file. See refhir.toml.example.

Default database is refhir.sqlite. --memory uses SQLite in RAM and
leaves no file. [fhir].version selects release defaults (r4: hl7.fhir.r4.core@4.0.1
and hl7.fhir.uv.sdc@4.0.0) downloaded from [conformance].package_registry (default
packages.fhir.org; a mirror URL or s3://bucket/prefix also works), cached and skipped
when already in the database. The server ships no packages and does not start if
that source is unreachable on a first start. --package may be repeated to add IGs (directory, .tgz,
or name@version). --references defaults to strict.
--smart enables SMART App Launch 2.2. --public-url is required when
--smart is used with a non-loopback --bind. Generated DCR and confidential
secrets print once to stderr in a terminal and are never written to logs.
--sdc-archiver stores QuestionnaireResponse without allowing a later read.

Rate limits, quotas, the audit trail and the request log are set in the config file
([rate_limit], [quota], [audit], [request_log], [metering]). Usage, the request log and
the audit trail are on by default; nothing is limited until a limit is configured.
GET /_audit, /_usage and /_requests read them back (system/AuditEvent.read with --smart).

Several processes on one database: exactly one primary writes and holds a lease on the
database. --standby (--role standby) waits for that lease and takes over when the
primary is gone. --role replica reads what the primary publishes and sends writes, and
reads that need a newer snapshot, to --primary-url. /healthz is 200 when a process can
take traffic and 503 when it cannot.

Probes, open under --smart: GET /livez is 200 while the process is up (use it for
liveness; /healthz is 503 on a standby). GET /readyz is 200 when startup is over and the
database answers, and 503 {"status":"starting"|"unavailable","reason":...} otherwise.

--db-pool sets the most Postgres connections (default 8), or, on SQLite, the read
connections next to the one writer (default 4).

refhir migrate

refhir migrate --status | --dry-run [--config path] [--sqlite path | --postgres url]

Reports the schema version of the database the server would open (the same file, environment
and flags as `refhir`) and what starting this build would do to it. Nothing is changed, and a
SQLite file that does not exist is not created.

  --status    the versions recorded in the database, and which this build would apply
  --dry-run   the same, plus the SQL that would run

The server applies pending migrations itself at startup, in one transaction. Migrations are
not reversible: take a backup first.

Exit codes: 0 this build would start; 1 it would refuse to start (for example the database was
migrated by a newer ReFHIR); 2 the database could not be read, or the arguments were wrong.

See Schema migrations for what the exit codes mean in an upgrade.