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

AMS help and shell-completion discovery are credential-free and offline: they do not resolve root profiles, read target files, create SDK clients, or log in. You can inspect the group, a leaf command, and completion candidates before configuring credentials or a target:

uv run --frozen hc ams --help
uv run --frozen hc ams inspect --help
_HC_COMPLETE=bash_complete COMP_WORDS="hc ams in" COMP_CWORD=2 uv run --frozen hc
_HC_COMPLETE=bash_complete COMP_WORDS="hc ams inspect --o" COMP_CWORD=3 uv run --frozen hc

Operational validation starts only when Click invokes an AMS leaf callback. discover, agents, departments, teams, organization, skills, and policies then validate their explicit environment and tenant arguments; the remaining leaves require --target-file. All apply the root, target, and authentication checks described below. Deferring preflight does not relax those safety requirements.

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

Create one private tenant-admin session before interactive AMS work, inspect its non-secret binding, and remove it when finished:

uv run --frozen hc login --environment dev --tenant-id TENANT_ID
uv run --frozen hc login --status
uv run --frozen hc logout

hc login reads HC_AMS_ADMIN_EMAIL and HC_AMS_ADMIN_PASSWORD when present, otherwise it prompts (with hidden password input). It stores only the email, tenant/environment binding, access/refresh tokens and expiry in the strict owner-only ~/.healthcloud/cli/ams-session.json; it never stores the password. AMS commands may omit both target flags while this session is present, except that a prod session still needs --environment prod on every command. Explicit flags and target files must match it exactly. A session within 60 seconds of expiry is refreshed once before the operation, under a lock so concurrent commands never spend the same refresh token (a second command waits up to 30 seconds, then stops), and atomically replaced. Refresh failure stops without an AMS call or password fallback and asks for a new login. If the refreshed session cannot be saved, the current command still finishes and prints a warning to run hc login again.

~/.healthcloud and ~/.healthcloud/cli must be directories you own with mode 700; the CLI creates them that way, and refuses (naming the directory and the chmod 700 fix) if an existing one is shared. hc logout deletes the local file only and reports "server_session_revoked": false: issued tokens stay valid until they expire.

Bootstrap candidate IDs with the public SDK discovery endpoint. Without a saved session both flags are required; a saved session supplies both together. No MCP defaults, admin login, or automatic candidate selection are used:

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

Read-only agent listing, inspection and export take flags instead of a target file; both may be omitted together when a matching saved session exists. Without one, they log in as tenant admin using HC_AMS_ADMIN_EMAIL / HC_AMS_ADMIN_PASSWORD. Stdout carries bounded metadata only; adapter shows whether an agent runs from the file or db config adapter (unknown when the server does not say). export first re-checks the agent/tenant identity, then saves the server's own JSON/YAML export byte-for-byte to a new owner-only --out file, refusing (and leaving no file) when the body is not valid UTF-8. export needs an AMS build that serves /agents/{agent_id}/configuration/export; that route is not yet deployed to dev:

uv run --frozen hc ams agents list --environment dev --tenant-id TENANT_ID
uv run --frozen hc ams agents get --environment dev --tenant-id TENANT_ID --agent-id AGENT_ID
uv run --frozen hc ams agents export --environment dev --tenant-id TENANT_ID --agent-id AGENT_ID \
  --format yaml --out agent.yaml

Read-only department listing and inspection use the same explicit tenant-admin targeting. They emit one versioned JSON result on stdout; failures emit one categorized JSON result on stderr. Department descriptions, creator identities, and evaluation-suite content are never included in the projection:

uv run --frozen hc ams departments list --environment dev --tenant-id TENANT_ID
uv run --frozen hc ams departments get --environment dev --tenant-id TENANT_ID \
  --department-id DEPARTMENT_ID

Department reads are complete and unpaged. The CLI does not expose department create, update, delete, activate, or deactivate operations.

Read-only team listing and inspection are also complete and unpaged. The bounded projection omits descriptions and creator identities; it includes evaluation-suite IDs but never suite content. The CLI does not expose team mutations:

uv run --frozen hc ams teams list --environment dev --tenant-id TENANT_ID
uv run --frozen hc ams teams get --environment dev --tenant-id TENANT_ID --team-id TEAM_ID

The organization hierarchy is the backend-built department/team/agent tree. The CLI preserves its order and nesting without issuing entity reads, joining records, or inferring missing relationships:

uv run --frozen hc ams organization hierarchy --environment dev --tenant-id TENANT_ID

Read-only skill catalog listing and inspection are complete and unpaged. The bounded projection includes only skill IDs, names, tool IDs, and audit timestamps; it omits descriptions, tenant identity, creator identity, arbitrary response fields, and tool details. Tool-ID order is preserved:

uv run --frozen hc ams skills list --environment dev --tenant-id TENANT_ID
uv run --frozen hc ams skills get --environment dev --tenant-id TENANT_ID --skill-id SKILL_ID

The CLI does not create, update, delete, or assign skills. Skill commands do not read guardrails. They make exactly one catalog GET after tenant-admin login and does not paginate, retry, cache, join, or infer additional catalog data. Skill reads refuse target files, root credentials or base URLs, raw output, blank or dot-segment skill IDs, and installed SDKs that do not provide both skill list and get methods. These local refusals happen before tenant-admin login or catalog reads.

Read-only policy catalog listing and inspection are complete and unpaged. The bounded projection includes only policy IDs, names, department IDs, guardrail IDs, active status, and audit timestamps. It never emits protected policy content, descriptions, tenant or creator identity, arbitrary response fields, or joined department/guardrail details. Guardrail-ID order is preserved:

uv run --frozen hc ams policies list --environment dev --tenant-id TENANT_ID
uv run --frozen hc ams policies get --environment dev --tenant-id TENANT_ID --policy-id POLICY_ID

The CLI does not export protected policy content; create, update, delete, or assign policies; or join guardrail records. It makes exactly one catalog GET after tenant-admin login and does not paginate, retry, cache, join, or infer referenced resources. Policy reads refuse target files, root credentials or base URLs, raw output, blank or dot-segment policy IDs, and installed SDKs without both policy methods before tenant-admin login or catalog reads. Successful reads make no assignment, deployment, serving, enforcement, or effectiveness claim.

Read-only guardrail catalog listing and inspection are complete and unpaged. The bounded projection includes only guardrail IDs, names, and audit timestamps. It never emits protected rules, descriptions, tenant or creator identity, arbitrary response fields, or joined policy/agent details:

uv run --frozen hc ams guardrails list --environment dev --tenant-id TENANT_ID
uv run --frozen hc ams guardrails get --environment dev --tenant-id TENANT_ID \
  --guardrail-id GUARDRAIL_ID

The CLI does not export rules; create, update, delete, assign, deploy, or enforce guardrails; or claim they are active or effective. It makes exactly one catalog GET after tenant-admin login and does not paginate, retry, cache, join, or infer additional data. Guardrail reads refuse target files, root credentials or base URLs, raw output, blank or dot-segment guardrail IDs, and installed SDKs without both guardrail methods before tenant-admin login or catalog reads.

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.

For CI and scripts with no saved session, credentials may still enter through HC_AMS_ADMIN_EMAIL and HC_AMS_ADMIN_PASSWORD in the current process, intended for composition with the existing onepassword-env wrapper; that compatibility path logs in once per invocation. There is no fallback identity, secret argument, arbitrary token import, resolved env file, keychain, 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.

Installed CLI integration

From the repository root, with Python 3.14, uv 0.12.5 and Node.js available:

python -m unittest discover -s tooling/cli-integration -p 'test_*.py' -v
python tooling/cli-integration/run.py --output /tmp/hc-cli-integration

The runner installs the SDK, tenant-admin SDK and CLI from the frozen CLI lock with uv sync --no-editable into a fresh temporary environment outside the checkout. It verifies installed module ownership, version, help for every AMS command, native shell completion, discovery and the inspect/plan/show/apply/restore journey. Negative journeys exercise denied login, identity/qualification/plan rejection, malformed responses, failed readback and uncertain writes without mutation replay.

The Installed CLI integration workflow selects its uv-installed Linux job at job level for packages/cli/**, packages/pip/**, packages/pip-tenantadmin/**, its own tooling/workflow, docs compiler inputs (tooling/docs-compiler/**, docs-src/**, docs/sdk/**), MCP contracts (contracts/mcp/**), and root package/lock, Python/lock and Ruff inputs. Backend-only changes skip the install job; the small CLI integration result check still runs and verifies applicability. Invalid selection or an applicable failed/cancelled/skipped job fails it. The job retains only sanitized consumer/JUnit results for seven days.

All scenario records and credentials are synthetic. A test-only Python startup adapter preserves the canonical DEV AMS/tenant-admin origins for product validation while routing only those exact origins over real HTTP to an owned loopback fixture; other origins are refused before network access. Child processes use an isolated home and an allowlisted environment. The adapter is outside all shipped distributions. This boundary does not verify TLS or deployed service conformance. A verified save still exits 1 with outcome="saved" and publication="unknown"; publication and runtime acceptance remain unverified.

Required-check activation is tracked separately in services #724. Require CLI integration only after the workflow is merged and both relevant and unrelated-change Actions results and effective settings are verified.