Metadata-Version: 2.5
Name: healthcloud-cli
Version: 3.2.1
Summary: Command-line interface for the HealthCloud MCP gateway, generated from the shared MCP tool manifest.
Project-URL: Issues, https://github.com/healthcloudservices/healthcloud-services/issues
Project-URL: Repository, https://github.com/healthcloudservices/healthcloud-services
Author: Healthcheck Systems Inc
License-Expression: MIT
Keywords: cli,health-cloud,healthcare,healthcloud,mcp
Requires-Python: >=3.14
Requires-Dist: click>=8.1
Requires-Dist: healthcloud-sdk>=3.14.0
Requires-Dist: healthcloud-tenantadmin>=1.1.1
Provides-Extra: dev
Requires-Dist: pytest>=9.0.3; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Description-Content-Type: text/markdown

# healthcloud-cli

Requires **Python 3.14 or newer**.

`hc` provides the HealthCloud MCP gateway and bounded deployed AMS administration.
The `hc mcp` subtree has exactly one subcommand per
MCP tool -- generated dynamically at startup from a shared manifest across
audiences such as `patient`, `fieldagent`, `ehr`, `vitals`, `diagnostics`,
`appointments`, `graph`, `person`, `provider`, `tenantadmin`, `connectors`,
and `telehealth`. Run `hc mcp tools list` to see the exact, current set for
your installed version. Nothing here is hand-written per tool: the same
manifest also drives the sibling NPM CLI (`@healthcloud CLI` in
`packages/cli/npm`), so command names match exactly between the two.

## Install

```bash
pip install healthcloud-cli
```

This installs the `hc` console script plus its dependency, the
[`healthcloud-sdk`](../../pip) package, which does the actual HTTP/JSON-RPC
work against the MCP gateway.

## Local development

Use uv 0.12.5 and Python 3.14. The package's uv source override installs the
SDK checkout in editable mode; its committed lock includes the test and build
tools. Released package consumers can still use pip.

```bash
cd packages/cli/pip
uv lock --check
uv sync --frozen --extra dev
uv run --frozen --extra dev python -m pytest
uv run --frozen hc --help
uv run --frozen hc mcp tools list --audience patient
uv run --frozen hc mcp patient get-patient --help
```

The bundled tool manifest (`healthcloud_cli/contracts/mcp-tools.manifest.json`)
is a copy of `packages/cli/contracts/mcp-tools.manifest.json`. Re-sync it
after pulling manifest changes with:

```bash
python scripts/bundle_manifest.py
```

This also runs automatically as a hatchling build hook whenever you `python
-m build`, so a built wheel/sdist is always self-contained and never depends
on a relative path outside the installed package.

## Authentication & configuration

Every command accepts these global options (place them before the `mcp`
subcommand):

| Flag              | Env var           | Meaning                                      |
|-------------------|--------------------|-----------------------------------------------|
| `--access-token`  | `HC_ACCESS_TOKEN`  | Bearer token sent to the MCP gateway          |
| `--base-url`      | `HC_MCP_BASE_URL`  | Override the MCP gateway base URL             |
| `--profile`       | `HC_PROFILE`       | Named profile (see below)                     |
| `--output`        | --                  | `pretty` (default) \| `json` \| `raw`         |
| `--raw`           | --                  | Shortcut for `--output raw`                   |
| `--verbose`       | --                  | Print request diagnostics to stderr           |

Precedence, highest wins: **explicit CLI flag > environment variable >
profile file value > built-in default** (`environment` defaults to `"dev"`;
`accessToken`/`baseUrl` default to unset). The resolved access token is never
written to logs, generated files, or test snapshots.

### Optional profile file

`~/.healthcloud/cli/profiles.json`:

```json
{
  "dev-mia": {
    "baseUrl": "https://dev-api-mcp.health.cloud",
    "accessToken": "eyJ...",
    "environment": "dev"
  }
}
```

A missing profiles file is not an error -- profiles are entirely optional. If
`--profile`/`HC_PROFILE` names a profile and the file (or that entry) is
missing, `hc` exits with a clear usage error rather than silently ignoring
it.

```bash
# get-patient is self-service — the patient is resolved from the access
# token, so no --patient-id flag exists.
hc --profile dev-mia mcp patient get-patient
```

## Listing and inspecting tools

```bash
# Local (bundled manifest, no network call)
hc mcp tools list
hc mcp tools list --audience patient

# Live gateway (requires --audience)
hc mcp tools list --audience patient --remote

# Full manifest entry for one tool (description, inputSchema, method/path)
hc mcp tools show patient add_insurance --output json
```

## Calling a tool

Every manifest tool is its own subcommand, grouped by audience:

```bash
hc mcp patient get-patient
hc mcp appointments book-appointment --patient-id patient-123 --slot-id slot-456

# Every Diagnostics tool takes an explicit --patient-id — providers and
# field agents legitimately look up or record diagnostics for a patient
# other than themselves. When the caller holds a patient token, the backend
# enforces server-side that --patient-id must be their own (403 otherwise).
hc mcp diagnostics create-rapid-test --patient-id patient-123 --test-type covid-19 --result negative
```

Run `--help` on any generated command to see its real manifest description
and arguments:

```bash
hc mcp patient get-patient --help
```

### Argument flags

- **Primitive properties** (`string`/`number`/`integer`/`boolean`) become a
  normal flag in kebab-case, e.g. `patient_id` -> `--patient-id`.
  - `enum` values are validated; invalid values are rejected before any
    network call.
  - `minimum`/`maximum`/`exclusiveMinimum`/`exclusiveMaximum` are enforced
    the same way.
  - Boolean properties are a tri-state flag pair: `--flag/--no-flag`.
    Passing neither leaves the value unset (falls back to the manifest
    default or an `--input`/`--stdin` value, if any); passing one sets it
    explicitly to `true`/`false`.
- **Object/array properties are never flattened.** They get a single
  `--<prop>-json` flag that takes a raw JSON string, e.g.:

  ```bash
  # create-medication is self-service — no --patient-id flag; the patient is
  # resolved server-side from the access token.
  hc mcp patient create-medication \
    --name "Metformin" \
    --dosage-json '{"value":10,"unit":"mg","frequency":"once_daily"}'
  ```
- Path parameters (from `{placeholders}` in the tool's HTTP path) are always
  required, in addition to whatever `inputSchema.required` lists.

### Bulk input: `--input` / `--stdin`

```bash
hc mcp appointments book-appointment --input request.json
cat request.json | hc mcp appointments book-appointment --stdin
```

`--input <file>` and `--stdin` both supply a *base* JSON object of
arguments. `--input` and `--stdin` cannot be combined. Merge precedence
(highest wins): **manifest defaults < `--input`/`--stdin` object < explicit
flags** -- i.e. an explicit flag you actually pass always overrides the same
key coming from a file or stdin, which in turn overrides the schema default.

After merging, the final object is validated against the tool's
`inputSchema` (required fields present, correct types, enum membership,
numeric bounds). Any validation failure prints a clear message to stderr and
exits **2**, without making a network call.

### `hc mcp call` -- generic escape hatch

`hc mcp call` dispatches to any MCP tool by its exact snake_case tool name --
including one not yet present in the bundled manifest (the tool name itself
is never validated against the manifest, it's just forwarded):

```bash
# get_patient is self-service and takes no arguments — {} is a complete,
# valid call.
hc mcp call patient get_patient --input '{}'
hc mcp call patient get_patient --input-file request.json
cat request.json | hc mcp call patient get_patient --stdin
```

Note the deliberate inconsistency versus named commands: here `--input` takes
an inline JSON **value**, not a file path -- use `--input-file` for a file.
Exactly one of `--input` / `--input-file` / `--stdin` may be given (or none,
meaning `{}`).

## Output modes

The MCP tool-call result is `{ content: [{type:"text", text: "..."}],
is_error: bool }` from the JSON-RPC response's `.result`, or the JSON-RPC
`.error` object if the gateway returned one.

- **`pretty`** (default): if `content[0].text` parses as JSON, pretty-prints
  the parsed value; otherwise prints the raw text. On a JSON-RPC error,
  prints `error.message` (and `error.code` with `--verbose`) to stderr.
- **`json`**: prints the tool result's parsed JSON (or raw text if
  unparseable) to stdout, with no envelope.
- **`raw`**: prints the complete JSON-RPC envelope (`id`, `jsonrpc`,
  `result`, `error`) as returned by the gateway.

Diagnostics and `--verbose` logs always go to stderr -- stdout stays
pipeable in every mode.

## Exit codes

| Code | Meaning                                                              |
|------|-----------------------------------------------------------------------|
| `0`  | Success                                                                |
| `2`  | Local input validation failure (bad JSON, missing required field, invalid enum/number, `--input`+`--stdin` both given, unknown option) -- no network call made |
| `3`  | HTTP/network failure talking to the MCP gateway                       |
| `4`  | JSON-RPC error response (`.error` is not `None`)                      |
| `5`  | MCP tool result reported `is_error: true`                             |

## Building

```bash
uv lock --check
uv run --frozen python -m build --no-isolation
uv run --frozen python -m zipfile -l dist/*.whl   # confirm the bundled manifest is included
```

## Deployed AMS administration (source checkout)

The reviewed AMS administration SDK is not published yet. Use this checkout's
editable SDK and tenant-admin sources; no released SDK version is claimed to
contain `ams_admin`. An installed SDK missing that capability is refused before
login. Ordinary MCP commands keep their existing behavior.

Prepare ignored SDK build READMEs from tracked inputs, then install the locked
editable packages (the CLI README itself is tracked):

```bash
node tooling/docs-compiler/prepare-package-readmes.mjs
cd packages/cli/pip
uv sync --frozen --extra dev
uv run --frozen hc ams --help
```

Bootstrap candidate IDs with the public SDK discovery endpoint. Both flags are
required; no MCP defaults, admin login, or automatic candidate selection are used:

```bash
uv run --frozen hc ams discover --environment dev --tenant-id TENANT_ID
```

Every other command requires an explicit local, non-secret target JSON file.
Only the canonical HTTPS AMS origin for that environment is accepted; custom
origins require separately verified support. Target and nested qualification keys
are strict. Unknown/unavailable qualification may be represented by omitted
records or empty qualification `{}` for inspection/UI, but blocks planning.

The following is a **schema example**, not evidence of deployed CareCo eligibility.
Replace its assertions only after an operator has established the corresponding
proof. `deployed_build` and `proof_ref` are references, never credentials:

```json
{
  "schema_version": 1,
  "environment": "dev",
  "tenant_id": "TENANT_ID",
  "agent_id": "EXPLICIT_SELECTED_AGENT_ID",
  "api_origin": "https://dev-amsservices.health.cloud",
  "qualification": {
    "runtime": {"source": "OPERATOR_VERIFIED_RUNTIME", "proof_ref": "RUNTIME_PROOF"},
    "instructions": {"source": "agent.instructions", "proof_ref": "INSTRUCTION_SOURCE_PROOF"},
    "greetings": {"source": "agent.greetings", "proof_ref": "GREETING_SOURCE_PROOF"},
    "backend_model_context": {
      "deployed_build": "OPERATOR_VERIFIED_DEPLOYED_REVISION",
      "config_version": 7,
      "proof_ref": "FULL_INPUT_AND_WRITER_COVERAGE_REVIEW_PROOF",
      "current_build_confirmed": true,
      "fresh_session": true,
      "no_attachments_or_history": true,
      "full_inputs_approved": true,
      "change_path_without_logs": true
    }
  }
}
```

Qualification is an operator assertion with evidence, never authorization.
Server-side tenant-admin authorization remains mandatory. No current-build API is
established: the CLI cannot automatically detect an unreported deployment, verify
actual runtime consumption, attest deployed all-writer coverage, or audit model
inputs. A changed/unavailable build or agent configuration invalidates the review;
the operator must refresh the record. The recorded config version must equal the
inspected version before planning/apply/restore.
`full_inputs_approved` means an operator approved non-sensitive **full planner and
reviewer inputs**, including custom_tools, catalogs, all agent fields, and all other
server context. Output projection does not sanitize server-side model context.
`change_path_without_logs` requires evidence that the exact deterministic modify
request uses the change path, avoiding the direct-answer branch's recent logs.
Unknown effective sources and file-backed/ignored instructions block tuning.

Before `plan`, `apply` or selected-field `restore`, the operator must review evidence
that the actual serving build includes **all writer version coverage**: ordinary
agent updates and startup/migration repair writers advance `config_version`
atomically with their changes, and tuning apply uses transactional compare-and-set
against the expected version. Bind this coverage evidence and the full-input
review together in the existing `qualification.backend_model_context.proof_ref`
review bundle for its `deployed_build`, inspected `config_version` and
`current_build_confirmed` assertion. AMS source prerequisites
[#488](https://github.com/healthcloudservices/healthcloud-ams-services/pull/488) and
[#497](https://github.com/healthcloudservices/healthcloud-ams-services/pull/497)
are evidence leads; source tests, PR merges, or a numeric `config_version` alone
cannot prove coverage in the serving build. If deployed identity or any writer's
coverage is unknown, or a writer still bypasses version advancement, stop
`plan`/`apply`/`restore`; bounded read-only inspection/UI may continue under their
existing limits. Refresh this evidence after a changed/unknown build or agent
configuration and recheck it before apply and selected-field restore. This is an
operator prerequisite: the current CLI does not automatically attest deployment
or all-writer coverage, and the record adds no server authorization boundary.

Credentials enter only through `HC_AMS_ADMIN_EMAIL` and `HC_AMS_ADMIN_PASSWORD`
in the current process, intended for composition with the existing
`onepassword-env` wrapper. Each invocation logs in through `HCTenantAdminSDK`;
tokens remain private in memory. There is no token cache, fallback identity,
secret argument, resolved env file, or browser credential bridge. Root MCP
`--access-token`, `--base-url`, their environment equivalents, and token/base-URL
profiles are refused for AMS. Root profile environment values do not select AMS.

```bash
uv run --frozen hc ams --target-file TARGET.json inspect
uv run --frozen hc ams --target-file TARGET.json inspect --out PRIVATE_INSPECTION.json
uv run --frozen hc ams --target-file TARGET.json plan --changes-file PRIVATE_CHANGES.json --out PRIVATE_RECEIPT.json
uv run --frozen hc ams --target-file TARGET.json show --receipt PRIVATE_RECEIPT.json --out PRIVATE_DIFF.json
uv run --frozen hc ams --target-file TARGET.json apply --receipt PRIVATE_RECEIPT.json --confirm-plan-hash DISPLAYED_HASH
uv run --frozen hc ams --target-file TARGET.json restore --receipt PRIVATE_RECEIPT.json --out PRIVATE_RESTORE_RECEIPT.json
uv run --frozen hc ams --target-file TARGET.json ui --repo EXISTING_AMS_WORKTREE
```

Changes JSON accepts only nonempty subsets of `instructions` (string) and
`greetings` (language-key to string map). Input changes/receipts must be regular,
owner-only files (for example create under `umask 077`). Outputs use exclusive
0600 creation and refuse overwrite/symlinks; failed operations remove unfinished
outputs. No whole-agent snapshot is saved. Free text appears only in explicitly
requested private files for human review before any AI use. Default output in
pretty/json/verbose modes contains bounded metadata and hashes; AMS refuses raw.

The planner receives `Update the agent configuration to exactly these field
values: ` followed by sorted, compact requested JSON. Extra fields, files,
validation errors, warnings/skipped references, blocking or unknown review
findings, and approximate wording are refused. Each immutable field change must
include `before` and exact `after` values so a modified receipt cannot redefine a
restore. A server plan omitting `before` cannot safely support this workflow;
review/replan rather than synthesizing server provenance. `show`/`apply` reload the
immutable backend plan/hash. Before apply, recheck the deployed coverage and
full-input qualification above. Apply requires the displayed hash, matching
version and selected before-values, and sends `confirm=True` once. HTTP 401/403
and 409 never trigger identity fallback or mutation replay.

On transport failure, apply records an unknown outcome and reconciles through GET
plan/agent without retrying the mutation. Confirmed saves require applied status,
selected-field readback and exactly the next config version. The current public
response omits publication_status: **saved/readback confirmed is reported separately
from publication unknown and runtime unverified**, with nonzero exit status for
complete success. `publish_failed` is reported separately. Do not replay a saved
apply to resolve publication. A fresh invocation refuses an already consumed plan.

Restore creates a new reviewed plan from only the selected fields' authoritative
before-values against the latest config version. Unrelated edits are preserved;
a current same-field mismatch blocks restore. There is no force restore. Refresh
operator qualification, including deployed all-writer coverage and full-input
evidence, for the latest build/version first, then review the new
restore receipt with `show` and confirm its new hash with `apply`.

UI launch validates the existing `test-client-ui/package.json` Vite script,
refuses lifecycle hooks, and invokes `npm run dev -- --host 127.0.0.1` by argv
with `shell=False`. It installs nothing and launches no backend. The allowlisted
child environment includes toolchain essentials plus only these public target
variables: `VITE_API_URL`, `VITE_HEALTHCLOUD_ENVIRONMENT`, `VITE_TUNING_TENANT_ID`,
`VITE_TUNING_AGENT_ID`. Injected HC/OP credentials and other VITE/NODE/NPM options
are excluded. It prints `/app/agents/{agent_id}`; browser login remains separate.
The supplied existing worktree and its local frontend configuration remain
operator-controlled.

AMS failures exit nonzero with safe categories, never backend exception bodies.
In particular, apply may exit nonzero after a confirmed save because publication
is unknown: inspect the emitted outcome before any next action.
