healthcloud-cli
Requires Python 3.14 or newer.
hc is an SDK-backed CLI: the primary surface is hc ams, which reads and
tunes one explicitly selected AMS tenant (catalog domains -- skills, policies,
guardrails, teams, departments, organization, data-sources, tools -- plus
read-only agent operations). The hc mcp subtree is the gateway fallback and
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, policies, and sessions
(with attachments and messages) 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):
| 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.
Saved hc login session fallback
When no explicit token is given (--access-token, HC_ACCESS_TOKEN, or a
profile accessToken), hc mcp uses the saved hc login tenant-admin
session as the bearer, with the same locked refresh-near-expiry behavior as
hc ams (the refreshed session is persisted for the next command):
hc login --environment dev --tenant-id TENANT_ID # saves/refreshes the session
hc mcp tenantadmin get-current-tenant-admin # uses the saved session bearer
On HTTP 401 when no explicit token and no saved session exist, the CLI
prints one hint line — Hint: not logged in; run 'hc login', or pass --access-token / HC_ACCESS_TOKEN. — after the failure line, and exits 3.
An explicit token always wins over the saved session; hc logout removes it
(local only).
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.enumvalues are validated; invalid values are rejected before any network call.minimum/maximum/exclusiveMinimum/exclusiveMaximumare 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/--stdinvalue, if any); passing one sets it explicitly totrue/false.
-
Object/array properties are never flattened. They get a single
--<prop>-jsonflag 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 whateverinputSchema.requiredlists.
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): ifcontent[0].textparses as JSON, pretty-prints the parsed value; otherwise prints the raw text. On a JSON-RPC error, printserror.message(anderror.codewith--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
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.
For CI and agents, log in non-interactively: pass --email and pipe the password
to --password-stdin (read as exactly one stdin line, never echoed, never a
flag value — there is no --password option):
printf '%s\n' "$HC_AMS_ADMIN_PASSWORD" | \
uv run --frozen hc login --environment dev --tenant-id TENANT_ID \
--email "$HC_AMS_ADMIN_EMAIL" --password-stdin
--email beats HC_AMS_ADMIN_EMAIL and --password-stdin beats
HC_AMS_ADMIN_PASSWORD. With --password-stdin, the piped line is always the
password: it is read before any prompt, so it can never be consumed as the
email, and the email must come from --email, HC_AMS_ADMIN_EMAIL or (only on
an interactive terminal) the email prompt. When stdin is not an interactive
terminal and neither --password-stdin nor HC_AMS_ADMIN_PASSWORD supplies the
password, hc login refuses with that guidance instead of attempting a hidden
prompt (no GetPassWarning, no echoed password); a missing email on a
non-interactive stdin (or a process with no stdin stream at all) is refused the
same way, naming --email/--password-stdin; every refusal happens before any
login request. --status cannot be combined with --email or --password-stdin.
Even on an interactive terminal, --password-stdin suppresses terminal echo
while the single line is read and restores it afterwards; a stdin stream that is
closed or errors mid-read is refused cleanly (exit 2, never a traceback).
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.
hc login works before the admin's email is verified. The current-admin
profile reports email_verified (invited admins start verified); confirm the
emailed code with hc tenants verify-email.
~/.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.
Tenant registration: hc tenants register
Creates a tenant and its first (primary) tenant admin through the tenant-admin
SDK (POST /tenants/register) — CLI-first, never an MCP passthrough:
printf '%s\n' "$ADMIN_PASSWORD" | \
uv run --frozen hc tenants register \
--tenant-id acmeclinic --name "Acme Clinic" \
--admin-first-name Ana --admin-last-name Doe \
--admin-email ana@example.test --password-stdin
- Requires a saved
hc loginsession — the session token is attached to the SDK before the call; without a session the command refuses with "runhc loginbefore registering a tenant" and makes no network call.--environmentmust match the saved session's environment. --tenant-idis validated locally (lowercase a-z only, e.g.acmeclinic) before any network call; anything else is refused without a request.- The admin password comes only from a hidden interactive prompt or
--password-stdin(exactly one stdin line, echo-suppressed). There is no--passwordflag, and the password is never echoed or logged. - Output: a
tenants.registerenvelope with the tenant ID, status, tier, admin ID andemail_otp_sent, plus a next-step hint pointing athc tenants verify-email. A 409 is reported as "A tenant with this ID already exists"; other API errors surface the backend's safe message.
Tenant email verification: hc tenants verify-email and hc tenants resend-code
Confirms (or re-sends) the registration OTP through the tenant-admin SDK
(POST /auth/verify-email / POST /auth/resend-verification-code) —
CLI-first, never an MCP passthrough:
uv run --frozen hc tenants verify-email \
--environment dev --tenant-id acmeclinic --email ana@example.test --otp 123456
uv run --frozen hc tenants resend-code \
--environment dev --tenant-id acmeclinic --email ana@example.test
- No saved
hc loginsession is required: the emailed OTP is the proof, and no bearer token is sent. --tenant-idis validated locally (lowercase a-z only) before any network call;--emailand--otpmust be nonblank.verify-emailoutput: atenants.verify-emailenvelope with the verified email and the exact next command to run —hc login --environment dev --tenant-id acmeclinic --email ana@example.test(the password is prompted, never a flag value).email_verifiedistrueonly when the service answersverified: true; any other answer reportsfalse.resend-codeoutput: atenants.resend-codeenvelope withsent: true.- A wrong or expired code is reported as the server's safe message (e.g. "Verification code is invalid or expired"); an unknown email is a not-found error. Both are bounded JSON envelopes, never stack traces.
Managing tenant admins: hc admins create, hc admins list, hc admins get
Adds and reads a tenant's admins through the tenant-admin SDK
(POST /auth/register mode=self, GET /tenant-admins, GET /admins/{admin_id})
— CLI-first, never an MCP passthrough:
printf '%s\n' "$ADMIN_PASSWORD" | \
uv run --frozen hc admins create --first-name Bo --last-name Nguyen \
--email bo@example.test --password-stdin
uv run --frozen hc admins list
uv run --frozen hc admins get --admin-id ADMIN_ID
- All three commands require a saved
hc loginsession; the session's tenant is always the target (there is no--tenant-idflag). Without a session the command refuses with "runhc loginbefore managing tenant admins" and makes no network call.--environment(optional) must match the saved session's environment. createadds another admin to the saved session's tenant. The new admin's password comes only from a hidden interactive prompt or--password-stdin(exactly one stdin line, echo-suppressed); there is no--passwordflag and the password is never echoed or logged. Its success envelope carries the newadmin_id,email_otp_sentand a next-step hint pointing athc tenants verify-email. A 409 is reported as "A tenant admin with this email already exists for the tenant".listandgetare read-only, unpaged and bounded: each admin is projected toid,name,email,statusandis_primaryonly — never phone numbers, Cognito subs, permissions or audit fields.listemitsdata.adminsplus an unpagedpageblock;getemitsdata.admin. Both omit theverificationblock, like every read.- Failures are the shared bounded error envelopes: not-found (
geton an unknown ID), conflict (duplicate email oncreate), validation (blank inputs or an environment mismatch, refused before any network call), authentication (no saved session) and transport — never stack traces.
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. They emit the same versioned result envelope as the
other read domains (operation, outcome, schema_version, target, data;
no verification block on reads); failures emit one categorized JSON error
envelope on stderr with the same categories (not found, target mismatch,
refusal, logged out), not the plain-text Error: … lines of earlier releases.
agents list carries bounded projections under data.agents plus a page
block; agents get carries the bounded projection under data.agent, whose
assigned_references holds both halves of an assignment: the nullable
department_id/team_id organization references and the five capability lists
(tool_ids, skill_ids, guardrail_ids, policy_ids, data_source_ids). The
legacy top-level {"agents": …, "environment": …, "tenant_id": …} shape is
intentionally replaced by this envelope — scripts must read the new shape.
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 (exact bytes preserved), refusing (and leaving no file) when the body is
not valid UTF-8; its stdout reports the envelope with the file path, format
and sha256 under data and the agent_id in target. 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
For example, hc ams agents list succeeds with (formatted for readability):
{"schema_version": 1, "operation": "agents.list", "outcome": "succeeded",
"target": {"environment": "dev", "tenant_id": "TENANT_ID"},
"data": {"agents": [{"id": "AGENT_ID", "name": "…", "adapter": "file", "…": "…"}],
"page": {"kind": "unpaged", "returned_count": 1, "continuation": null}}}
and a missing --agent-id fails with one envelope on stderr and exit 1:
{"schema_version": 1, "operation": "agents.get", "outcome": "failed",
"target": {"environment": "dev", "tenant_id": "TENANT_ID", "agent_id": "AGENT_ID"},
"error": {"category": "not_found", "message": "Agent 'AGENT_ID' was not found."}}
Agent lifecycle changes are two first-class, send-once write commands. They
require a saved hc login session (env-var credentials are not accepted for
writes) and an explicit --expected-config-version, --confirm acknowledgement:
uv run --frozen hc ams agents deactivate --environment dev --tenant-id TENANT_ID \
--agent-id AGENT_ID --expected-config-version N --confirm
uv run --frozen hc ams agents activate --environment dev --tenant-id TENANT_ID \
--agent-id AGENT_ID --expected-config-version N --confirm
Each command issues exactly one GET /agents/{agent_id}, local pre-checks,
exactly one PUT /agents/{agent_id}, and exactly one GET readback. The PUT
body is exactly {"status": …, "active": …} and nothing else — the server's
update schema accepts ~40 fields, but a lifecycle command is not a generic CRUD
fallback, so there is no agents update, no --status/--active flag, and no
archive here (deletion is its own reviewed command, below). deactivate writes status: "disabled" and
active: false; activate writes status: "active" and active: true.
Writing one field and reporting the other is a false claim, so both are written
and both are read back.
The result envelope reports three facts separately under data:
data.evidence.saved (confirmed only when the readback shows the exact pair
that was sent, for this agent in this tenant), data.evidence.side_effects
(always unverified: no side-effect readback route exists) and
data.evidence.runtime (always unverified: no serving route exists). Exit 0
requires that readback confirmation; a readback mismatch exits nonzero with
"outcome": "failed" and verification.saved_state: "failed" and says the new
state is not confirmed. A readback that is missing, cannot be read as an
agent object, describes a different agent, or lands in a different tenant is the
same unconfirmed failure (never an internal error): data.eligibility.fields_tested_by_read_paths is then null
because those fields could not be observed. data.eligibility states that the
fields the read-eligibility paths test now read the new pair, and warns
explicitly that
get_default_agent_for_tenant / get_orchestrator_for_tenant never test these
fields — a disabled agent can still be selected by those paths — and that
in-flight runs, WSS sessions and schedules are untouched by this route.
Pre-checks refuse with exit 1 and no write: a missing --confirm (exit 2
usage error, before login), an agent outside the explicit tenant, an already
in-effect state, an unsupported archived/draft target (named as having no
supported reversible transition here), or a config_version that no longer
matches --expected-config-version. That version check is a local best-effort
guard only: the route has no If-Match and the server never compares the
version, so it cannot prove atomicity and a request could still race between
the read and the PUT.
A transport error or 5xx from the PUT is reported as outcome: "unknown"
with mutation_replayed: false, verification.saved_state: "unknown" and a
reconciliation: {"status": "not_read", …} block; the CLI sends no retry and
does not re-read automatically — run hc ams agents get before doing anything
else. A failed readback after an accepted PUT is reported the same way (unknown,
not success). A 2xx PUT answer whose body cannot be read as an agent object is
also outcome: "unknown" (sent once, saved state unverified), never an internal
error and never a success.
Capability and organization assignments are one first-class, send-once write
command. It requires a saved hc login session (env-var credentials are not
accepted for writes), an explicit --expected-config-version, and the
--confirm acknowledgement of the target and the printed reviewed diff:
uv run --frozen hc ams agents assignments set --environment dev --tenant-id TENANT_ID \
--agent-id AGENT_ID --expected-config-version N --confirm \
--tool-ids TOOL_ID --tool-ids ANOTHER_TOOL_ID \
--clear-team
There is no assignment route on the server: assignments are plain fields on
the one PUT /agents/{agent_id} route, so this command issues exactly one
GET /agents/{agent_id}, local pre-checks, exactly one PUT, and exactly one
GET readback, and the PUT body is exactly the reference fields the
reviewed diff changes — never the whole agent payload, never a generic
agents update, never the legacy tools/data_sources name aliases, and never
a lifecycle, model or instruction field.
Each family is either omitted (unchanged) or given exactly once:
--department-id, --team-id, and the repeatable --skill-ids, --tool-ids,
--policy-ids, --guardrail-ids, --data-source-ids flags replace that family
exactly; --clear-department, --clear-team and --clear-skill-ids,
--clear-tool-ids, --clear-policy-ids, --clear-guardrail-ids,
--clear-data-source-ids empty or clear it ([] for a list family, null for
the two nullable scalars). The server de-duplicates ids, so the CLI does too.
health_service_id, custom_tools, artifact_kinds, lifecycle and workflow
are not part of this command: a health-service assignment has no hc read
surface, so it would not be reviewable.
The reviewed diff is printed to stderr before the single write (ids only, never
instruction text): each changed field with its before -> after value, plus
sorted added/removed id lists for the list families. It is omitted under
--output json/raw so those modes keep stderr machine-parsable; the same diff
is carried in the envelope under data.changed as
{field: {before, after, added, removed}} (added/removed are null for the
two scalar references).
The envelope reports data.agent_id, data.changed,
data.config_version: {before, after} (a version advance is informational
only), and three facts separately under data.evidence: saved (confirmed
only when the readback is this agent in this tenant and every changed
reference equals the intended after value), side_effects (always unverified)
and runtime (always unverified). data.mutation_replayed is always false.
The three side effects are disclosed, not verified: this route does not
regenerate or publish the agent's Application file (only the plan-apply path
publishes), disable_direct_agent_mutations does not gate this PUT, and the
server audit log records an UPDATE with the payload. Runtime enforcement of
the new references is unobservable: no serving readback route exists, so this
command never claims it.
tool_ids and data_source_ids address unscoped global catalogs by design;
the server checks tenant scope only for the department, team, skill, policy and
guardrail references. This command does not imply otherwise, and it does not
re-implement the server's reference checks.
Pre-checks refuse with exit 1 and no write: a missing --confirm (exit 2
usage error, before login and before any request), no assignment option at all
(exit 2), setting and clearing the same family together (exit 2), an agent
outside the explicit tenant, a request where every reference already equals the
read state ("already in effect"), or a config_version that no longer matches
--expected-config-version. That version check is a local best-effort guard
only: the route has no If-Match and the server never compares the version, so
it cannot prove atomicity and a request could still race between the read and
the PUT. Operation-specific approval here is the CLI's own --confirm plus the
reviewed diff, deliberately separate from the tuning/plan-apply approval path;
the server enforces tenant isolation, reference existence and the audit log, and
it has no assignment approval or consent entity.
A transport error or 5xx from the PUT is reported as outcome: "unknown" with
mutation_replayed: false, verification.saved_state: "unknown" and a
reconciliation: {"status": "not_read", …} block; the CLI sends no retry and
does not re-read automatically — run hc ams agents get before doing anything
else. A 2xx PUT answer whose body cannot be read as an agent object is also
outcome: "unknown". A readback that is missing, cannot be read as an agent, is
a different agent or a different tenant, or does not show exactly the references
that were sent, is outcome: "failed" with verification.saved_state: "failed"
and a re-read pointer — never an internal error, never a replay.
Assignments are not reachable through the tuning path: a generated plan that
carries a reference field is refused by field name by
hc ams sessions plans apply, so a plan/tuning approval can never grant
capabilities.
Deleting an agent is one first-class, send-once destructive command. It requires
a saved hc login session (env-var credentials are not accepted for writes) and
the --confirm acknowledgement of the target and disclosure block it prints:
uv run --frozen hc ams agents delete --environment dev --tenant-id TENANT_ID \
--agent-id AGENT_ID --confirm
Before the delete it reads the agent once and prints the resolved destructive
target (agent_id, name, type, status, active, config_version) and the
disclosure block to stderr, so the operator approves an actual record, not a
phrase. The same disclosure is carried under data.disclosure in the envelope
(irreversible, generated_file, dependency_guard, restore,
authorization, recovery_trail), and it is the honest server contract:
- the delete is a hard delete of the agent row: no soft delete, no tombstone, no retention window and no undelete route;
- the generated agent code file is removed from the runtime;
- the server guards one reference only — schedules that point at the agent
answer
409and nothing is deleted. Default-agent and orchestrator selection, engine bindings (default_agent_id), sessions and utility agents are not guarded (there is no foreign key), so this command cannot detect them; hc ams restorecannot restore a deleted agent (it replays tuning fields onto an existing agent). Export the configuration first withhc ams agents exportif you may need it;- the route needs an authenticated tenant user only: no admin/role check is applied;
- only a server audit row (
AuditAction.DELETE) remains.
The sequence is exactly one GET /agents/{agent_id}, exactly one
DELETE /agents/{agent_id} (204, no body) and exactly one confirmation GET.
Only a 404 from that confirmation read proves the row is gone: the envelope
then reports data.deleted: true, data.evidence.deleted.status: "confirmed"
with confirmation: "not_found" and confirmation_status: 404, plus
data.evidence.side_effects and data.evidence.runtime (both always
unverified) and data.mutation_replayed: false. The command prints no promise
of restore and has no --force, no --dry-run, no interactive prompt and no
--expected-config-version — the route has no If-Match or version check, so a
version flag would advertise protection the server does not offer.
Refusals claim nothing and send nothing extra: a missing --confirm is an exit
2 usage error before login or any request; an agent outside the explicit tenant,
the tenant identity mismatch and a delete target that no longer exists are
refused before the DELETE; a 409 is a conflict refusal naming the referring
schedules; a 404 from the DELETE is not_found; and a 405 is the server's
refusal (unsupported). None of them is retried.
A transport error or 5xx from the DELETE is outcome: "unknown" with
mutation_replayed: false, verification.saved_state: "unknown" and a
reconciliation: {"status": "not_read", …} block; nothing is replayed and the
agent is never restored — run hc ams agents list before doing anything else.
The same unknown outcome applies when the delete was accepted but the
confirmation read could not be read. A confirmation read that still returns the
agent (200) — or a 2xx body that cannot be read as an agent — is
outcome: "failed" with data.deleted: false and
verification.saved_state: "failed", never success.
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.
Department writes are first-class, send-once commands that require a saved
hc login session (run hc login first; env-var credentials are not accepted
for writes). Each write is sent exactly once — the CLI never retries a write —
and the result envelope carries the server's authoritative readback of the
department (same bounded projection as reads):
uv run --frozen hc ams departments create --environment dev --tenant-id TENANT_ID --name "Clinical Operations" --created-by-user-id ADMIN_USER_ID [--description TEXT] [--parent-department-id PARENT_ID] [--key KEY] [--required-eval-suite-ids SUITE_ID ...]
uv run --frozen hc ams departments update --environment dev --tenant-id TENANT_ID --department-id DEPARTMENT_ID [--name NAME] [--description TEXT] [--parent-department-id PARENT_ID] [--key KEY] [--required-eval-suite-ids SUITE_ID ...]
uv run --frozen hc ams departments set-active --environment dev --tenant-id TENANT_ID --department-id DEPARTMENT_ID
uv run --frozen hc ams departments deactivate --environment dev --tenant-id TENANT_ID --department-id DEPARTMENT_ID
uv run --frozen hc ams departments delete --environment dev --tenant-id TENANT_ID --department-id DEPARTMENT_ID
createsucceeds withoperation: "departments.create"anddata.department= the server's 201 readback.--nameand--created-by-user-idare required by the server contract (the tenant is taken from the saved session's authenticated admin, never from a flag).updatesends only the options you pass (an empty--description ""clears it); it refuses with exit 1 (validation) when no field option is given.set-activeanddeactivatemark the department active/inactive.deletesucceeds withdata: {"deleted": true}(the server answers 204 with no body) and is irreversible.- A 404 for the requested department is a
not_foundrefusal naming the ID (oncreate, a 404 names the referenced department — typically the missing--parent-department-id); a target/tenant or identity mismatch is avalidationrefusal; both exit 1 without changes. The one exception is a tenant mismatch on thecreatereadback: the department has already been created server-side, so the CLI reports avalidationrefusal that names the department, the tenant that received it, and tells you to runhc ams departments get— it never claims a landed write was a stopped no-op. - If the transport times out, the connection drops mid-write, or the server
answers an HTTP 5xx/408 before a readable result, the write's outcome is
unknown: the CLI exits 1 with an
unknownenvelope (verification.saved_state: unknown,verification.side_effects: unverified,data.mutation_replayed: false, anddata.reconciliation.status: not_read) whose message says the outcome is unknown and to checkhc ams departments getbefore retrying. It never re-sends the write and never re-reads on its own.
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:
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
Team writes are first-class, send-once commands that require a saved hc login
session (run hc login first; env-var credentials are not accepted for writes).
Each write is sent exactly once — the CLI never retries a write — and the result
envelope carries the server's authoritative readback of the team (same bounded
projection as reads). Teams have no active/inactive lifecycle, so there are no
set-active/deactivate commands:
uv run --frozen hc ams teams create --environment dev --tenant-id TENANT_ID --name "Escalation Team" --department-id DEPARTMENT_ID --created-by-user-id ADMIN_USER_ID [--description TEXT] [--key KEY] [--required-eval-suite-ids SUITE_ID ...]
uv run --frozen hc ams teams update --environment dev --tenant-id TENANT_ID --team-id TEAM_ID [--name NAME] [--description TEXT] [--key KEY] [--required-eval-suite-ids SUITE_ID ...]
uv run --frozen hc ams teams delete --environment dev --tenant-id TENANT_ID --team-id TEAM_ID
createsucceeds withoperation: "teams.create"anddata.team= the server's 201 readback.--name,--department-idand--created-by-user-idare required by the server contract (the tenant is taken from the saved session's authenticated admin, never from a flag).updatesends only the options you pass (an empty--description ""clears it;--clear-required-eval-suite-idssends an empty list to clear the required evaluation suites;--keyaccepts a nonblank key, it cannot be blanked); it refuses with exit 1 (validation) when no field option is given.deletesucceeds withdata: {"deleted": true}(the server answers 204 with no body) and is irreversible. When AI agents still reference the team, the server refuses with 409 and the CLI reports oneconflictrefusal that names the team and says agents reference it; no changes were made.- A 404 for the requested team is a
not_foundrefusal naming the ID (oncreate, a 404 names the referenced department — the missing--department-id); a target/tenant mismatch on an update readback is avalidationrefusal that reports the landed write truthfully: it names the team and the tenant that actually received it and points tohc ams teams get— it never claims a landed write was stopped. - If the transport times out, the connection drops mid-write, or the server
answers an HTTP 5xx/408 before a readable result, the write's outcome is
unknown: the CLI exits 1 with an
unknownenvelope (verification.saved_state: unknown,verification.side_effects: unverified,data.mutation_replayed: false, anddata.reconciliation.status: not_read) whose message says the outcome is unknown and to checkhc ams teams getbefore retrying. It never re-sends the write and never re-reads on its own.
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 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.
Skill writes are first-class, send-once commands that require a saved hc login
session (env-var credentials are not accepted for writes). Each write is sent
exactly once — the CLI never retries a write — and the result envelope carries
the server's authoritative readback of the skill (same bounded projection as
reads). Skills have no active/inactive lifecycle, so there are no
set-active/deactivate commands:
uv run --frozen hc ams skills create --environment dev --tenant-id TENANT_ID --name "Schedule Lookup" --created-by-user-id ADMIN_USER_ID [--description TEXT] [--tool-ids TOOL_ID ...]
uv run --frozen hc ams skills update --environment dev --tenant-id TENANT_ID --skill-id SKILL_ID [--name NAME] [--description TEXT] [--tool-ids TOOL_ID ... | --clear-tool-ids]
uv run --frozen hc ams skills delete --environment dev --tenant-id TENANT_ID --skill-id SKILL_ID
createsucceeds withoperation: "skills.create"anddata.skill= the server's 201 readback.--nameand--created-by-user-idare required by the server contract; the tenant is taken from the saved session's authenticated admin, never from a flag. The server does not validate that--tool-idsreference real tools (blank tool IDs are rejected client-side).updatesends only the options you pass (an empty--description ""clears it;--clear-tool-idssends an explicit empty list to clear the skill's tool bindings); it refuses with exit 1 (validation) when no field option is given.deletesucceeds withdata: {"deleted": true}(the server answers 204 with no body) and is irreversible. When AI agents still reference the skill (via theirskill_ids), the server refuses with 409 and the CLI reports oneconflictrefusal that names the skill and says agents reference it; no changes were made.- A 404 for the requested skill is a
not_foundrefusal naming the ID (oncreate, a 404 is a generic referenced-record refusal — the server does not validate tool references and the CLI does not either); a target/tenant mismatch on a write readback is avalidationrefusal that reports the landed write truthfully: it names the skill and the tenant that actually received it and points tohc ams skills get— it never claims a landed write was stopped. - If the transport times out, the connection drops mid-write, or the server
answers an HTTP 5xx/408 before a readable result, the write's outcome is
unknown: the CLI exits 1 with an
unknownenvelope (verification.saved_state: unknown,verification.side_effects: unverified,data.mutation_replayed: false, anddata.reconciliation.status: not_read) whose message says the outcome is unknown and to checkhc ams skills getbefore retrying. It never re-sends the write and never re-reads on its own.
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 and never emits it: policy
--content is write-only — it is sent to the server but never appears in any
command output, error message, or readback. Read commands make exactly one
catalog GET after tenant-admin login and do 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.
Policy writes are first-class, send-once commands that require a saved hc login
session (env-var credentials are not accepted for writes). Each write is sent
exactly once — the CLI never retries a write — and the result envelope carries
the server's authoritative readback of the policy (same bounded projection as
reads: never content, description, tenant identity, or creator identity).
Policies have an active lifecycle flag, so activate and deactivate
commands exist (they PUT the active field):
uv run --frozen hc ams policies create --environment dev --tenant-id TENANT_ID --name "Appointment Safety" --department-id DEPARTMENT_ID --created-by-user-id ADMIN_USER_ID [--description TEXT] [--content TEXT | --content-file PATH] [--guardrail-ids GUARDRAIL_ID ...]
uv run --frozen hc ams policies update --environment dev --tenant-id TENANT_ID --policy-id POLICY_ID [--name NAME] [--description TEXT] [--content TEXT | --content-file PATH] [--guardrail-ids GUARDRAIL_ID ... | --clear-guardrail-ids]
uv run --frozen hc ams policies activate --environment dev --tenant-id TENANT_ID --policy-id POLICY_ID
uv run --frozen hc ams policies deactivate --environment dev --tenant-id TENANT_ID --policy-id POLICY_ID
uv run --frozen hc ams policies delete --environment dev --tenant-id TENANT_ID --policy-id POLICY_ID
-
createsucceeds withoperation: "policies.create"anddata.policy= the server's 201 readback.--name,--department-idand--created-by-user-idare required by the server contract; the tenant is taken from the saved session's authenticated admin, never from a flag. The server does not validate that--guardrail-idsreference real guardrails (blank guardrail IDs are rejected client-side).--contentis write-only: it is sent but never echoed back. -
The protected policy content can also arrive from an owner-only file, which keeps it out of the command line entirely (argv, the process table under
ps//proc/*/cmdline, shell history and CI logs all see only the path):uv run --frozen hc ams policies create --environment dev --tenant-id TENANT_ID --name "Appointment Safety" --department-id DEPARTMENT_ID --created-by-user-id ADMIN_USER_ID --content-file PATH uv run --frozen hc ams policies update --environment dev --tenant-id TENANT_ID --policy-id POLICY_ID --content-file PATH
The file is read locally, before the login check and any request, by the same reader the sessions commands use: it must be a readable owner-only regular text file (no symlinks, no directories, not group- or world-readable) and must hold 1-20000 characters. Its content is never printed, and an invalid, empty or oversized file is refused locally with a message that names the discipline, never the text. The output is identical to the inline form:
policies.create/policies.updatewithdata.policy. -
Exactly one content source is accepted per write: passing
--contentwith--content-fileis a usage error (exit 2) that sends nothing. The inline--contentflag remains supported for convenience and remains exposed in argv, the process table and shell history — use the file channel for anything sensitive. An empty--content ""onupdateis still the documented clear; an empty--content-fileis avalidationrefusal, so a truncated or misdirected file can never clear protected content by accident. -
updatesends only the options you pass (an empty--description ""or--content ""clears it;--clear-guardrail-idssends an explicit empty list to clear the policy's guardrail bindings); it refuses with exit 1 (validation) when no field option is given. -
activate/deactivatePUTactive: true|falseand succeed only when the readback confirms the requested flag. -
deletesucceeds withdata: {"deleted": true}(the server answers 204 with no body) and is irreversible. If the server refuses with 409, the CLI reports oneconflictrefusal naming the policy; no changes were made. -
Any other 409 on
create,update,activateordeactivateis one write-wordedconflictrefusal (naming the policy where one was given) that says the server refused the write and to review the policy's current server state before retrying; no changes were made. Writes are never refused with the read-era conflict wording. -
A 404 for the requested policy is a
not_foundrefusal naming the ID (oncreate, a 404 names the referenced--department-id); a target/tenant mismatch on a write readback is avalidationrefusal that reports the landed write truthfully: it names the policy and the tenant that actually received it and points tohc ams policies get— it never claims a landed write was stopped. -
If the transport times out, the connection drops mid-write, or the server answers an HTTP 5xx/408 before a readable result, the write's outcome is unknown: the CLI exits 1 with an
unknownenvelope (verification.saved_state: unknown,verification.side_effects: unverified,data.mutation_replayed: false, anddata.reconciliation.status: not_read) whose message says the outcome is unknown and to checkhc ams policies getbefore retrying. It never re-sends the write and never re-reads on its own.
Governed authoring sessions and their messages are first-class commands over the
VibeCoder session routes. Creating a session and appending a message make no model
call; they only record authoring state. Sessions are tenant- and user-scoped by the
server, newest first, and expired sessions are not returned. --limit is the only
pagination the server offers (sessions default 50, maximum 100; messages default
100, maximum 200) — there are no offsets or cursors, and a limit outside that range
is refused locally:
uv run --frozen hc ams sessions list --environment dev --tenant-id TENANT_ID [--limit N]
uv run --frozen hc ams sessions get --environment dev --tenant-id TENANT_ID --session-id SESSION_ID
uv run --frozen hc ams sessions create --environment dev --tenant-id TENANT_ID [--agent-id AGENT_ID] [--mode plan|implement] [--initial-prompt TEXT | --initial-prompt-file PATH]
uv run --frozen hc ams sessions messages list --environment dev --tenant-id TENANT_ID --session-id SESSION_ID [--limit N]
uv run --frozen hc ams sessions messages add --environment dev --tenant-id TENANT_ID --session-id SESSION_ID [--content TEXT | --content-file PATH] [--mode plan|implement] [--idempotency-key KEY]
-
listemitsoperation: "sessions.list",data.sessions(bounded projections of session ID, agent ID, operation, mode, status and audit timestamps) and apageblock ({"kind": "limit", "limit": N, "returned_count": N, "continuation": null}).getemitsoperation: "sessions.get"anddata.session. The projections never include the session's protectedinitial_prompt, tenant or user identity, or arbitrary response fields. -
createandmessages addrequire a savedhc loginsession (env-var credentials are not accepted for writes). Each write is sent exactly once and the envelope carries the server's authoritative readback:operation: "sessions.create"withdata.session, andoperation: "sessions.messages.add"withdata.message(message ID, role, mode, plan ID, model, timestamps) plusdata.idempotency_keywhen a key was supplied. Protected free text —--initial-promptand--content— is sent to the server but never appears in the envelope, a refusal, a diagnostic or a log. -
The protected free text can also arrive from an owner-only file, which keeps it out of the command line entirely (argv, the process table under
ps//proc/*/cmdline, shell history and CI logs all see only the path):uv run --frozen hc ams sessions create --environment dev --tenant-id TENANT_ID --initial-prompt-file PATH uv run --frozen hc ams sessions messages add --environment dev --tenant-id TENANT_ID --session-id SESSION_ID --content-file PATH
The file is read locally, before the login check and any request, by the same reader
hc ams sessions plans generate --prompt-fileuses: it must be a readable owner-only regular text file (no symlinks, no directories, not group- or world-readable), and must hold 1-20000 characters — the same bound the inline flag is now held to, so neither channel can carry an empty or over-long value past the local check. Its content is never printed, and an invalid, empty or oversized file is refused locally with a message that names the discipline, never the text. The output is identical to the inline form:sessions.createwithdata.session,sessions.messages.addwithdata.message. -
Exactly one source is accepted per field. Passing
--initial-promptwith--initial-prompt-file, or--contentwith--content-file, is a usage error (exit 2) that sends nothing;messages addwith neither is the same usage error. The inline--initial-promptand--contentflags remain supported for convenience, and remain exposed in argv, the process table and shell history — use the file channel for anything sensitive. -
--initial-promptbecomes the session's firstusermessage in the same server transaction;hc ams sessions messages listshows it afterwards. -
--mode implementis not available from the server yet:createreports oneunsupportedrefusal (the server answers 501) and creates nothing. A message whose--modediffers from its session's mode is refused by the server with 409 and reported as one write-wordedconflictrefusal that says a message's mode must match its session's mode and points athc ams sessions get; no message is added, and the read-era conflict wording is never used. -
A missing, expired or other user's session is a
not_foundrefusal naming the session onget,messages listandmessages add; oncreate, a 404 names the requested--agent-id. -
Messages with an
--idempotency-keyare replay-safe: the server answers 201 with the existing message instead of inserting a second one, and the command reports that message (its original ID) — a replay is never reported as a new write, and the command itself never re-sends a write. -
If the transport times out or the connection drops mid-write, the write's outcome is unknown: the CLI reports one
transporterror whose message says so and points athc ams sessions list/hc ams sessions messages listbefore retrying. A write readback that lands in a different tenant is reported truthfully asvalidation, naming the tenant that actually received it — a landed write is never reported as stopped. -
Reads refuse target files, root credentials or base URLs, raw output, blank or dot-segment session IDs, out-of-range limits, and installed SDKs without the session list/get and message list/add methods before tenant-admin login or any read. The existing
hc ams plan|show|apply|restoretuning commands and their signatures are unchanged. -
These session and message commands do not attach files, apply or roll back configuration, or send session history to a model. Plan review is its own command group (below).
Session attachments are three commands over the live VibeCoder attachment routes. There is no download command: the server exposes no attachment content route, so the CLI never fetches, prints or reconstructs a file's bytes:
uv run --frozen hc ams sessions attachments list --environment dev --tenant-id TENANT_ID --session-id SESSION_ID
uv run --frozen hc ams sessions attachments upload --environment dev --tenant-id TENANT_ID --session-id SESSION_ID --file PATH
uv run --frozen hc ams sessions attachments delete --environment dev --tenant-id TENANT_ID --session-id SESSION_ID --attachment-id ATTACHMENT_ID
listemitsoperation: "sessions.attachments.list"anddata.attachments, each a bounded projection ofid,filename,content_type,size_bytes,index_statusandcreated_at. The server offers no pagination on this route, so there is nopageblock and no--limit. The projections never includestorage_key,content_hash, tenant or user identity, or any file content. An agent-backed session lists the agent attachments linked to the session; a session with no agent lists its draft attachments. The server guarantees no ordering, so the CLI claims none.uploadreads--filelocally, reads the session once first, then sends the file exactly once as the multipartfilepart under its bare filename, and reports the server's authoritative readback asoperation: "sessions.attachments.upload"withdata.attachment(the same projection aslist). It requires a savedhc loginsession. The file's bytes are never written to stdout, stderr, an error envelope, a diagnostic or a log; only its name and size appear. An agent-backed session derives the content type from the extension and stores an agent attachment (with an indexing status); a session with no agent stores a draft attachment and accepts any extension.- Before sending,
uploadrefuses a missing or unreadable file and a file larger than 5 MiB without any request: those bounds apply to both paths. The extension allow-list (txt,md,pdf,docx) is the agent path's only, because that path derives the content type from the extension, so it is applied after the session read and only when the session has anagent_id; a draft upload of any other extension is sent, and the server answers. The session read is a separate route, so the upload POST itself is still sent exactly once. These local pre-checks mirror the server's own bounds; they never replace the server's answer. When the server does refuse, its status is reported as sent and never normalised:413(the route's stream cap) and422(the attachment service's size check, an unsafe or blank filename, or an unsupported extension on the agent path) both become onevalidationrefusal naming the status and the server's own detail, and nothing is attached. A missing, expired or other user's session is anot_foundrefusal naming the session. deleteremoves an attachment with a204(no body, so the envelope is built from the request identity, never a fabricated response). It requires a savedhc loginsession and reads the session once first, because the route has two different effects and the wording must be truthful: for an agent-backed session the file is only detached from the session and the agent attachment and its stored object survive (data.effect: "detached"), while a session with no agent has its draft attachment deleted (data.effect: "deleted").dataalso carriesattachment_id, anddetailstates the effect in words. The DELETE itself is sent exactly once. A missing session, or an attachment ID that is not attached to the session, is anot_foundrefusal; nothing is removed.- If the transport times out or the connection drops mid-write, the upload's or
delete's outcome is unknown: the CLI reports one
transporterror saying so and pointing athc ams sessions attachments listfor that session before retrying. It never re-sends automatically;listis the reconciliation step. A refused or failed upload creates no session link, sends no message, generates no plan and makes no model call, and a landed write readback in another tenant is reported truthfully asvalidation. - Attachment commands refuse target files, root credentials or base URLs, raw
output, blank or dot-segment session and attachment IDs, and installed SDKs
without the attachment list/upload/delete methods before tenant-admin login
or any request. Uploads are multipart requests;
APIClient.requestforwardsfiles/datafor them and every existing JSON caller's wire bytes are unchanged.
Exact create/configure plans are five commands over the existing VibeCoder plan routes: two review commands, one send-once apply, one send-once rollback and one read-only reconciliation. There is no approval receipt and no direct agent write:
uv run --frozen hc ams sessions plans generate --environment dev --tenant-id TENANT_ID --session-id SESSION_ID [--operation modify|create] [--agent-type Application|Utility] [--prompt-file PATH] [--idempotency-key KEY] --out PATH
uv run --frozen hc ams sessions plans get --environment dev --tenant-id TENANT_ID --plan-id PLAN_ID --out PATH
uv run --frozen hc ams sessions plans apply --environment dev --tenant-id TENANT_ID --plan-id PLAN_ID --confirm-hash 64_HEX_PLAN_HASH [--expected-config-version N] --confirm
uv run --frozen hc ams sessions plans rollback --environment dev --tenant-id TENANT_ID --plan-id PLAN_ID --expected-config-version N [--reason TEXT] --confirm
uv run --frozen hc ams sessions plans reconcile --environment dev --tenant-id TENANT_ID --plan-id PLAN_ID
generatesends exactly onePOST /vibecoder/sessions/SESSION_ID/planwith the explicit session ID; it makes no preflight read and no other request, no message write, noPUTand no apply. The server runs the planner once. It requires a savedhc loginsession and reportsoperation: "sessions.plans.generate"withdata.plananddata.out.getsends exactly oneGET /vibecoder/plans/PLAN_IDand reportsoperation: "sessions.plans.get"; a reload is immutable, so it returns the sameplan_hashand diff however the session changed afterwards.getis a read and needs no savedhc loginsession.--outis required and must be a new path: the review is written to a newly created owner-only file (mode0600, no symlinks, never overwritten). A refusal removes the reservation again, so a refused review never leaves a file behind.- The review file carries the exact target (
environment,tenant_id,session_id,agent_id— explicitnullfor a creation plan — andplan_id),operation,status,base_config_version(nullfor create),plan_hash,model,summary, the advisoryreview_warningswith their ownseverity,file_actionsas attachment IDs only, and the diff:changeswith each returned field'sbeforeandafterfor a configure plan, ordefinition(name, description, type, model,is_orchestrator, department/team, instructions, greetings, opening suggestions) plusreferences(catalog IDs grouped by department/team/tool/skill/policy/ guardrail/data-source) for a creation plan.plan_json["original_prompt"]is never projected, andwarnings/skipped_referencesare reported as counts, not bodies. - stdout stays bounded and free-text-free: plan ID,
plan_hash, operation, status, base config version, agent ID, model, sorted changed-field names (create: reference counts by kind) and finding counts. No prompt, instructions, greeting, summary, message content or plan value is printed to stdout, stderr, a diagnostic or an error string. - The prompt is protected free text and never comes from argv:
--prompt-filereads one owner-only regular text file (no symlinks, at most 20000 characters) and sends it once.--prompt-fileis optional — the server falls back to the session's initial prompt or last message — and--agent-typeapplies to--operation createonly (withmodifyit is a usage error before login or any request).--prompt-fileis not mirrored as a local "prompt required" rule: a creation plan with no prompt anywhere keeps the server's own422 "a prompt is required for agent creation". - It refuses rather than endorses. A configure plan that changes anything
outside the existing tuning field set (
instructions,greetings) is refused by field name — in particular capability/permission expansion (tool_ids,skill_ids,policy_ids,guardrail_ids,data_source_ids,department_id,team_id,is_orchestrator), lifecycle/status, model and file actions: permission assignment stays a separately reviewed capability. It also refuses a plan whosestatusis notproposed, whoseplan_hashis not 64 hex characters, whosesession_id/tenant_id/operationdiffer from the explicit target, whoseplan_jsoncarries unknown keys, or whose file actions name anything but an attachment ID. Astatus: "invalid"plan is refused instead of reviewed, and itsvalidation_errorsare reported by count and never quoted — that server text can contain protected field values, so read it in the AMS console. Non-advisoryreview findings are refused the same way; advisory findings are displayed in the review file. A creation plan that claims anagent_idis refused, and no existing agent ID is ever fabricated or required. - Server answers are preserved, not replaced: a missing, expired or other
user's session or plan is a
not_foundrefusal naming it, a422from the plan route is avalidationrefusal carrying the server's own bounded detail, and an unavailable planner (503) is atransportrefusal with no file written. A dropped connection ongeneratereports onetransporterror saying the plan's outcome is unknown and points athc ams sessions messages list/plans getbefore retrying; the request is never re-sent automatically. - Both commands refuse target files, root credentials or base URLs, raw output,
blank or dot-segment session and plan IDs, a prompt file that is not a
readable owner-only regular file, and installed SDKs without the plan
generate/get methods before tenant-admin login (or, for
generate, before any request). The existinghc ams plan|show|apply|restoretuning commands and their signatures are unchanged.
Applying, rolling back and reconciling one plan are separate capabilities on the
same routes. The commands never retry, never replay, never send a second
mutation and never fall back to PUT /agents/{id}:
applyrequires a savedhc loginsession,--confirmand the exact 64-hex--confirm-hashfrom the review. It reads the plan once, runs its local pre-checks, sends exactly onePOST /vibecoder/plans/PLAN_ID/applywith the reviewedplan_hash, the version the plan itself carries andconfirm: true, then reads the plan (and the agent, when the plan names one) back. Approving a plan binds exactly what was reviewed: a configure plan whose changes fall outsideinstructions/greetings, or which carries file actions, is refused by field name even though the server would accept it, and a creation plan that claims an agent ID, reports existing-field changes or carries a file write/path action is refused the same way. A plan that is notproposed, carriesvalidation_errors, has blocking review findings, or whose hash no longer matches--confirm-hashis refused before anything is sent.- A configure
applyrequires--expected-config-versionequal to the plan's ownbase_config_version; a mismatch is a local refusal, never a stale send. A creation plan has no baseline (base_config_versionisnull), so--expected-config-versionmust not be supplied: the request sends1only because the pinned route schema requiresexpected_config_version >= 1while the server's creation branch never reads it. That1is a documented protocol filler, not a baseline claim, and the CLI never reports it as evidence. applyreports three evidence sections independently and never collapses them into "applied":data.evidence.saved(the plan reloaded after the write isapplied/publish_failed; for a configure plan the agent'sconfig_versionadvanced by exactly one from the plan's ownbase_config_versionand every reviewed field equals itsaftervalue; for a creation plan the createdagent_idwas read back in this tenant and no version baseline is claimed),data.evidence.side_effects(files areunverifiedbecause the pinned contract exposes no attachment/file readback, and publication isnot_requiredwhen the server reportspublication_status: not_applicable, otherwiseunknown/failed— never "serving"), anddata.evidence.runtime(alwaysunverified, because there is no serving/runtime route).data.mutation_replayedis alwaysfalse.- Exit codes are strict:
0only when the write is provably saved and readback-confirmed (theverificationblock then readssaved_state: confirmed,side_effects: unverified,runtime: unverified). A readback mismatch, a saved-but-unpublished result, or an unknown outcome exits nonzero with the bounded JSON envelope on stderr. applysurfaces the server's own answers and never its free text: a missing plan is anot_foundrefusal naming it; a409names only the structured reason code (plan_hash_mismatch,already_applied,plan_not_applicable,attachments_changed,stale_baseline,concurrent_edit) with bounded local wording; a422is reported by validation-error count only, because that server text can quote protected field values.- Unknown outcome is never success and never a replay. On a transport
failure or any
5xxfrom/apply(the mutation may have committed) the command sends nothing further, recordsoutcome: "unknown", runs the same read-only reconciliationreconcileperforms, prints it together withmutation_replayed: false, and exits nonzero telling the operator to inspect before acting. The only supported follow-up isplans reconcile, orplans rollbackonce the state is known. rollbackrequires a savedhc loginsession,--confirm,--expected-config-versionequal to the agent's currentconfig_version, and reads the plan and agent first. It requires the plan to be an applied configure plan (statusappliedorpublish_failed, with anagent_id); a mismatch is refused locally, never sent. It then sends exactly onePOST /vibecoder/plans/PLAN_ID/rollback(the pinned request schema requiresreason, so--reasonis sent as a bounded string,""when omitted, and is never echoed), reads both back, and reports the same three evidence sections.--reasonis protected free text: it never reaches stdout, stderr, a diagnostic or an error string.- Rollback is not restore and neither is deletion recovery.
hc ams restoreis the tuning contract's selected-field restore: receipt-bound fields put back on the same agent.hc ams sessions plans rollbackasks the server to revert the fields one applied plan changed, version-checked. A creation plan changed no existing field, so it is refused locally: deleting an agent a creation plan created is a different capability this CLI does not add. The existinghc ams plan|show|apply|restoretuning commands and their signatures, output and receipts are unchanged. reconcileis the read-only recovery path: it sends noPOST, noPUTand noDELETE. It reloads the plan, reads its agent when it names one, and reports the planstatusandplan_hash, theagent_id, the agent'sconfig_version, which planned field values arepresent/absent/other, andmutation_replayed: false; side effects and runtime stayunverified. It is what an operator runs after any uncertain outcome, before any further write.- All three refuse target files, root credentials or base URLs, raw output,
blank or dot-segment plan IDs, an apply/rollback without
--confirm, a malformed--confirm-hash, an out-of-range--expected-config-version, a--reasonlonger than 2000 characters, and installed SDKs without the plan get/apply/rollback methods before tenant-admin login or any request.
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
Reads make exactly one catalog GET after tenant-admin login and do 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 catalog methods before tenant-admin login or catalog reads.
Guardrail writes are first-class, send-once commands that require a saved
hc login session (env-var credentials are not accepted for writes). Each write
is sent exactly once — the CLI never retries a write — and the result envelope
carries the server's authoritative readback of the guardrail (same bounded
projection as reads: never rules, description, tenant identity, or creator
identity). A guardrail has no active flag and no config_version, so there is
no activate/deactivate command and no expected-version option: the server's
write routes carry no If-Match, and the CLI will not advertise a guard the
server does not offer.
uv run --frozen hc ams guardrails create --environment dev --tenant-id TENANT_ID --name NAME --created-by-user-id ADMIN_USER_ID [--description TEXT] [--rules-file RULES_JSON_FILE]
uv run --frozen hc ams guardrails update --environment dev --tenant-id TENANT_ID --guardrail-id GUARDRAIL_ID [--name NAME] [--description TEXT] [--rules-file RULES_JSON_FILE]
uv run --frozen hc ams guardrails delete --environment dev --tenant-id TENANT_ID --guardrail-id GUARDRAIL_ID --confirm
createsucceeds withoperation: "guardrails.create"anddata.guardrail= the server's 201 readback.--nameand--created-by-user-idare required by the server contract; the tenant is taken from the saved session's authenticated admin, never from a flag.--rules-filenames a regular JSON file holding the rules object with string keys. Rules never ride argv (so they stay out of the process list) and are never echoed: an unreadable, symlinked, duplicate-keyed or non-object file is refused with one fixed message that does not quote its content. Rules are write-only — they are sent but never appear in any command output, error message or readback.updatesends only the options you pass (an empty--description ""clears it; a--rules-fileholding{}sends an empty rule set); it refuses with exit 1 (validation) when no field option is given.deleteis a reviewed one-shot destructor and requires--confirm; without it the command exits 2 before login and sends nothing. With it the CLI makes exactly oneGETfor the guardrail, oneGET /agentsand oneGET /policiesto compute the affected references, prints the resolved target, those references and the disclosure block to stderr (pretty mode only;--output json|rawkeeps stderr machine-parsable), sends exactly oneDELETE, then makes exactly one confirmationGET. Only a 404 there proves the deletion: the command reportsdata.deleted: trueandverification.saved_state: confirmedfor a 404,data.deleted: falsewithsaved_state: failedwhen the guardrail is still served, andoutcome: unknownwithdata.mutation_replayed: falseand anot_readreconciliation when the answer is 5xx or the transport fails. It never replays, retries or re-reads on its own, and it never claims a restore:hc ams restorereplays tuning fields onto an existing agent and can never restore a deleted guardrail.- The server guards one reference only: an agent whose
guardrail_idscontain the guardrail answers 409 and nothing is deleted (the CLI reports oneconflictrefusal). A policy whoseguardrail_idsstill name it is NOT guarded and is not repaired, so a later agent configuration read that resolves that policy fails; the disclosure says so, and the printed affected references name every policy that still points at the guardrail. When the agent or policy catalog cannot be read, the delete is refused (nothing was changed) rather than executed without its disclosure. - Any other 409 on
createorupdateis one write-wordedconflictrefusal that says the server refused the write and to review the guardrail's current server state before retrying; no changes were made. - A 404 for the requested guardrail on
updateis anot_foundrefusal naming the ID; a target/tenant mismatch on a write readback is avalidationrefusal that reports the landed write truthfully: it names the guardrail and the tenant that actually received it and points tohc ams guardrails get. - If the transport times out or the connection drops mid-write, the write's
outcome is unknown: the CLI reports one
transporterror whose message says the outcome is unknown and to checkhc ams guardrails getbefore retrying. It never re-sends the write on its own.
Read-only tool catalog listing and inspection are complete and unpaged. The bounded projection includes only IDs, names, read-only and confirmation flags, agent types, required scopes, audit events, and activity labels:
uv run --frozen hc ams tools list --environment dev --tenant-id TENANT_ID
uv run --frozen hc ams tools get --environment dev --tenant-id TENANT_ID \
--tool-id TOOL_ID
When both target flags are omitted, these commands may use the matching saved tenant-admin session. Explicit flags must match that session. Tool output never includes descriptions, parameters, input schemas, PIP or connector routing, or arbitrary response fields. The CLI does not execute, assign, create, update, or delete tools; join agents or skills; or claim assignment, availability, authorization, deployment, serving, or runtime effectiveness. It makes exactly one catalog GET after tenant-admin login and does not paginate, retry, cache, join, or infer additional data. Tool reads refuse target files, root credentials or base URLs, raw output, blank or dot-segment IDs, and installed SDKs without both tool methods before tenant-admin login or catalog reads.
Read-only data-source catalog listing and inspection are complete and unpaged. The bounded projection includes only stable IDs and names:
uv run --frozen hc ams data-sources list --environment dev --tenant-id TENANT_ID
uv run --frozen hc ams data-sources get --environment dev --tenant-id TENANT_ID \
--data-source-id DATA_SOURCE_ID
When both target flags are omitted, these commands may use the matching saved tenant-admin session. Explicit flags must match that session. Data-source output never includes descriptions or arbitrary response fields and does not imply access, patient consent, record availability, assignment, authorization, or runtime effectiveness. The CLI does not create, update, delete, assign, access records through, or execute data sources. It makes exactly one catalog GET after tenant-admin login and does not paginate, retry, cache, truncate, join, or infer additional data. Data-source reads refuse target files, root credentials or base URLs, raw output, blank or dot-segment IDs, and installed SDKs without both data-source methods before tenant-admin login or catalog reads.
AMS output modes
The read commands (hc ams skills|tools|policies|guardrails|data-sources|teams|departments list|get
and hc ams organization hierarchy) render in two modes (--output on the root
hc command; pretty is the default):
pretty(default): a compact human view. Lists print anID/NAMEtable with an entry count; a single record printskey: valuelines; the organization hierarchy prints an indented tree. Each failed AMS command prints one stderr line,error: <message> (<category>)(flag/argument usage errors from Click print Click's standard usage message instead).json: the stable result envelope (below) on stdout. When stdout is not a terminal, the envelope is printed as one compact line; on a terminal it is indented. Errors keep the structured JSON envelope on stderr.
The JSON envelope carries schema_version, operation, target, outcome,
and either data (succeeded) or error: {category, message} (failed). On
read-only operations the envelope no longer includes the verification block:
every field there is not_applicable on a read, so it was boilerplate. If a
future mutating operation reintroduces it, verification reappears only with
non-not_applicable content. Everything else about the envelope — field names,
ordering semantics, categories — is unchanged and stays parseable.
--raw/--output raw stays refused for AMS (Raw output is refused for AMS.),
and refusals keep the JSON error envelope on stderr.
hc ams skills list --environment dev --tenant-id TENANT_ID # pretty table
hc ams skills get --environment dev --tenant-id TENANT_ID --skill-id SKILL_ID # key: value
hc --output json ams skills list --environment dev --tenant-id TENANT_ID # compact envelope
hc --output json ams skills list --environment dev --tenant-id TENANT_ID | jq .data
What hc ams errors report
In json and raw modes each failed AMS command prints one JSON object on stderr with
an error.category and a message naming the real cause; in pretty mode the
same message is exactly one stderr line, error: <message> (<category>):
- Local refusals keep their specific message and exit
1with categoryvalidation:Raw output is refused for AMS.,AMS target does not match the saved session; stopped before authentication., identity mismatches (Skill/tenant identity mismatch; stopped.), and dot-segment ID refusals. - No saved session and no target flags: category
authenticationwithNot logged in; run \hc login --environment --tenant-id `.` - A
getwhose requested ID does not exist (HTTP 404): categorynot_foundnaming the ID, e.g.Skill 'nosuch' was not found.(a 404 onliststaysvalidation; departments keeps its legacy contract for all read statuses, while department write 404s arenot_foundrefusals naming the ID). - HTTP 401/403 map to
authentication/authorization; 409 toconflict; network failures totransport; local output failures tolocal_io. - Any unexpected internal error is category
internalwith a generic message; it is never labeledvalidationand never leaks exception details.
hc --raw ams skills list --environment dev --tenant-id TENANT_ID # validation: raw refused
hc ams skills list --tenant-id OTHER_TENANT # validation: target mismatch
hc ams skills list # authentication: not logged in
hc ams skills get --skill-id NOSUCH # not_found: names the 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.
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. Those three local packages keep one
version across the stacked release series, so the install passes
--refresh-package for each of them: without it uv can restore a cached wheel
built from an earlier commit and the suite silently exercises old code.
Negative journeys exercise denied login, identity/qualification/plan rejection, malformed responses, failed readback and uncertain writes without mutation replay.
The journey suite journals itself as it runs: the output directory holds
uv/journeys.json (the ordered journey list), uv/progress.jsonl (each
completed journey, flushed) and uv/journeys/ (per-journey results and
diagnostics). If the suite hits its timeout, the run adds uv/timeout.json plus
a console summary naming the journeys that were in flight, so the retained
evidence is never an empty directory that cannot say where the run stopped.
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.
Metadata
Release files for healthcloud-cli 3.7.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| healthcloud_cli-3.7.1.tar.gz | 231.7 kB | With provenance | Details for healthcloud_cli-3.7.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| healthcloud_cli-3.7.1-py3-none-any.whl | Python 3 | none | any | Details for healthcloud_cli-3.7.1-py3-none-any.whl |
Total release size: 476.2 kB
Release files / healthcloud_cli-3.7.1.tar.gz
| Download URL | healthcloud_cli-3.7.1.tar.gz |
|---|---|
| Size | 231.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2080ba0427c7cc4d6d464ea15bbac0bd5c6b0b2b6e27b7fed87cc46b7a6c2fad
|
|
BLAKE2b-256 checksum How to use checksums |
a0a5d3ead55b3d47bf2da3e7a2caff99058a548e54e3d6b13ccbe349050b085f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.
Transparency logRelease files / healthcloud_cli-3.7.1-py3-none-any.whl
| Download URL | healthcloud_cli-3.7.1-py3-none-any.whl |
|---|---|
| Size | 244.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
832e234d5e17a1cdd89a6b33cbc11281b86cbbbf02f701b12c9d36961dfe7142
|
|
BLAKE2b-256 checksum How to use checksums |
b1c2cb20703a53d574eba3106dba7e1a142e79c5510e7ba5214b95211348d891
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.
Transparency logSecurity for healthcloud-cli 3.7.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for healthcloud_cli-3.7.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.