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

pip install healthcloud-cli

This installs the hc console script plus its dependency, the healthcloud-sdk 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.

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:

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

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:

{
  "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.

# 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

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

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:

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

  # 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

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

# 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

Building

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

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:

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:

{
  "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 and #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.

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 on POSIX and an owner-only protected DACL on Windows, 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 or HTTP 5xx, 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.

On Windows, chmod does not establish file privacy. Create the private-input directory with an owner-only ACL before saving change JSON or receipts there:

New-Item -ItemType Directory -Path .\ams-private
$amsUser = whoami
icacls .\ams-private /inheritance:r /grant:r "${amsUser}:(OI)(CI)F"

Native file handling checks the opened handle's owner and DACL, rejects grants to other principals and reparse points, and creates outputs with their restricted DACL already in place. Filesystems without usable ACLs fail closed.

The Python CLI and Python CLI (Windows) CI jobs run the non-live suite on Linux and Windows, including native file permissions and apply reconciliation. Both feed SDK package checks; a job failure or unexpected job skip blocks that aggregate. Run locally, sequentially, from packages/cli/pip with uv run --frozen --extra dev python -m pytest -q -m 'not live'. These synthetic checks do not establish live CareCo acceptance. That still needs an explicitly selected and qualified DEV agent, scoped credentials, and the attended before/after/restore procedure above.

For an optional real-HTTP reproduction with Postman CLI 1.75.0, start postman simulation run postman/simulations/ams-tuning-failure.sim.yaml --port 4900 --no-history --output ndjson from the repository root. In another terminal, run the same SDK verification helper used by the required loopback HTTP tests:

uv run --project packages/cli/pip --frozen --extra dev python -c "import sys; sys.path.insert(0, 'packages/cli/pip/tests'); from test_ams_http import verify_uncertain_apply; print(verify_uncertain_apply('http://127.0.0.1:4900/ams/api/ams'))"

The simulation log must show GET plan, GET agent, one POST apply returning 503, then GET plan and GET agent. Restart the stateful simulation before repeating; stop it with Ctrl+C afterward. This is a source-backed synthetic failure fixture, not the deployed service. The required CI tests exercise both pre-commit and post-commit 503 over loopback HTTP without requiring a Postman login or installation.