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.
- zsh
- bash
- fish
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
Add to ~/.bashrc (on macOS, ~/.bash_profile):
eval "$(COMPLETE=bash haste-health)"
Use eval rather than source <(...): the bash 3.2 that ships with macOS ignores source on a process substitution.
Add to ~/.config/fish/config.fish:
COMPLETE=fish haste-health | source
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
ClientApplicationID 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
- FHIR API Documentation - FHIR API reference
- Authentication - Auth setup guide
External Resources
- FHIR Specification - FHIR standard
- FHIR Operations - FHIR HTTP API
- FHIR Search - Search documentation
Support
If you encounter issues:
- Check the CLI help:
haste-health --help - Review command-specific help:
haste-health api --help - Check the GitHub Issues
- Verify your configuration:
haste-health profile show