> ## Documentation Index
> Fetch the complete documentation index at: https://docs.healos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# HealOS CLI

> Use the HealOS API from your terminal, scripts and AI agents

`healos` is the HealOS command line. It talks to the [HealOS API](https://docs.healos.ai/introduction.md), so every command uses the same API keys, scopes and [rate limits](https://docs.healos.ai/rate-limiting.md) 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).

```bash npm theme={null}
npm install -g @healos/cli
```

```bash bun theme={null}
bun add -g @healos/cli
```

```bash pnpm theme={null}
pnpm add -g @healos/cli
```

```bash yarn theme={null}
yarn global add @healos/cli
```

Or run it without installing:

```bash npx theme={null}
npx @healos/cli@latest whoami
```

```bash bunx theme={null}
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:

```bash theme={null}
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.

## Sign in

```bash theme={null}
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:

```bash theme={null}
healos login --scopes all                          # every scope
healos login --scopes patients:read,notes:write    # only these scopes
```

> [!NOTE]
>
> 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:
>
> ```bash theme={null}
> 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.

```bash theme={null}
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](https://docs.healos.ai/ehr-actions/overview.md) 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

```bash theme={null}
# 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](https://docs.healos.ai/ai-agents.md#use-healos-from-an-ai-agent-mcp).

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.