HealOS CLI

healos is the HealOS command line. It talks to the HealOS API, so every command uses the same API keys, scopes and rate limits as your own integration. It works the same for people at a terminal and for scripts or AI agents (--json).

Install

Requires Node.js 18 or later (or Bun).

npm install -g @healos/cli

bun add -g @healos/cli

pnpm add -g @healos/cli

yarn global add @healos/cli

Or run it without installing:

npx @healos/cli@latest whoami

bunx @healos/cli@latest whoami

Check the install with healos --version.

Standalone binary

Each release can also ship a single healos binary that needs no Node.js, for macOS (Apple silicon and Intel), Linux x64 and Windows x64, with a SHA256SUMS file. Check a download before you run it:

sha256sum --check --ignore-missing SHA256SUMS   # macOS: shasum -a 256 --check --ignore-missing SHA256SUMS
chmod +x healos-darwin-arm64 && mv healos-darwin-arm64 /usr/local/bin/healos

The binaries are not yet code-signed. On macOS, clear the download quarantine flag (xattr -d com.apple.quarantine /usr/local/bin/healos) or install from npm instead.

Updating

healos update tells you whether a newer version is out and how to upgrade the copy you have (the npm command, or the release binary to download). It asks the public npm registry and sends no API key. It does not replace the binary itself. With npm, npm install -g @healos/cli@latest updates in place.

healos login

This opens HealOS in your browser. Approve the request and the CLI saves a new API key on this machine. The key is labeled CLI · <computer> · <date> in Settings → API keys and expires after 90 days. The key is read-only by default. The approval page shows exactly which scopes it asks for. To let the CLI create or change data, ask for more:

healos login --scopes all                          # every scope
healos login --scopes patients:read,notes:write    # only these scopes

Only organization admins can approve a CLI sign-in, because API keys are organization-wide. If you are a member, ask an admin to create a key for you in Settings → API keys, then pass it on standard input:

pbpaste | healos login --api-key -

--api-key hlsk_... also works, but the CLI warns you: a key typed on the command line ends up in your shell history.

healos whoami    # user, organization, scopes and key expiry
healos logout    # removes the key from this machine

logout does not revoke the key. Revoke it in Settings → API keys. Where the key is stored: the macOS Keychain when available, otherwise ~/.config/healos/credentials.json, readable only by you. The CLI refuses to use a credentials file that other users can read. Several accounts: add --profile <name> to login and to any command, for example healos login --profile clinic-b.

Commands

Every command has --help, for example healos notes create --help. Lists take --page, --limit and --all (every page).

Patients and documents

Command	What it does
`healos patients list [--q <text>]`	List patients
`healos patients search <name>`	Find patients by name
`healos patients get <id>`	Show one patient
`healos patients create --first-name --last-name [--dob --phone --email --mrn]`	Create a patient
`healos patients update <id> [--phone --email ...]`	Update a patient
`healos patients delete <id>`	Delete a patient (asks to confirm)
`healos documents list --patient <id>`	List a patient’s documents and their extraction status
`healos documents upload <file> --patient <id>`	Upload a PDF, JPG, PNG or DOCX (up to 10 MB)
`healos documents extract <documentId> --patient <id>`	Run or retry text extraction
`healos documents delete <documentId> --patient <id>`	Delete a document (asks to confirm)

Clinical notes

Command	What it does
`healos notes create --text "..." [--patient <id>] [--wait]`	Generate a note from text
`healos notes create --audio visit.wav [--patient <id>] [--wait]`	Generate a note from a recording
`healos notes from-documents --patient <id> [--wait]`	Generate a note from the patient’s documents
`healos notes list [--patient --from --to]`	List notes
`healos notes get <id>`	Show one note
`healos notes export [--format json\|csv\|ndjson] [--out <file>]`	Export notes, with the same filters as `list`
`healos notes regenerate <sessionId> [--template <id>]`	Regenerate a session’s note
`healos sessions get <id>`	Show a visit session and its status
`healos sessions update <id> --patient <id>`	Assign a session to a patient
`healos sessions delete <id>`	Move a session and its notes to the recycle bin (asks first unless `--yes`; never permanent)
`healos sessions restore <id>`	Take a session out of the recycle bin
`healos templates list`	List note templates

notes create returns as soon as the note is queued. Add --wait to wait for the finished note (up to 5 minutes, or --timeout <seconds>).

Scheduling, eligibility and prior auth

Command	What it does
`healos providers list`	List providers in your organization
`healos appointments list [--date]`	List appointments
`healos appointments get <id>`	Show one appointment
`healos appointments create --patient --type --visit-type --start --duration`	Create an appointment
`healos appointments update <id> [--start --duration --status ...]`	Update an appointment
`healos appointments delete <id>`	Delete an appointment (asks to confirm)
`healos eligibility check --payer --npi --provider-name --patient <id>`	Run an insurance eligibility check
`healos eligibility list`, `healos eligibility get <id>`	Past eligibility checks
`healos benefits payers search <name>`	Find a payer ID
`healos prior-auth list [--status --decision]`	List prior-auth requests
`healos prior-auth get <id>`, `healos prior-auth events <id>`	A request and its history
`healos prior-auth workflows`	Available prior-auth workflows
`healos prior-auth check-status`	Refresh Availity statuses (at most every 10 minutes)

AI Receptionist

Command	What it does
`healos receptionist calls list [--from --to --outcome --search]`	List calls, newest first, with outcome and summary
`healos receptionist calls get <id>`	Show one call with its extracted details
`healos receptionist calls transcript <id>`	Print the transcript, one line per turn
`healos receptionist calls recording <id> --out <file>`	Download the recording (file created with mode 0600)
`healos receptionist tasks list [--status --category --search --from --to]`	List inbox tasks, newest first
`healos receptionist tasks get <id>`	Show one inbox task
`healos receptionist tasks create --title <text> [--category --notes --due --patient --call --assignee]`	Add an inbox task
`healos receptionist tasks update <id> [--title --status --category --notes --due ...]`	Change the fields you pass
`healos receptionist tasks resolve <id>`	Mark a task done
`healos receptionist tasks delete <id>`	Delete a task (asks first unless `--yes`)
`healos webhooks list`	List your webhooks
`healos webhooks get <id>`	Show one webhook
`healos webhooks create --name <n> --url <https-url> --event <EVENT> [--format --description --header "Name: value"]`	Register a webhook
`healos webhooks update <id> [--url --event --name --header ... --pause / --resume]`	Change a webhook; `--header` replaces every header
`healos webhooks delete <id>`	Delete a webhook (asks first unless `--yes`)

EHR actions

Command	What it does
`healos ehr actions list [--ehr athena]`	List the EHR actions HealOS supports
`healos ehr actions get <ehr.action>`	Show one action, for example `athena.search_patients`
`healos ehr connections`	Which EHRs your organization has connected

These need the ehr:read scope.

Examples

# Find a patient and generate a note for them
healos patients search "Testy Example"
healos notes create --patient <patientId> --text-file visit.txt --wait

# Upload a referral letter, then write a note from the patient's documents
healos documents upload referral.pdf --patient <patientId>
healos notes from-documents --patient <patientId> --wait

# Check eligibility
healos benefits payers search "Aetna"
healos eligibility check --payer <payerId> --npi 1234567893 --provider-name "Dr. Example" --patient <patientId>

# JSON for scripts
healos patients list --all --json | jq '.data[].id'

Scripts, CI and AI agents

--json prints the raw API response. Errors go to stderr, also as JSON.
HEALOS_API_KEY uses a key without signing in, and takes precedence over the saved profile.
--dry-run prints the request it would send and sends nothing.
Writes ask for confirmation, and deletes always do. Pass --yes to skip the prompt. Without a terminal to ask on, they are refused unless --yes is passed.
The CLI only sends your key over HTTPS to HealOS, and never follows a redirect to another host.
healos mcp runs an MCP server for Claude, Cursor and other AI agents, read-only unless you pass --allow-writes (it ships in the next CLI release). See Use HealOS from an AI agent.

Exit code	Meaning
`0`	Success
`1`	Bad flags or cancelled
`2`	The API rejected the request (4xx)
`3`	Server or network error (5xx), or `--wait` timed out
`4`	Not signed in, invalid key, or missing permission

Get Started

Recipes

Product Guides

Connections

EHR Integrations

Trust

Go Live

Install

Standalone binary

Updating

Commands

Patients and documents

Clinical notes

Scheduling, eligibility and prior auth

AI Receptionist

EHR actions

Examples

Scripts, CI and AI agents

​Install

​Standalone binary

​Updating

​Sign in

​Commands

​Patients and documents

​Clinical notes

​Scheduling, eligibility and prior auth

​AI Receptionist

​EHR actions

​Examples

​Scripts, CI and AI agents

Install

Standalone binary

Updating

Sign in

Commands

Patients and documents

Clinical notes

Scheduling, eligibility and prior auth

AI Receptionist

EHR actions

Examples

Scripts, CI and AI agents