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​

Download the CLI via https://github.com/HasteHealth/HasteHealth by downloading precompiled binaries for your OS, or build locally from source via:

cd backend
cargo install --path . --locked

Once installed, you can use the binary as follows:

haste-health --help

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, navigate to resources/ClientApplication → New and set the grant type to authorization_code, response type to code, add the redirect URI above, and set the same scopes.

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 (found in your Admin App API Settings/FHIR)
  • OIDC discovery URI: Found in your Admin App under Settings/OpenID Connect
  • 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.

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/r4"
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