Skip to main content

Setting Up the CLI

The Haste Health CLI is a powerful command-line tool for interacting with FHIR servers, managing configurations, running tests, and automating workflows.

Installation​

Install the CLI globally with npm (requires Node.js 18 or later):

npm install -g haste-health

To try it without installing, run it with npx:

npx haste-health --help

Builds exist for Linux (x64 and arm64) and macOS on Apple Silicon, and npm installs only the one for your machine. The Linux builds are static, so they run on any distribution. On Windows, run the CLI inside WSL.

The same haste-health binary also runs the server and the worker.

Without Node.js​

Each GitHub release has the binaries attached, or you can build from source:

cd backend
cargo install --path . --locked

Quick Start​

After installation, verify the CLI is working:

haste-health --help

This will display all available commands and options.

Shell Completion​

The CLI can complete what you type when you press Tab: commands, options, FHIR resource types (haste-health api read Pat → Patient) and the names of your saved profiles (haste-health profile use). Completions come from the installed CLI itself, so new commands and newly created profiles show up without any further setup.

Your shell only asks a program for completions once it has been told to, so enable it once by adding a line to your shell's startup file. haste-health must be on your PATH (an npm install -g or binary install); completion doesn't apply to npx haste-health or cargo run.

Add to ~/.zshrc:

source <(COMPLETE=zsh haste-health)

The line uses zsh's completion system, so it must come after compinit. Frameworks such as Oh My Zsh load it for you; with a plain ~/.zshrc, put these lines before it:

autoload -Uz compinit
compinit

Open a new terminal (or source the startup file) and try haste-health api <Tab>.

The startup line prints a small shell function that calls the CLI on every Tab press, and the shell loads it. Because it runs each time a shell starts, it always points at the CLI you have installed now, including after an upgrade or a reinstall.

Initial Setup​

The CLI authenticates as a human user via the browser, using the authorization_code + PKCE flow. You log in once with haste-health login and the CLI stores the resulting tokens locally, refreshing them as needed.

1. Register a Client Application​

Register a public ClientApplication for the CLI to use. You can do this with the CLI itself (via an existing authenticated profile or the server admin binary), or through the Admin App:

haste-health admin client create \
--id cli \
--tenant [tenant] \
--project [project] \
--grant-type authorization-code \
--redirect-uri http://127.0.0.1:8976/callback \
--scope "openid profile fhirUser offline_access user/*.*"

This creates a public (no secret) ClientApplication with ID cli supporting the authorization_code and refresh_token grants. Because it's a public client used by a signed-in human, it does not need an AccessPolicyV2 of its own — access is governed by whichever policy is attached to the user who logs in.

The --scope above is what haste-health profile create defaults to as well; adjust it to whatever scopes the logged-in users should be able to request. See the Scopes documentation for the full syntax.

To register it through the Admin App instead, open your project's console, pick ClientApplication from the sidebar's resource types, click New ClientApplication, and set the grant type to authorization_code, response type to code, add the redirect URI above, and set the same scopes. Save with Actions → Create.

2. Configure Your First Profile​

Before using the CLI, you need to configure at least one profile (FHIR server):

haste-health profile create

This prompts you for:

  • Profile name: A unique identifier for this configuration
  • FHIR R4 Server URL: The FHIR R4 endpoint URL (in the Admin App under Settings → FHIR and OIDC Endpoints, as FHIR R4 Base URL)
  • Auth Mode: Press Enter to accept the default, authorization-code
  • OIDC discovery URI: Same card, as OIDC Discovery URL
  • Client ID: The ClientApplication ID from step 1 (e.g. cli)
  • Loopback Redirect URI: Press Enter to accept the default, http://127.0.0.1:8976/callback
  • OAuth Scope: Press Enter to accept the default, or enter whatever scopes you registered the client with in step 1 (see the Scopes documentation)

Every prompt can be skipped by passing its value as an option instead, which is how you'd create a profile from a script:

haste-health profile create local \
--r4-url https://api.haste.health/w/[tenant]/[project]/api/v1/fhir/r4 \
--auth-mode authorization-code \
--discovery-uri https://api.haste.health/.well-known/openid-configuration/w/[tenant]/[project] \
--client-id cli

Outside a terminal, options with a default (--redirect-uri, --scope) fall back to it, and any other missing option is an error. Run haste-health profile create --help for the options of the other auth modes (client-credentials, basic-auth and none).

The new profile becomes the active one, which other commands use. To manage profiles:

haste-health profile list # all profiles; * marks the active one
haste-health profile show [name] # a profile's settings, never its secrets
haste-health profile use [name] # switch the active profile
haste-health profile delete [name] # delete a profile and its stored secrets

Leave out the name to pick from a list.

3. Log In​

haste-health login

This opens your browser to sign in against the active profile's OIDC provider, then stores the resulting access/refresh tokens in the CLI's secrets file.

Without a browser (over SSH, for example), run haste-health login --no-browser and open the printed URL in a browser that can reach the loopback redirect URI. Over SSH, forward its port.

Configuration File Location​

The CLI stores configuration at:

~/.haste_health/config.toml

You can manually edit this file if needed. Example structure:

active_profile = "LOCAL_CLIENT"

[[profiles]]
name = "LOCAL_CLIENT"
r4_url = "https://api.haste.health/w/[tenant]/[project]/api/v1/fhir"
oidc_discovery_uri = "https://api.haste.health/.well-known/openid-configuration/w/[tenant]/[project]"

[profiles.auth.AuthorizationCode]
client_id = "cli"
redirect_uri = "http://127.0.0.1:8976/callback"
scope = "openid profile fhirUser offline_access user/*.*"

Secrets are kept out of this file. Client secrets, passwords and the tokens from haste-health login are stored per profile in ~/.haste_health/.secrets.toml, so config.toml is safe to inspect or share.

API Commands​

The CLI provides commands for all FHIR REST operations.

You can find a list of available API commands by running:

haste-health api --help

Implementation Guides​

Install FHIR packages such as US Core into the active profile's project, with the packages they depend on:

haste-health package install hl7.fhir.us.core@6.1.0
haste-health package list
haste-health package uninstall hl7.fhir.us.core

install also takes a .tgz or a package folder. See Implementation Guides.

Documentation​

External Resources​

Support​

If you encounter issues:

  1. Check the CLI help: haste-health --help
  2. Review command-specific help: haste-health api --help
  3. Check the GitHub Issues
  4. Verify your configuration: haste-health profile show