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.

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 config create-profile 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 config create-profile

This interactive command will prompt 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)
  • OIDC discovery URI: Same card, as OIDC Discovery URL
  • Client ID: The ClientApplication ID from step 1 (e.g. cli)
  • Auth Mode: Press Enter to accept the default, authorization-code
  • 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)

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

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/*.*"

Tokens obtained via haste-health login are cached under profiles.tokens in this same file.

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

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 config show-profile