Skip to main content

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, health-services, schedules, tools -- plus read-only agent operations, and the utility-agent runs/actions they produce). 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.

Selecting an AMS API URL

Pass --api-url after ams to select a different AMS deployment without changing SDK defaults or DNS:

uv run --frozen hc ams --api-url https://dev-ams-services.health.cloud/api/ams \
  agents list --environment dev --tenant-id careco

The value is the full HTTPS service base URL, including /api/ams when that is the service path. A trailing slash is normalized. Without this option, the existing environment-derived URL is used. The option applies to AMS discovery, reads and writes; it does not change the tenant-admin login/refresh endpoint or the saved session's environment and tenant. Root --base-url is for MCP and remains separate. Use root --verbose to show the selected override on stderr; JSON results remain on stdout.

For tuning commands, the target file's api_origin must match the selected URL's origin. New override-based receipts bind the full URL, including its path: repeat the same option for show, apply and restore. Changing the endpoint or dropping the option requires a new reviewed plan; existing default receipts remain bound to their original default configuration. Embedded credentials, query strings, fragments and ambiguous paths are refused. TLS verification stays enabled and redirects are not followed.

The local ui launcher supports only the /api/ams service path because the existing frontend appends that path itself; it refuses custom API paths before launching. This option does not update deployed web clients.

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.

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

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

Bulk input: --input / --stdin

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

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

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

hc mcp call -- generic escape hatch

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

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

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

Output modes

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

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

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

Exit codes

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.

By default (pretty) these three commands print readable lines — never a raw JSON blob and never a token:

$ hc login --environment dev --tenant-id TENANT_ID
saved session: dev / TENANT_ID
email: admin@example.test
expires_at: 2026-11-02T01:42:29Z
$ hc logout
saved session removed: true
server session revoked: false

hc login --status prints the same three lines for the saved session, and a second hc logout reports saved session removed: false. --output json (and --output raw, which these commands treat as JSON) prints exactly the objects they have always printed: {"schema_version": 1, "ok": true, "session": {"schema_version": 1, "environment", "tenant_id", "email", "expires_at"}} for login/--status, and {"schema_version": 1, "ok": true, "removed": true|false, "server_session_revoked": false} for logout.

For CI and agents, log in non-interactively: pass --email and pipe the password to --password-stdin (read as exactly one stdin line, never printed by the CLI, 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. On supported POSIX terminals, --password-stdin suppresses terminal echo while the single line is read and restores it afterwards. When suppression is unavailable (including Windows consoles), or stdin's interactivity cannot be determined, it warns on stderr before reading that the terminal may display the password. Noninteractive pipes do not need suppression and stay quiet. Login failures exit 1 on stderr: HTTP 401 is Tenant-admin login rejected (HTTP 401); no session was saved., HTTP 403 is not authorized, and other HTTP failures include their observed status. Connection and timeout failures say Tenant-admin login connection failed; no session was saved. Local session-storage failures keep their own message. Error output omits raw server responses and credentials; a failed login preserves any previously saved session. 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 login session — the session token is attached to the SDK before the call; without a session the command refuses with "run hc login before registering a tenant" and makes no network call. --environment must match the saved session's environment.
  • --tenant-id is 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, with terminal echo handling as described above). There is no --password flag, and the CLI never prints or logs the password.
  • Output: a tenants.register envelope with the tenant ID, status, tier, admin ID and email_otp_sent, plus a next-step hint pointing at hc 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 login session is required: the emailed OTP is the proof, and no bearer token is sent.
  • --tenant-id is validated locally (lowercase a-z only) before any network call; --email and --otp must be nonblank.
  • verify-email output: a tenants.verify-email envelope 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_verified is true only when the service answers verified: true; any other answer reports false.
  • resend-code output: a tenants.resend-code envelope whose sent is true only when the service explicitly returns email_otp_sent: true. This reports the service's answer; it does not verify email delivery.
  • 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 login session; the session's tenant is always the target (there is no --tenant-id flag). Without a session the command refuses with "run hc login before managing tenant admins" and makes no network call. --environment (optional) must match the saved session's environment.
  • create adds 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 --password flag and the password is never echoed or logged. Its success envelope carries the new admin_id, email_otp_sent and a next-step hint pointing at hc tenants verify-email. A 409 is reported as "A tenant admin with this email already exists for the tenant".
  • list and get are read-only, unpaged and bounded: each admin is projected to id, name, email, status and is_primary only — never phone numbers, Cognito subs, permissions or audit fields. list emits data.admins plus an unpaged page block; get emits data.admin. Both omit the verification block, like every read.
  • Failures are the shared bounded error envelopes: not-found (get on an unknown ID), conflict (duplicate email on create), 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

To discover the selected public entry for an AMS V2 tenant, pass --api-url, --environment, --tenant-id, and --origin explicitly. Use the HTTPS service URL, including its deployed base path, with a TLS certificate trusted by the SDK. If the service uses a private CA, set SSL_CERT_FILE to its trusted CA bundle. Copy the exact HTTP(S) origin from the service's allowlist.

uv run --frozen hc ams --api-url https://ams-v2.example.test/api/ams \
  discover --environment dev --tenant-id TENANT_ID --origin https://approved-app.example.test

V2 discovery returns the selected entry in candidates.public, omits candidates.orchestrator, and leaves selected_agent set to null. It runs without a saved session and requires a matching Python SDK that provides ams.get_public_agents_for_tenant. Omit --origin for V1 discovery, which supports the existing SDK minimum.

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. Read failures are classified by what the request read, not by its status code alone. A missing agent is not_found whether the server answers HTTP 404 or a 200 that carries no record at all — a literal null, or a body-less 200 or 204 (the transport returns the same nothing for all three, so the CLI cannot tell them apart and does not pretend to). Each of these missing-record responses uses the same message, Agent '<agent_id>' was not found., including the identity read before an export. A 200 that is something else entirely (a non-JSON body, or an object without id/tenant_id) stays validation, because that is a bad response rather than a missing record, and a body naming a different agent or tenant keeps the "Agent/tenant identity mismatch" refusal. A 404 on agents list is not not_found either: a route that does not serve the collection is a route-level failure and stays validation. export re-reads the agent before it exports, so a missing agent already 404s at that read and is not_found. A 404 from the later /agents/{agent_id}/configuration/export request is reported as unsupported: the refusal states that the identity read passed in this run and the export request answered HTTP 404. The export route or configuration may be unavailable, or the agent may have changed or been removed between requests. Run hc ams agents get to check its current state. An empty or whitespace-only successful export response also reports unsupported and leaves no file; its message describes the empty response without claiming a 404 or current agent existence. The SDK raises healthcloud.errors.EmptyConfigurationExportError (also a ValueError for compatibility). Invalid UTF-8 remains a distinct validation failure, and the agent identity read keeps its existing not_found behavior. The --target-file refusal is decided before the saved session is resolved, so hc ams --target-file <f> agents list|get|export with no flags says "requires explicit environment/tenant flags, without a target file" rather than "Not logged in"; the agents write commands still resolve the session first. 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, where its 404 is reported as the unsupported refusal described above and no file is left behind:

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 an agent the tenant does not have — an HTTP 404, or a 200 with a null or empty body — 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."}}

The agent model catalog is one unpaged, read-only command. It lists the model IDs the server suggests for agent configuration and marks the server's default:

uv run --frozen hc ams agents models --environment dev --tenant-id TENANT_ID

--output pretty (the default) prints two columns, ID and DEFAULT, in the server's order with an entry count ((no entries) for an empty catalog); --output json puts the same rows under data.models as {"id": MODEL_ID, "default": true|false} plus an unpaged page block. The list is never sorted, deduplicated or padded, and default is the server's own choice, not a client heuristic. The catalog is advisory: the server accepts model IDs that are not in it, so it is not a validation rule and the CLI does not check an agent's configured model against it. The command makes exactly one GET /agents/models after tenant-admin login, and is read-only: no --confirm, no idempotency key, nothing is ever sent. It refuses target files, root credentials or base URLs, raw output, and installed SDKs without list_agent_models (checked before the tenant-admin login). The catalog route names no record, so a 404 here is a route-level validation refusal, never not_found; a 2xx with no body at all, an empty body, a literal null or a 204 is also validation, with a message saying no catalog was inferred — an unreadable answer never becomes an empty or invented catalog.

Agent lifecycle changes are two first-class, send-once write commands. They require a saved hc login session (the command refuses before any request when none is saved; env-var credentials are not accepted here) and the --confirm acknowledgement. --expected-config-version is optional:

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.

data.config_version_check says which concurrent-edit check actually ran: matched (the read config_version equals --expected-config-version), not_run (the flag was omitted, so no version check ran and the reviewed target plus --confirm are the approval), never a silent success. It is carried on the confirmed, refused and unknown envelopes alike, so an outcome where the write may already have committed still says which check ran. A deployment whose agent payload omits or nulls config_version cannot honour the flag: the command refuses that flag with a way forward (Re-run without --expected-config-version) instead of refusing every lifecycle command forever and instead of interpolating a Python None repr.

Default pretty output prints those facts as labelled lines — transition, requested, config_version_check, evidence (saved, side_effects, runtime), eligibility, mutation_replayed: false — and closes with a verification: block, so a deactivate reads transition: deactivate, then evidence: / saved: / status: confirmed, then verification: / saved_state: confirmed, side_effects: unverified, runtime: unverified; it is never one raw JSON line. --output json prints the full envelope above, byte-identical to before. An unknown outcome still prints its one-line error: plus the reconciliation on stderr.

Without --confirm the command is a preview: it re-reads the agent exactly once (the same one bounded GET), runs the same local pre-checks, prints preview: --confirm was not passed, so nothing has been sent. and then the resolved change to stderr — the target (agent_id, name, type, config_version), status and active before -> after, and one PUT /agents/{agent_id} with body keys: status, active — and, after a successful preview, exits 2 having sent nothing. Login, target resolution, preflight or preview-read failures exit 1; interruption exits 130. With --confirm the write path is unchanged: it re-reads before the single PUT, so a preview is never an approval token. The preview text is suppressed under --output json/raw (the same rule the confirmed path's review follows). The final exit-2 refusal is plain Click usage-error text on stderr, including in JSON mode; it has no JSON envelope. AMS commands refuse --output raw before making requests; use --output json for structured output.

Pre-checks refuse with exit 1 and no write: 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 — all of these are also enforced by the preview, which still sends nothing. A missing --confirm exits 2 only after a successful preview. An active value the server emits as 1/0/"true"/"false" is interpreted as a flag (an already in-effect state is still recognised and a correct write is still confirmed); any other value is unconfirmed, never a false success. 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, a 5xx/408 from the PUT, or an interrupt (Ctrl-C) during the PUT or the readback 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" (attempted once; the request may not have been sent and its saved state is unverified), never an internal error and never a success.

A non-5xx rejection of the PUT (409, 422, 400, 403, …) is worded as a write that the server refused, never as a read: outcome: "failed", verification.saved_state: "failed", mutation_replayed: false, the pre-write state under data.evidence.saved.before, and a reconciliation saying the CLI did not re-read. A 2xx body that is not an agent object at all (for example a plain-text body) is a bounded validation refusal with the same verification: not_applicable as any read, never an AttributeError and never a traceback.

The saved-session requirement above is enforced by the shared AMS authentication path. These writes refuse a missing or mismatched session at authentication, even if an earlier command check succeeded. Environment credentials cannot substitute for a saved session in this mode. Read commands keep their existing environment-credential fallback.

Capability and organization assignments are one first-class, send-once write command. It requires a saved hc login session (the command refuses before any request when none is saved; env-var credentials are not accepted here) and the --confirm acknowledgement of the target and the printed reviewed diff. --expected-config-version is optional:

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.

Default pretty output prints the same facts as labelled lines: agent_id, changed (each field with before/after/added/removed), config_version: {before, after}, evidence (saved, side_effects, runtime), mutation_replayed: false, and a closing verification: block. --output json prints the full envelope described here, unchanged.

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.

Without --confirm the command is a preview: it reads the agent exactly once (the same one bounded GET), computes the same reviewed diff and runs the same local pre-checks, prints preview: --confirm was not passed, so nothing has been sent. followed by the reviewed diff, and, after a successful preview, exits 2 having sent no PUT. Login, target resolution, preflight or preview-read failures exit 1; interruption exits 130. With --confirm the write path is unchanged: it re-reads before the single PUT, so a preview is never an approval token. Both renderings stay human: the preview text is suppressed under --output json/raw because it accompanies a usage refusal (plain Click usage-error text on stderr, with no JSON envelope), and the confirmed review is suppressed the same way, like the lifecycle review. In those modes the reviewed diff is carried in the envelope under data.changed instead, so a scripted caller reads the diff from the envelope and never from stderr. agents delete is the one exception: its confirmed review prints in every mode, because it is the acknowledgement of an irreversible hard delete rather than a reversible field write.

Option validation refuses with exit 2 and no write when no assignment option is given or the same family is both set and cleared. Pre-checks refuse with exit 1 and no write for 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 — all of these are also enforced by the preview, which still sends nothing. A missing --confirm exits 2 only after a successful preview. 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.

data.config_version_check reports matched when an explicit version equals the usable integer version read before the PUT, or not_run when the flag is omitted. An explicit check against a missing, null or non-integer version is refused before the PUT, with instructions to omit the flag or repair the version. Omitting it allows those deployments to use assignments, but provides no local concurrent-edit check. Every sent-write outcome carries this check record; the request body still contains only changed references.

A transport error, 5xx/408 from the PUT, or an interrupt during the PUT or its readback 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.

A definite HTTP refusal of the PUT is a sent-write failure, with verification.saved_state: "failed", the pre-write references, mutation_replayed: false and a not_read reconciliation. It is never described as a failed read. An interrupt before the PUT remains a read cancellation (exit 130) and sends no mutation.

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 (the command refuses before any request when none is saved; env-var credentials are not accepted here) 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
# the same acknowledgement, bound to the id being destroyed:
uv run --frozen hc ams agents delete --environment dev --tenant-id TENANT_ID \
  --agent-id AGENT_ID --confirm AGENT_ID

--confirm is required. It accepts the bare flag or the AGENT_ID being deleted; a value that does not match --agent-id is refused (exit 2) before any request, so a replayed acknowledgement cannot destroy a different agent. The refusal names both spellings. This binding belongs to agents delete only — the lifecycle and assignment --confirm flags stay plain acknowledgements.

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 in every output mode, so a scripted --output json caller approves the record and the disclosure it was actually shown rather than a phrase it never saw. --output pretty renders the same block unchanged; --output raw is refused for every AMS command, so json is the machine mode this command renders in. The same disclosure is carried under data.disclosure in the envelope (irreversible, generated_file, dependency_guard, restore, authorization, recovery_trail, review_staleness), 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 409 and 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 restore cannot restore a deleted agent (it replays tuning fields onto an existing agent). Export the configuration first with hc ams agents export if you may need it;
  • the route needs an authenticated tenant user only: no admin/role check is applied;
  • --confirm approves the pre-read snapshot printed above, not the row the server destroys: the route has no If-Match or version precondition, so a concurrent recreate or configuration change between that read and the DELETE is not detected and a different record can go. A 404, or a 2xx with no body, from the confirmation read is read as absence, and the error body cannot distinguish absence from a mid-operation authorization or scope change;
  • 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. A 404 from that confirmation read proves the row is gone, and so does a 2xx with no body (see below); a 404 is the only answer that also pins the status. 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.

Default pretty output prints the result as labelled lines next to the stderr disclosure: agent_id, deleted: true, target, disclosure, evidence (deleted/side_effects/runtime), mutation_replayed: false, and a closing verification: block. --output json prints the full envelope on stdout, unchanged and on stdout alone. Because the review also goes to stderr in json mode, a failing confirmed delete prints that review followed by the one error envelope on stderr: parse stdout for the success envelope, and take the envelope from the first { on stderr when the command failed. That recipe holds by construction, not by luck: every server-supplied value the review prints (agent_id, name, type, status, active, config_version) has its braces escaped as \u007b/\u007d, so the review never contains a literal { or } and the first { on stderr always begins the envelope — an agent named beta{"deleted":true} cannot break a scripted caller's parse.

Without --confirm the command is a preview: it reads the agent exactly once (the same one bounded GET), prints preview: --confirm was not passed, so nothing has been sent. plus the resolved destructive target and the whole disclosure block to stderr, and, after a successful preview, exits 2 having sent no DELETE. Login, target resolution, preflight or preview-read failures exit 1; interruption exits 130. With --confirm the sequence above is unchanged: it re-reads before the single DELETE, so a preview is never an approval token. The preview text alone is suppressed under --output json/raw (it accompanies a plain Click usage-error refusal on stderr, with no JSON envelope); the confirmed path's review is not: it prints to stderr in every output mode, as described above.

Refusals claim nothing and send nothing extra: an agent outside the explicit tenant, the tenant identity mismatch and a delete target that no longer exists are refused before the DELETE (the preview reports the same not_found); 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.

Definitive refusals from the DELETE (400, 401, 403, 404, 405, 409, 422, 429, …) carry the same send-once report: the envelope is outcome: "failed" with verification.saved_state: "failed", the category comes from the status (validation, authentication, authorization, not_found, unsupported, or conflict); other refusals, including 429, 402, 423, 426 and redirects, use validation, data.evidence.deleted.confirmation is not_attempted with confirmation_status: null (no confirmation read was taken), and the message says the delete was sent once, that nothing was replayed, and points at hc ams agents list. It also carries the reconciliation: {"status": "not_read", …} block: this command did not re-read the agent, so a scripted caller can tell it apart from a read-shaped outcome. The 404, 405 and 409 refusals also include the reviewed target and full disclosure, while retaining their missing-agent, method and schedule guidance.

A transport error, a 408 or a 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, and when Ctrl-C interrupts the command after the DELETE is attempted, including the confirmation GET, result handling or SDK cleanup: the interrupt is caught (never swallowed silently), the command still exits non-zero, and it prints the unknown-outcome envelope instead of a plain failure that pretends nothing was sent.

A confirmation read that still returns the agent is outcome: "failed" with data.deleted: false, confirmation: "still_present" and verification.saved_state: "failed", never success. A 2xx body that cannot be read as an agent is also failed, but data.deleted is null and confirmation is unobserved, with wording that says the route still answers this path rather than claiming the agent is still present. A confirmation read that answers 401/403 (or any other non-404, non-2xx status) observed nothing about the row, so confirmation is likewise unobserved and data.deleted is null, rather than claiming the agent is still present. A 2xx with a null or empty body is the opposite case: this server uses a 200 null body to say the agent does not exist (the same answer hc ams agents get reports as not_found), so it proves absence exactly as a 404 does. The envelope is then outcome: "succeeded" with data.deleted: true and confirmation: "not_found" — never a 404 invented to match the wording.

In every one of those non-404 cases confirmation_status is null, and not only when the body is unreadable: the SDK returns None for any response with no content, before it looks at the status, so a 204, a 202 with no body and a 200 with a null body are indistinguishable at the client. A body-bearing 2xx does not pin the code either — 200, 201 and 202 all read back the same way. Only the 404 path can state a status it really observed, so only that path records one.

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"   [--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 | --clear-parent-department] \
  [--key KEY | --clear-key] \
  [--required-eval-suite-ids SUITE_ID ... | --clear-required-eval-suite-ids]
uv run --frozen hc ams departments activate --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 [--confirm]
  • create succeeds with operation: "departments.create" and data.department = the server's 201 readback. --name is required. There is no creator flag: before the write the CLI reads the saved session's own identity (GET /admins/me) and sends it as the server contract's created_by_user_id. The CLI requires that profile's tenant to match the target exactly (a missing tenant is refused) and strips surrounding whitespace from the nonblank admin ID before sending it. This binds this CLI's creator field to the saved session; server-side enforcement for other clients is separate. A failed identity read is a bounded failure and the write is never sent — it is not reported as an unknown outcome. A malformed profile response, including missing required fields, is a validation refusal; response contents and missing-key details are not printed.
  • update sends only the options you pass (an empty --description "" clears it); it refuses with exit 1 (validation) when no field option is given. --clear-parent-department and --clear-key send explicit JSON nulls; --clear-required-eval-suite-ids sends an empty evaluation suite list. Omitted fields stay unchanged, and clears for different fields can be combined. Setting and clearing the same field together refuses with usage exit 2 before session lookup or any request. activate and deactivate mark the department active/inactive. hc ams departments activate is the current spelling; the pre-#867 spelling hc ams departments set-active still works as a hidden alias (same single POST /departments/{id}/activate, same departments.activate envelope) but is no longer listed in hc ams departments --help, so existing scripts keep running while new documentation points at activate. activate is send-once: it refuses (exit 1, authentication, nothing sent) without a saved hc login session, and an uncertain outcome is never replayed.
  • delete --confirm succeeds with data: {"deleted": true} (the server answers 204 with no body) and is irreversible: the CLI keeps no restore. Without --confirm the command is a preview: it reads the department exactly once (one bounded GET), prints preview: --confirm was not passed, so nothing has been sent. plus the resolved target and the disclosure block to stderr, and exits 2 having sent no DELETE. With --confirm the confirmed run makes the same single GET before its single DELETE, and the result envelope is the same, so a preview is never an approval token. These are separate runs: a rename or re-parent between them is reviewed afresh by the confirmed run. There is no If-Match or version precondition, so a change between that confirmed read and the DELETE is not detected. Unconfirmed preview text stays suppressed under --output json/raw (the exit-2 refusal itself is plain text on stderr; see #890). A confirmed JSON-mode delete prints the reviewed target and disclosure to stderr before sending; stdout remains one JSON result on success and is empty on failure. A failed/unknown result follows the review on stderr: parse from its first literal {. Review values escape braces and control characters so they cannot move that boundary.
  • A 404 for the requested department is a not_found refusal naming the ID (on create, a 404 names the referenced department — typically the missing --parent-department-id; on delete, the reviewed read refuses identically and nothing is sent); a target/tenant or identity mismatch is a validation refusal; both exit 1 without changes. The one exception is a tenant mismatch on the create readback: the department has already been created server-side, so the CLI reports a validation refusal that names the department, the tenant that received it, and tells you to run hc 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 unknown envelope (verification.saved_state: unknown, verification.side_effects: unverified, data.mutation_replayed: false, and data.reconciliation.status: not_read) whose message says the outcome is unknown and to check hc ams departments get before 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 activate/deactivate commands:

uv run --frozen hc ams teams create --environment dev --tenant-id TENANT_ID   --name "Escalation Team" --department-id DEPARTMENT_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 ... | --clear-required-eval-suite-ids]
uv run --frozen hc ams teams delete --environment dev --tenant-id TENANT_ID   --team-id TEAM_ID
  • create succeeds with operation: "teams.create" and data.team = the server's 201 readback. --name and --department-id are required. The CLI resolves the creator from the saved session's GET /admins/me identity before sending the write; there is no creator flag or credential fallback. An identity read failure sends no mutation and reports a bounded failure, not an unknown write outcome. The tenant comes from the authenticated admin.
  • update sends only the options you pass (an empty --description "" clears it; --clear-required-eval-suite-ids sends an empty list to clear the required evaluation suites; --key accepts a nonblank key, it cannot be blanked); it refuses with exit 1 (validation) when no field option is given. --required-eval-suite-ids and --clear-required-eval-suite-ids are alternatives: passing both is a usage error (exit 2) and nothing is sent.
  • delete succeeds with data: {"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 one conflict refusal that names the team and says agents reference it; no changes were made.
  • A 404 for the requested team is a not_found refusal naming the ID (on create, a 404 names the referenced department — the missing --department-id); a target/tenant mismatch on an update readback is a validation refusal that reports the landed write truthfully: it names the team and the tenant that actually received it and points to hc 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 unknown envelope (verification.saved_state: unknown, verification.side_effects: unverified, data.mutation_replayed: false, and data.reconciliation.status: not_read) whose message says the outcome is unknown and to check hc ams teams get before 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. Pretty output displays up to 32 department levels and explicitly marks deeper departments as omitted. Use --output json for the full projected hierarchy:

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 activate/deactivate commands:

uv run --frozen hc ams skills create --environment dev --tenant-id TENANT_ID --name "Schedule Lookup" [--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
  • create succeeds with operation: "skills.create" and data.skill = the server's 201 readback. --name is required; the creator is resolved from the saved session's GET /admins/me identity before the write, without a creator flag or credential fallback. An identity read failure sends no mutation. The tenant comes from the authenticated admin. The server does not validate that --tool-ids reference real tools (blank tool IDs are rejected client-side).
  • update sends only the options you pass (an empty --description "" clears it; --clear-tool-ids sends an explicit empty list to clear the skill's tool bindings); it refuses with exit 1 (validation) when no field option is given. --tool-ids and --clear-tool-ids are alternatives: passing both is a usage error (exit 2) and nothing is sent.
  • delete succeeds with data: {"deleted": true} (the server answers 204 with no body) and is irreversible. When AI agents still reference the skill (via their skill_ids), the server refuses with 409 and the CLI reports one conflict refusal that names the skill and says agents reference it; no changes were made.
  • A 404 for the requested skill is a not_found refusal naming the ID (on create, 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 a validation refusal that reports the landed write truthfully: it names the skill and the tenant that actually received it and points to hc 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 unknown envelope (verification.saved_state: unknown, verification.side_effects: unverified, data.mutation_replayed: false, and data.reconciliation.status: not_read) whose message says the outcome is unknown and to check hc ams skills get before 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 [--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
  • create succeeds with operation: "policies.create" and data.policy = the server's 201 readback. --name and --department-id are required. The creator is resolved from the saved session's GET /admins/me identity before the write, without a creator flag or credential fallback; an identity read failure sends no mutation. The tenant comes from the authenticated admin. The server does not validate that --guardrail-ids reference real guardrails (blank guardrail IDs are rejected client-side). --content is 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 --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.update with data.policy.

  • Exactly one content source is accepted per write: passing --content with --content-file is a usage error (exit 2) that sends nothing. The inline --content flag 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 "" on update is still the documented clear; an empty --content-file is a validation refusal, so a truncated or misdirected file can never clear protected content by accident.

  • update sends only the options you pass (an empty --description "" or --content "" clears it; --clear-guardrail-ids sends an explicit empty list to clear the policy's guardrail bindings); it refuses with exit 1 (validation) when no field option is given. --guardrail-ids and --clear-guardrail-ids are alternatives: passing both is a usage error (exit 2) and nothing is sent.

  • activate/deactivate PUT active: true|false and succeed only when the readback confirms the requested flag.

  • delete succeeds with data: {"deleted": true} (the server answers 204 with no body) and is irreversible. If the server refuses with 409, the CLI reports one conflict refusal naming the policy; no changes were made.

  • Any other 409 on create, update, activate or deactivate is one write-worded conflict refusal (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_found refusal naming the ID (on create, a 404 names the referenced --department-id); a target/tenant mismatch on a write readback is a validation refusal that reports the landed write truthfully: it names the policy and the tenant that actually received it and points to hc 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 unknown envelope (verification.saved_state: unknown, verification.side_effects: unverified, data.mutation_replayed: false, and data.reconciliation.status: not_read) whose message says the outcome is unknown and to check hc ams policies get before retrying. It never re-sends the write and never re-reads on its own.

For departments, teams, skills and policies, a DELETE response rejected by the SDK for unexpected content is also an unknown write outcome. Deletion may have completed: data.deleted is null, mutation_replayed is false, and reconciliation.status is not_read. The CLI sends no retry or follow-up read; inspect the domain's list command before deciding whether to retry. A normal empty response keeps the existing successful result.

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]
  • list emits operation: "sessions.list", data.sessions (bounded projections of session ID, agent ID, operation, mode, status and audit timestamps) and a page block. These routes page with a limit only, so the block always says which limit was in force: with --limit N it is {"kind": "limit", "limit": N, "returned_count": N, "continuation": null}, and without it the server's own default page was applied, which the block reports as {"kind": "server_default", "server_default_limit": 50, "returned_count": N, "continuation": null} (50 sessions, 100 messages) — so a truncated page is never mistaken for a complete list. get emits operation: "sessions.get" and data.session. The projections never include the session's protected initial_prompt, tenant or user identity, or arbitrary response fields.

  • Default pretty output prints list as a table with honest headers — ID, AGENT ID, OPERATION, STATUS, EXPIRES AT for sessions and ID, ROLE, MODE, PLAN ID, CREATED AT for messages — followed by an entry count (1 entry / N entries), and (no entries) for an empty list. These projections carry no name, so no NAME column is invented and the id is always shown. get, create and messages add print key: value lines. --output json prints the full envelope exactly as before; pretty output is additive and never changes the envelope.

  • create and messages add require a saved hc login session (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" with data.session, and operation: "sessions.messages.add" with data.message (message ID, role, mode, plan ID, model, timestamps) plus data.idempotency_key — the key the server read back, when the returned message carries one. When the readback does not echo a key, the field is omitted: the envelope never asserts a key→message association the server did not confirm. An --idempotency-key longer than 128 characters (or an empty one) is refused locally with a validation error naming the flag, before anything is sent. Protected free text — --initial-prompt and --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-file uses: 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.create with data.session, sessions.messages.add with data.message.

  • Exactly one source is accepted per field. Passing --initial-prompt with --initial-prompt-file, or --content with --content-file, is a usage error (exit 2) that sends nothing; messages add with neither is the same usage error. The inline --initial-prompt and --content flags remain supported for convenience, and remain exposed in argv, the process table and shell history — use the file channel for anything sensitive.

  • --initial-prompt becomes the session's first user message in the same server transaction; hc ams sessions messages list shows it afterwards.

  • --mode implement is not available from the server yet: create reports one unsupported refusal (the server answers 501) and creates nothing, and a messages add the server answers 501 for is the same unsupported refusal with no message added. Both refusals report the 501 the server actually sent and name implement mode as the documented reason, rather than asserting the requested mode was the cause. A message whose --mode differs from its session's mode is refused by the server with 409 and reported as one write-worded conflict refusal that names the session, mentions a mode mismatch as one possible cause, and points at hc 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_found refusal naming the session on get, messages list and messages add; on create, a 404 names the requested --agent-id.

  • Messages with an --idempotency-key are 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. The envelope echoes the server's read-back key, never a key the server did not confirm.

  • If the transport times out or the connection drops mid-write, the write's outcome is unknown: the CLI reports one transport error whose message says so and points at hc ams sessions list/hc ams sessions messages list before retrying. A write readback that lands in a different tenant is reported truthfully as validation, 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 methods before tenant-admin login or any read. messages list needs only messages.list — the write method add is not required for the read. The writes check their own methods in the same preflight — each command requires exactly the write method it calls, so create refuses an installed SDK without sessions.create and messages add one without messages.add before tenant-admin login and before any read or write, and neither is refused for the write the other command performs. A single-object route whose 2xx body is not a JSON object is refused as a validation error, never reported as an internal failure. The existing hc ams plan|show|apply|restore tuning 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
  • list emits operation: "sessions.attachments.list" and data.attachments, each a bounded projection of id, filename, content_type, size_bytes, index_status and created_at. The server offers no pagination on this route, so there is no page block and no --limit. The projections never include storage_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.
  • upload reads --file locally, reads the session once first, then sends the file exactly once as the multipart file part under its bare filename, and reports the server's authoritative readback as operation: "sessions.attachments.upload" with data.attachment (the same projection as list). It requires a saved hc login session. 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. The CLI supplies text/plain for txt, text/markdown for md, application/pdf for pdf, and the DOCX MIME type for docx, including uppercase extensions. Other draft filenames use application/octet-stream. These types are derived from filenames; the CLI does not inspect file contents.
  • Before sending, upload refuses a missing or unreadable file and a file larger than 5 MiB without any request: those bounds apply to both paths. It also checks the bytes actually read, so a file that grows during the read is refused before any request. 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 an agent_id; a draft upload of any other extension is sent, and the server answers. The extension is the text after the last dot, so a filename such as .txt uses the same txt handling as notes.txt. 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) and 422 (the attachment service's size check, an unsafe or blank filename, or an unsupported extension on the agent path) both become one validation refusal naming the status and the server's own detail, and nothing is attached. A missing, expired or other user's session is a not_found refusal naming the session.
  • delete removes an attachment with a 204 (no body, so the envelope is built from the request identity, never a fabricated response). It requires a saved hc login session and reads the session once first, because the route has two different effects: 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"). This is inferred from the session when checked: data.effect_basis is session_preflight and data.effect_confirmed is false. The session can change between the GET and DELETE, and the DELETE returns no receipt identifying its applied effect. data also carries attachment_id, and detail explains the preflight inference without claiming a confirmed effect. The DELETE itself is sent exactly once. A missing session, or an attachment ID that is not attached to the session, is a not_found refusal; 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 transport error saying so and pointing at hc ams sessions attachments list for that session before retrying. It never re-sends automatically; list is 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 as validation.
  • 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.request forwards files/data for 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
  • generate sends exactly one POST /vibecoder/sessions/SESSION_ID/plan with the explicit session ID; it makes no preflight read and no other request, no message write, no PUT and no apply. The server runs the planner once. It requires a saved hc login session and reports operation: "sessions.plans.generate" with data.plan and data.out. An --idempotency-key that is empty, whitespace-only, or longer than 128 characters is refused locally with a validation error naming the flag, before checking login or sending anything. The same rule applies to sessions messages add; valid keys are sent unchanged. get sends exactly one GET /vibecoder/plans/PLAN_ID and reports operation: "sessions.plans.get"; a reload is immutable, so it returns the same plan_hash and diff however the session changed afterwards. get is a read and needs no saved hc login session: it authenticates like every other session read, with the saved session when there is one and otherwise with the environment's own HC_AMS_ADMIN_EMAIL/HC_AMS_ADMIN_PASSWORD credentials. A refusal is worded for the operation that was refused, so a 422 or 503 on get never claims a plan "was generated": generate says no plan was generated, get says no plan was reloaded.
  • --out is required and must be a new path: the review is written to a newly created owner-only file (mode 0600, 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 — explicit null for a creation plan — and plan_id), operation, status, base_config_version (null for create), plan_hash, model, summary, the advisory review_warnings with their own severity, file_actions as attachment IDs only, and the diff: changes with each returned field's before and after for a configure plan, or definition (name, description, type, model, is_orchestrator, department/team, instructions, greetings, opening suggestions) plus references (catalog IDs grouped by department/team/tool/skill/policy/ guardrail/data-source) for a creation plan. plan_json["original_prompt"] is never projected, and warnings/skipped_references are reported as counts, not bodies.
  • The review file marks the text a model produced: content_origin is "model-generated" and model_generated_fields lists the fields whose values came from the planner — summary, changes.*.why, definition.instructions/greetings/name/description/opening suggestions and review_warnings[].message. Those values are data to inspect before you approve, never instructions to the reader or to an agent that later reads the file.
  • 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.
  • Default pretty output renders generate, get, apply, rollback and reconcile as labelled lines — plan: with the bounded metadata, then evidence: (saved/side_effects/runtime) and mutation_replayed: false where the command reports them, and a closing verification: block for the writes. A write is never printed as a raw JSON blob in the default mode. --output json prints the full envelope, unchanged.
  • The prompt is protected free text and never comes from argv: --prompt-file reads one owner-only regular text file (no symlinks, at most 20000 characters) and sends it once. A file that is too large, missing, unreadable, not UTF-8 text, or not an owner-only regular file is a validation refusal naming the reason and never quoting the text. Ownership is checked differently per platform: on POSIX it is the file's mode and owner; on Windows the opened handle's owner and DACL must grant access to your account only, so a file that inherited a grant to another principal (SYSTEM, Administrators) is refused as not owner-only. Keep the prompt file in a directory only your account can read. --prompt-file is optional — the server falls back to the session's initial prompt or last message — and --agent-type applies to --operation create only (with modify it is a usage error before login or any request). --prompt-file is not mirrored as a local "prompt required" rule: a creation plan with no prompt anywhere keeps the server's own 422 "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 — 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. Unknown plan/agent field names and unendorsed change-field names are reported by count only in review, apply and rollback refusals; their text is never echoed. It also refuses a plan whose status is not proposed, whose plan_hash is not 64 hex characters, whose session_id/tenant_id/operation differ from the explicit target, whose plan_json carries unknown keys, or whose file actions name anything but an attachment ID. A status: "invalid" plan is refused instead of reviewed, and its validation_errors are reported by count and never quoted — that server text can contain protected field values, so read it in the AMS console. Non-advisory review findings are refused the same way; advisory findings are displayed in the review file. A creation plan that claims an agent_id is refused, and no existing agent ID is ever fabricated or required. So is a creation plan whose proposed agent carries a field outside the documented definition and reference set (name, description, type, model, preferred_model, is_orchestrator, department_id, team_id, instructions, greetings, opening_suggestions, opening_suggestions_options, and the catalog *_ids), or whose reference field contains a non-string ID or a list with blank IDs. A blank scalar string contributes no catalog reference; blank department_id and team_id values remain unchanged in the review's definition, so the operator still sees the proposed value.
  • Server answers are preserved, not replaced: a missing, expired or other user's session or plan is a not_found refusal naming it, and an unavailable planner (503) is a transport refusal with no file written. A 422 from the plan route is a validation refusal, but its detail is only quoted when it is a known static contract message that carries no field values — the documented "a prompt is required for agent creation". Any other 422 detail can quote protected field values, exactly like validation_errors and blocking review findings, so it is reported by category only and you read it in the AMS console. A dropped connection on generate reports one transport error saying the plan's outcome is unknown and points at hc ams sessions messages list/plans get before 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 existing hc ams plan|show|apply|restore tuning 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}:

  • apply requires a saved hc login session, --confirm and the exact 64-hex --confirm-hash from the review. It reads the plan once, runs its local pre-checks, sends exactly one POST /vibecoder/plans/PLAN_ID/apply with the reviewed plan_hash, the version the plan itself carries and confirm: 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 outside instructions/ greetings, or which carries file actions, is refused 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 not proposed, carries validation_errors, has blocking review findings, or whose hash no longer matches --confirm-hash is refused before anything is sent.
  • A configure apply requires --expected-config-version equal to the plan's own base_config_version; a mismatch is a local refusal, never a stale send. A creation plan has no baseline (base_config_version is null), so --expected-config-version must not be supplied: the request sends 1 only because the pinned route schema requires expected_config_version >= 1 while the server's creation branch never reads it. That 1 is a documented protocol filler, not a baseline claim, and the CLI never reports it as evidence.
  • apply reports three evidence sections independently and never collapses them into "applied": data.evidence.saved (the plan reloaded after the write is applied/publish_failed; for a configure plan the plan's own agent was read back in this tenant, its config_version advanced by exactly one from the plan's own base_config_version, and every reviewed field equals its after value; for a creation plan the created agent_id was read back in this tenant and no version baseline is claimed), data.evidence.side_effects (files are unverified because the pinned contract exposes no attachment/file readback, and publication is not_required when the server reports publication_status: not_applicable, otherwise unknown/failed — never "serving"), and data.evidence.runtime (always unverified, because there is no serving/runtime route). data.mutation_replayed is always false.
  • Exit codes are strict: 0 only when the write is provably saved and readback-confirmed (the verification block then reads saved_state: confirmed, side_effects: unverified, runtime: unverified — or side_effects: failed when the evidence above reports a failed publication, so one envelope never carries two different side-effect claims). A readback mismatch, a saved-but-unpublished result, or an unknown outcome exits nonzero with the bounded JSON envelope on stderr.
  • apply surfaces the server's own answers and never its free text: a missing plan is a not_found refusal naming it; a 409 names only the structured reason code (plan_hash_mismatch, already_applied, plan_not_applicable, attachments_changed, stale_baseline, concurrent_edit) with bounded local wording; a 422 is reported by validation-error count only, because that server text can quote protected field values; a 400 is worded as an invalid request, never as a missing confirmation, because every apply and rollback this CLI sends already carries confirm: true. --confirm-hash accepts either hex case and is compared case-insensitively against the reviewed plan_hash.
  • Unknown outcome is never success and never a replay. A read-back that fails after the response bound this plan is also an unknown outcome, not a failure: the receipt proved the server accepted the write, so a mismatched readback request (a 5xx, a dropped connection, or an unreadable answer) is reported as outcome: "unknown" with the same reconciliation. When that reconciliation itself cannot be read, data.reconciliation is {"status": "not_read", "detail": …} with a bounded reason — a failed reconciliation never looks like an empty one, and never a bare null. On a transport failure or any 5xx from /apply (the mutation may have committed) the command sends nothing further, records outcome: "unknown", runs the same read-only reconciliation reconcile performs, prints it together with mutation_replayed: false, and exits nonzero telling the operator to inspect before acting. The only supported follow-up is plans reconcile, or plans rollback once the state is known.
  • rollback requires a saved hc login session, --confirm, --expected-config-version equal to the agent's current config_version, and reads the plan and agent first. It requires the plan to be an applied configure plan (status applied or publish_failed, with an agent_id); a mismatch is refused locally, never sent. It then sends exactly one POST /vibecoder/plans/PLAN_ID/rollback (the pinned request schema requires reason, so --reason is sent as a bounded string, "" when omitted, and is never echoed), reads both back, and reports the same three evidence sections. --reason is protected free text: it never reaches stdout, stderr, a diagnostic or an error string. A rollback whose plan records no field changes is refused with wording for a configure plan that proposed nothing — only a plan whose operation is create is worded as a creation plan — and a plan that changes a field outside instructions/greetings is refused by count, exactly as apply does. A rollback 409/422 is reported like apply's: the structured reason code, or the validation-error count, and never the server's free text.
  • A saved-but-unpublished apply (status: publish_failed) is refused with category publication, not transport: the change was saved and read back, so triage must not be pointed at a network failure.
  • Rollback is not restore and neither is deletion recovery. hc ams restore is the tuning contract's selected-field restore: receipt-bound fields put back on the same agent. hc ams sessions plans rollback asks 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 existing hc ams plan|show|apply|restore tuning commands and their signatures, output and receipts are unchanged.
  • reconcile is the read-only recovery path: it sends no POST, no PUT and no DELETE. It reloads the plan, reads its agent when it names one, and reports the plan status and plan_hash, the agent_id, the agent's config_version, which planned field values are present/absent/other, and mutation_replayed: false; side effects and runtime stay unverified. It is what an operator runs after any uncertain outcome, before any further write. A field the review did not endorse (PLAN_REVIEW_FIELDS is instructions/greetings) is reported as unvalidated and its value is never read from the agent; a change whose before and after are the same value reports unchanged, so a committed no-op rollback is not mistaken for a failed readback.
  • All three refuse target files, root credentials or base URLs, raw output, plan IDs that are not 1-128 characters of letters, digits, ., _, : or - (a value carrying control characters or terminal escapes is refused and never echoed), an apply/rollback without --confirm, a malformed --confirm-hash, an out-of-range --expected-config-version, a --reason longer than 2000 characters, and installed SDKs without the plan get/apply/rollback and ams_admin.get_agent methods before tenant-admin login or any request. The agent read is required up front because apply, rollback and reconcile all read the agent back: checking it only there would let a POST that may have committed die as a plain unsupported failure.

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 [--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
  • create succeeds with operation: "guardrails.create" and data.guardrail = the server's 201 readback. --name is required. The creator is resolved from the saved session's GET /admins/me identity before the write, without a creator flag or credential fallback; an identity read failure sends no mutation. The tenant comes from the saved session's authenticated admin; --tenant-id is accepted only as an explicit target that must match that session (a mismatch is refused before any request). --rules-file names an owner-only (0600) 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, non-owner-only, 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.
  • update sends only the options you pass (an empty --description "" clears it; a --rules-file holding {} sends an empty rule set); it refuses with exit 1 (validation) when no field option is given. create treats an empty --description "" the same way: it is omitted rather than refused.
  • delete is 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 one GET for the guardrail, one GET /agents and one GET /policies to compute the affected references, prints the resolved target, those references and the disclosure block to stderr (pretty mode only; --output json|raw keeps stderr machine-parsable), sends exactly one DELETE, then makes exactly one confirmation GET. A 404 or an absent record there proves the deletion: the command reports data.deleted: true and verification.saved_state: confirmed for either, data.deleted: false with saved_state: failed when the guardrail is still served, and outcome: unknown with data.mutation_replayed: false and a not_read reconciliation when the answer is 5xx or the transport fails. A confirmation read that answers 401/403 (or any other non-404, non-2xx status) observed nothing about the row, so data.evidence.deleted.confirmation is unobserved, never still_present. A null or empty confirmation body means not_found; a malformed body or a record with a different ID/tenant means unobserved, with data.deleted: null. Successful SDK reads expose no HTTP status, so their confirmation_status is null, including when the matching guardrail is still present. Only an observed HTTP error records its actual status. A 2xx answer to the DELETE itself (a proxy or misbehaving server returning a body) is treated as sent, not as input validation: the one confirmation GET still decides the outcome. It never replays, retries or re-reads on its own, and it never claims a restore: hc ams restore replays tuning fields onto an existing agent and can never restore a deleted guardrail.
  • The server guards one reference only: an agent whose guardrail_ids contain the guardrail answers 409 and nothing is deleted (the CLI reports one conflict refusal). A policy whose guardrail_ids still 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; the refusal category is the honest one (authentication, authorization, unsupported for a missing catalog route, internal for a server error, transport for a network failure).
  • Any other 409 on create or update is one write-worded conflict refusal 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 update is a not_found refusal naming the ID; a target/tenant mismatch on a write readback is a validation refusal that reports the landed write truthfully: it names the guardrail and the tenant that actually received it and points to hc ams guardrails get.
  • If the transport times out, the connection drops mid-write, the server answers 5xx/408, or a 2xx write body cannot be read as a guardrail, the write's outcome is unknown: the CLI reports outcome: unknown with data.mutation_replayed: false and a not_read reconciliation, and its message says the write may have landed and to check hc ams guardrails get before retrying. It never re-sends the write on its own. That unknown envelope carries the shared transport error category for both a 5xx/408 answer and a network failure (the disclosure reads above use internal for a server error and transport for a network failure; the send-once write helper is shared across every catalog domain, so it reports one category for either).
  • A drifted installed SDK is refused before the tenant-admin login: the preflight checks that create, update, delete, list and get accept the exact call this CLI makes, so a renamed keyword is reported as unsupported with "Nothing was sent" instead of being mistaken for a landed write with an unreadable answer. Guardrail writes and agent lifecycle, assignment and delete writes also require an inspectable SDK method signature; an unreadable signature is refused as unsupported before sending anything. Read-only methods retain their permissive behavior when a signature cannot be inspected.

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.

Health-service catalog listing and inspection are complete and unpaged. The bounded projection includes only the stable ID, name, and the server's created/updated timestamps:

uv run --frozen hc ams health-services list --environment dev --tenant-id TENANT_ID
uv run --frozen hc ams health-services get --environment dev --tenant-id TENANT_ID \
  --service-id SERVICE_ID

When both target flags are omitted, these commands may use the matching saved tenant-admin session. Explicit flags must match that session. Health-service output never includes descriptions or arbitrary response fields, and does not imply booking, availability, pricing, scheduling, or that a service is offered to a patient.

The catalog also has three send-once writes. Each requires a saved hc login session, sends exactly one request, echoes the server's own readback, and never retries:

uv run --frozen hc ams health-services create --environment dev --tenant-id TENANT_ID \
  --name NAME --created-by-user-id USER_ID [--description TEXT]
uv run --frozen hc ams health-services update --environment dev --tenant-id TENANT_ID \
  --service-id SERVICE_ID [--name NAME] [--description TEXT]
uv run --frozen hc ams health-services delete --environment dev --tenant-id TENANT_ID \
  --service-id SERVICE_ID [--confirm]
  • create sends exactly one POST /health-services with only the fields the server's HealthServiceCreate declares: --name and --created-by-user-id (both required) plus an optional --description. It never sends tenant_id: the route overwrites it with the authenticated admin's tenant, so a client value would be ignored. There is no booking, availability, pricing, scheduling, capacity or patient-facing field on this contract, and the CLI invents none of them.
  • update sends exactly one PUT /health-services/{service_id} carrying only the flags that were given. HealthServiceUpdate declares only name and description, so those are the only field options; --description "" clears the description. With no field option it exits 2 with Nothing to update; pass at least one field option. and sends nothing.
  • delete is a hard delete with no restore and no server-side guard that refuses it: the database clears ai_agents.health_service_id for every agent that referenced the service (fk_ai_agents_health_service is ON DELETE SET NULL), and this command does not rebind them. Without --confirm it performs one bounded read and sends no DELETE, exiting 2 with --confirm is required; no delete was sent. In the default pretty mode that read also prints the reviewed target (service_id, name, created_date) and the disclosure block to stderr before the refusal; under --output json/raw that review text is suppressed so stderr stays machine-parsable, and the exit-2 refusal is plain text in every mode. With --confirm it makes that same read and then exactly one DELETE /health-services/{service_id}; it never replays, never retries and never claims a restore the server does not have. The envelope reports the accepted delete honestly: a 204/no-body answer proves the server accepted it, not which 2xx it was (the transport returns "no content" before it looks at the status), so confirmation_status is null and confirmation is unobserved.

All three render in both output modes, like every other AMS command: --output pretty (the default) prints the returned record's key: value lines or the delete's evidence block, and --output json prints the envelope.

Descriptions are write-only: --description is accepted on the wire and is never echoed back, because the projection omits the description field (skills and guardrails make the same omission), so the CLI never claims a description was verified. A created or updated record whose tenant_id differs from the session's tenant, or an update that read back as a different service ID, is a validation refusal that states the write already landed server-side and points at hc ams health-services list; it is never reported as a stopped no-op. A 404 on update/delete is a real missing (or other-tenant) record, because the route reads the row tenant-scoped first: it reports not_found and names the requested service ID, and a delete 404 means nothing was deleted. (tenant_id, name) is unique, so create/update of a name this tenant already uses answers 5xx and is reported as that same unknown outcome (the server maps the unique violation to nothing; it is not a 409, which is why the conflict category claims no cause). A 5xx/408 or a transport failure on any of the three writes is an unknown outcome (verification.saved_state: unknown, data.mutation_replayed: false, data.reconciliation.status: not_read): the write may have landed and the CLI neither retries nor re-reads on its own. Health-service writes refuse target files, root credentials or base URLs, raw output, an empty or dot-segment --service-id, and installed SDKs without the method the command needs, all before tenant-admin login.

Reads make exactly one catalog GET after tenant-admin login: a get whose service ID is unknown in this tenant reports not_found and names the requested ID — a 404 from the route, a null 2xx body, and a record whose tenant does not match the session all fail without an envelope claiming success (a foreign-tenant record is a validation identity refusal). Health-service reads refuse target files, root credentials or base URLs, raw output, blank or dot-segment IDs, and installed SDKs without both health-service read methods before tenant-admin login or catalog reads.

Agent schedules: hc ams schedules list|get|create|update|delete

List and inspect an agent's schedules, and configure one. Every row shows what it would run (the target agent and the cron expression) and, in UTC, when the CLI computes that it would next run:

uv run --frozen hc ams schedules list --environment dev --tenant-id TENANT_ID
uv run --frozen hc ams schedules get --environment dev --tenant-id TENANT_ID \
  --schedule-id SCHEDULE_ID

When both target flags are omitted, these commands may use the matching saved tenant-admin session. Explicit flags must match that session. Each read makes exactly one GET: the collection route takes no query parameters at all (no limit, offset or filter), so the list is complete and unpaged and reports page.kind: unpaged. The bounded projection is the schedule's ID, name, target agent_id, cron_expression, active, a description_present flag (the description text is never echoed, exactly as for health services, skills and guardrails), the server's own timestamps, and next_runs/next_runs_status.

The "when" is the CLI's own computation, not a scheduled fact. The server has no next-run or last-run column and no next-run route, and nothing executes schedules in this build: cron_matches() in the server has no callers, no schedule has ever fired, and utility_agent_invocations.triggered_by_schedule_id is never populated. So next_runs is computed here, in UTC, from the stored expression with the server's own matching rules (all five fields ANDed, weekday as isoweekday() % 7), bounded to a 366-day horizon and at most 3 occurrences, and starting at the next whole minute when the current minute has already begun — a next_run is never an instant that has already passed; next_runs_status is computed, none_within_horizon (a parseable expression that matches nothing inside the horizon, e.g. 0 0 31 2 * or 99 * * * * — never "never"), or not_computable. Every envelope also carries a next_runs block naming that provenance (computed_by: cli, timezone: UTC, execution: none_in_this_build) and the README makes no claim beyond it.

The writes are config-only and send-once. Each requires a saved hc login session, sends exactly one request, echoes the server's own saved row, and never retries:

uv run --frozen hc ams schedules create --environment dev --tenant-id TENANT_ID \
  --name NAME --agent-id AGENT_ID --cron-expression "0 9 * * 1-5" \
  --created-by-user-id USER_ID [--description TEXT]
uv run --frozen hc ams schedules update --environment dev --tenant-id TENANT_ID \
  --schedule-id SCHEDULE_ID [--name NAME] [--cron-expression EXPR] \
  [--description TEXT | --clear-description]
uv run --frozen hc ams schedules delete --environment dev --tenant-id TENANT_ID \
  --schedule-id SCHEDULE_ID [--confirm]
  • create sends exactly one POST /schedules with the fields the server's ScheduleCreate declares: --name, --agent-id, --cron-expression, --created-by-user-id (all required), an optional --description, and the session's tenant_id — which the body schema requires (omitting it is a 422) even though the route then overwrites it with the caller's tenant. There is no --active flag: ScheduleCreate has no such field, so a flag would be a silent no-op. The created row is therefore active: true by the server's own column default, read back from the saved row, and the envelope says so in data.notes.active. The target agent must be a Utility or Phone agent; any other type is the server's own 422, whose text the error names. The server's agent lookup on this route is not tenant-scoped, so a schedule can be created pointing at another tenant's agent if that ID is known; the CLI cannot see another tenant, so it discloses this rather than inventing a check the write does not perform.
  • update sends exactly one PUT /schedules/{schedule_id} carrying only the flags that were given. ScheduleUpdate declares name, cron_expression, description and active, and the server applies exclude_unset semantics, so --clear-description sends an explicit null (and --description "" is a local refusal: use --clear-description). It has no agent_id: a schedule's target agent is fixed at creation, so there is no --agent-id flag. With no field option it exits 2 with Nothing to update; pass at least one field option. and sends nothing, because an empty body is a server-side no-op that still writes an audit entry.
  • Enabling or disabling is refused here, in both directions. Configuration and enablement are separate operations on this server, and no route in this build reports a future-job effect. --active exits 2 with Refusing to enable a schedule: starting execution is a separately authorized edit... and --no-active exits 2 with its own message (Refusing to disable a schedule: ... does not toggle active at all); both refuse before hc login, before any read and before any request, under every output mode.
  • delete is a hard delete with no restore and no retention window, and no guard refuses it: the database clears triggered_by_schedule_id on any utility_agent_invocations row attributed to the schedule (ON DELETE SET NULL), which in this build is never populated because nothing fires schedules. The route's audit write runs after the delete, so a 5xx there leaves the row gone. Without --confirm it performs one bounded read and sends no DELETE, exiting 2 with --confirm is required; no delete was sent. In the default pretty mode that read also prints the reviewed target (schedule_id, name, agent, cron expression, active, the computed next UTC runs) and the disclosure block to stderr before the refusal; under --output json/raw that review text is suppressed so stderr stays machine-parsable, and the exit-2 refusal is plain text in every mode. With --confirm it makes that same read and then exactly one DELETE /schedules/{schedule_id} in the same authenticated session; the envelope reports confirmation_status: null / confirmation: unobserved because a no-body 2xx proves the server accepted it, not which 2xx it was.

All five render in both output modes: --output pretty (the default) prints a ID/NAME/AGENT ID/CRON EXPRESSION/ACTIVE/NEXT RUNS STATUS table plus the computed-instants disclosure for a list, key: value lines (plus the disclosure, and notes on create) for one schedule, and the labelled disclosure block for a delete; --output json prints the envelope. A returned row whose tenant_id differs from the session's tenant, a create whose saved row carries a different agent_id/name/cron_expression, and an update that read back a different ID or a field the server ignored are all validation refusals stating that the write already landed server-side and pointing at hc ams schedules list; none is reported as a stopped no-op. A 404 on create names the agent (the route resolves the agent first); a 404 on get/update/delete is a real missing (or other-tenant) schedule — the route reads the row tenant-scoped first — so it reports not_found naming the schedule ID, and a delete 404 means nothing was deleted. Both reachable 422 shapes on create (a string detail for an unschedulable agent type, a pydantic list for a rejected cron field) are reported as validation carrying the server's own text, never the raw body. This family has no unique constraint and the service raises no EntityInUseError, so there is no 409 branch and none is invented. A 5xx/408 or a transport failure on any write is an unknown outcome (verification.saved_state: unknown, data.mutation_replayed: false, data.reconciliation.status: not_read): the write may have landed and the CLI neither retries nor re-reads on its own. A malformed cron expression is refused locally with the server's own structural rule (five parseable fields, no bounds check) before sign-in, and all five commands refuse target files, root credentials or base URLs, raw output, a blank or dot-segment --schedule-id, and installed SDKs without the method the command needs, before tenant-admin login.

Agent knowledge files: hc ams agents files list|status|download|upload|delete

See what an agent has been given as knowledge, whether each file is indexed, add a file, take one away, and save one locally:

uv run --frozen hc ams agents files list --environment dev --tenant-id TENANT_ID \
  --agent-id AGENT_ID
uv run --frozen hc ams agents files status --environment dev --tenant-id TENANT_ID \
  --agent-id AGENT_ID --file-id FILE_ID
uv run --frozen hc ams agents files download --environment dev --tenant-id TENANT_ID \
  --agent-id AGENT_ID --file-id FILE_ID --output-file PATH
uv run --frozen hc ams agents files upload --environment dev --tenant-id TENANT_ID \
  --agent-id AGENT_ID --file PATH --created-by-user-id USER_ID
uv run --frozen hc ams agents files delete --environment dev --tenant-id TENANT_ID \
  --agent-id AGENT_ID --file-id FILE_ID --confirm
  • Three reads and two send-once writes on one agent: GET /agents/{agent_id}/files, GET /agents/{agent_id}/files/{file_id}/index-status, GET /agents/{agent_id}/files/{file_id}/content, POST /agents/{agent_id}/files (multipart) and DELETE /agents/{agent_id}/files/{file_id}. There is no rename, copy or search command here, and none is inferred.
  • list is complete and unpaged: the route takes no query parameters at all (no limit, offset or filter), so the CLI sends none and prints every row it was served in the server's order. --output pretty (the default) draws one row per file with six columns — ID, FILENAME, CONTENT TYPE, SIZE BYTES, INDEX STATUS, CHUNK COUNT — plus an entry count. --output json carries the same rows with the full projection: the file's id, agent_id, filename, content_type, size_bytes, index_status, index_error_present, chunk_count and indexed_at. The server's opaque storage_key (its object-storage pointer) and content_hash are never printed in either mode, and no arbitrary response field is echoed.
  • status prints the index state: attachment_id, agent_id, status, chunk_count, indexed_at and index_error_present. status is not checked against a closed set: the server stores it in a plain text column with no database constraint, so the values this build writes (pending, ready, failed) are facts to report, not an enum to enforce. An index error is reported as presence only — the CLI never prints the server's error text. A 2xx answer with no body is refused (The server returned no agent-file index status; no status was inferred.) rather than turned into an empty status.
  • download writes the server's exact bytes, unchanged, to a new owner-only file (mode 0600 on POSIX, the private-handle path on Windows). It never overwrites an existing path, never follows or creates a symlink, refuses a directory, and never prints the content to stdout or into the JSON/pretty envelope. The envelope (and the pretty output) carries only path, size_bytes and sha256 of exactly what was written, so a zero-byte file is reported explicitly as size_bytes: 0. The file is reserved before sign-in — a bad path fails before any request is made — and any failed or interrupted download unlinks the partial file, so nothing half-written is left behind.
  • The flag is --output-file PATH here (the hc ams agents export precedent calls the same concept --out); both name a new local file and refuse an existing one.
  • A 404 on list is not_found for the agent (unknown, or another tenant's): that route looks up no file. status and download look the agent up first and only then the file, so their 404 is not_found naming both records — File 'F' was not found for agent 'A' in this tenant (the agent itself may not exist, or belong to another tenant). The CLI never guesses which one is missing, and the server's own detail text is never printed. A row whose tenant_id or agent_id does not match the session is a validation identity refusal before anything is projected. A 5xx or transport failure stays the shared bounded category and is never retried.
  • When both target flags are omitted, these commands may use the matching saved tenant-admin session. Explicit flags must match that session. They refuse a target file, root credentials or base URLs, raw output, a blank or dot-segment --agent-id/--file-id, and an installed SDK without the agent-file read method the command needs, all before tenant-admin login.
  • upload sends exactly one multipart POST carrying the bare local filename and the file's bytes read once from --file, plus --created-by-user-id as a required form field (the server's contract; a missing value is a 422). The bytes never appear in the envelope, the pretty output, a refusal or a diagnostic. It sends no tenant_id and no idempotency key — the server has none and does not dedupe, so a re-send creates a second attachment.
    • It refuses locally, before sign-in and before any request: a blank or missing --file, a directory, an unreadable file (local_io), a file larger than the server's own 5 MiB bound, and an extension outside txt, md, pdf, docx (validation). A refusal names the path and the file name, never the content.
    • On success it prints the server's own record: --output pretty (the default) prints id, agent_id, filename, content_type, size_bytes, index_status, chunk_count, indexed_at, index_error_present, index_status_source and a one-line detail; --output json carries the same fields in the envelope's data.agent_file. filename and content_type are the server's values after its safe-filename normalisation — the CLI never presents its local name as authoritative, and the server's opaque storage_key/content_hash are never printed.
    • The index fields come from one GET .../index-status readback, not from the 201 body: that body's index_status is an insert-time snapshot (the server writes the real status with raw SQL and never refreshes the object), so it is never reported as the outcome. index_status_source says index-status read; if that read fails the upload is still reported as succeeded, with index_status_source: not read, no inferred status, and a pointer to hc ams agents files status. A pdf/docx upload that answers index_status: failed ("text extraction is not implemented for this format") is the server's answer and a successful upload, not an error.
    • A 404 names the agent (the route resolves the agent tenant-scoped first and the file does not exist yet): not_found, nothing was uploaded. A 422 is validation and quotes the server's own detail (status + detail). There is no 409 and no 413 on this route, so neither is claimed. A 5xx/408 or a transport failure is the shared unknown outcome (verification.saved_state: unknown, data.mutation_replayed: false, data.reconciliation.status: not_read): the upload may have landed, so the command neither retries nor re-reads — reconcile by filename and size with hc ams agents files list. A readback row whose agent_id or tenant_id differs from the session is a validation refusal that states the upload landed server-side.
  • delete needs --confirm. Without it the command makes one review read (GET /agents/{agent_id}/files, the only read that names a file), prints the reviewed target and the cleanup disclosure to stderr — in --output pretty only, because json/raw keep stderr machine-parsable — sends no delete, and exits 2 with --confirm is required; no delete was sent.. With --confirm it makes the same single read and then exactly one DELETE, never a retry or a replay.
    • The DELETE answers 204 with no body, and an empty body reads as "no content" before its status is looked at, so the envelope records status: accepted, confirmation_status: null and confirmation: "unobserved" — no 200 or 204 is invented.
    • Indexing cleanup is the server's and is not verified by any route. The delete removes the stored object, the attachment's chunk rows and the attachment row; the vector-index cleanup is an unfinished server-side step (TODO(milvus)) that this CLI cannot observe, and the cleanup field says exactly that. The server writes its audit-log entry after deleting the row, so an unclear delete may already have removed the file: the unknown outcome says so rather than claiming the file is still there.
    • A 404 names both records — File 'F' was not found for agent 'A' in this tenant (the agent itself may not exist, or belong to another tenant). — because the route resolves the agent first. A file that is not in the agent's own list is the same not_found with nothing sent. A reviewed row from another tenant is a validation identity refusal.
  • When both target flags are omitted, these commands may use the matching saved tenant-admin session. Explicit flags must match that session. They refuse a target file, root credentials or base URLs, raw output, a blank or dot-segment --agent-id/--file-id, a blank --created-by-user-id, and an installed SDK without the agent-file methods the command needs (upload requires both the upload method and its index-status readback; delete requires the review list and the delete), all before tenant-admin login.

Utility-agent runs and actions: hc ams runs and hc ams actions

Read what a utility agent did, scoped to one agent. Two read-only groups cover five served routes; nothing here writes, acknowledges, archives or changes a status.

uv run --frozen hc ams runs list --environment dev --tenant-id TENANT_ID --agent-id AGENT_ID \
  [--status pending|running|completed|failed|cancelled] [--limit N] [--offset N]
uv run --frozen hc ams runs get --environment dev --tenant-id TENANT_ID --agent-id AGENT_ID \
  --invocation-id INVOCATION_ID
uv run --frozen hc ams actions list --environment dev --tenant-id TENANT_ID --agent-id AGENT_ID \
  [--invocation-id INVOCATION_ID] [--severity info|warning|critical] \
  [--status generated|acknowledged|acted_on|dismissed|expired] \
  [--follow-up-required|--no-follow-up-required] [--limit N] [--offset N]
uv run --frozen hc ams actions get --environment dev --tenant-id TENANT_ID --agent-id AGENT_ID \
  --action-id ACTION_ID
uv run --frozen hc ams actions stats --environment dev --tenant-id TENANT_ID --agent-id AGENT_ID

Every command makes exactly one GET on its route after tenant-admin login: /agents/{agent_id}/invocations, /agents/{agent_id}/invocations/{invocation_id}, /agents/{agent_id}/actions, /agents/{agent_id}/actions/{action_id} and /agents/{agent_id}/actions-statistics. The two list routes are the agent registrations, which take routing precedence on the server; the CLI does not model the later duplicate envelope registrations. A run is one invocation of a utility agent; its actions are the discrete follow-ups that run generated.

What it prints. --output pretty (the default) prints an ID/STATUS/timing table for a run list, an ID/ACTION NAME/severity/status/follow-up table for an action list (each with an entry count and (no entries) when empty), key: value lines for a single run or action, and the server's own counts (total_actions, by_severity, by_status, critical_unaddressed, follow_ups_due) for actions stats. --output json prints the stable result envelope. runs list/actions list echo a page block naming the limit applied (a sent --limit, or the server's default of 100 when omitted) and the offset; both routes return a bare list with no server-side total, so the CLI never invents one. actions stats reports the server's counts unchanged: missing keys are not zero-padded and nothing is recomputed.

What it omits. The bounded projections never carry patient identity, model-written free text (a run's result_summary, an action's action_description), prompt or context metadata, execution logs, error traces or error messages. runs get prints the run's identity, status, timing and token/cost accounting; actions get prints identity, severity/status, routing (target_role, priority_score, follow-up) and archive state. A run reports whether it recorded an error as error_present (a boolean); the message text itself is free text and stays out. Logs and metrics are their own command surface, not these reads (see the next section).

The one model-written field either group keeps is an action's action_name, and the reads would be unusable without it: it is the action's identity — the first line of the runtime's ACTION: block (app/services/utility_runner.py: action_name = lines[0].strip()), which the server stores verbatim and does not validate. It is printed as-is, not summarized or truncated, and it is the only such field either projection carries. patient_id is deliberately not a filter or an output field (patient-scoped reads stay out), and no acknowledge/archive/status write exists in either group: there is no --confirm, no idempotency key and nothing is ever sent.

What it refuses. Target files, root credentials or base URLs, raw output, blank or dot-segment IDs, --limit below 1, a negative --offset, a status/severity outside the values above, and an installed SDK without the run or action resource (checked before tenant-admin login). A get whose ID is unknown in this tenant reports not_found and names the requested ID: a 404 from the route, a 2xx with no body or a null body, and a record that is not the requested one all fail without an envelope claiming success (a foreign-agent or foreign-tenant record is a validation identity refusal). A 404 on a list/stats route stays validation, because a missing collection or statistics route is not a missing record, and a body-less actions stats answer is a validation refusal rather than invented zero counts.

Agent logs and run metrics: hc ams logs list and hc ams agents metrics

See what an agent has been doing and what its runs cost, for one agent. Both are read-only single-request commands; nothing here writes.

uv run --frozen hc ams logs list --environment dev --tenant-id TENANT_ID --agent-id AGENT_ID \
  [--limit N]
uv run --frozen hc ams agents metrics --environment dev --tenant-id TENANT_ID --agent-id AGENT_ID \
  [--days N]

Every command makes exactly one GET after tenant-admin login: /agents/{agent_id}/logs (newest first) or /agents/{agent_id}/metrics. Each route takes exactly one integer and nothing else — limit for logs, days for metrics. There are no filters, no offsets and no continuation tokens: both answer with a bare body, so the CLI never invents a next page.

What it prints. --output pretty (the default) prints a KIND/TS/DETAIL PRESENT table for a log list (with an entry count, and (no entries) when the agent has logged nothing — an unreachable log store also answers empty, which is a normal success, not an error) and one key: value line per metric plus a window: block for agents metrics. --output json prints the stable result envelope. logs list always sends a bounded limit — 100 by default, the server's own default page — and echoes the limit it applied plus the returned count in a page block; the server's cap is 1000 and the CLI never asks for more. agents metrics sends --days (default 30, the server's own window) and prints the server's eight aggregate numbers unchanged — total_runs, successful_runs, failed_runs, success_rate, avg_execution_time_ms, total_tokens, total_cost_usd, avg_cost_per_run — alongside a window block naming the days the numbers cover. Nothing is recomputed, rounded or padded.

What it omits. A log entry carries four fields on the server: kind, ts, the agent_id the caller already passed, and detail. detail is the raw WSS message text that produced the entry — the user's message, the model's output or a tool payload — which is the free-text (and PHI) carrier on this surface, so the projection keeps kind and ts and never prints detail. detail_present is the one cue it carries: a boolean saying the server did record text for that entry, with the text itself left out. Metrics carry no free text at all.

What it refuses. Target files, root credentials or base URLs, raw output, blank or dot-segment agent IDs, --limit below 1 or above 1000, --days below 1 or above 365, and an installed SDK without the log resource or the metrics method (checked before tenant-admin login). A logs read that answers 404 — an unknown agent, or another tenant's agent — reports not_found and names the agent ID; it is never an empty log list. agents metrics is the honest opposite: the route checks the caller's tenant but not the agent, so an unknown or foreign agent ID is a 200 of zeros, and the CLI prints those zeros rather than inventing a not_found the server can never send. A metrics 404 — only reachable when the deployed server does not serve the route at all — is reported by category as a failed read, never as a missing agent. Neither command has a --confirm, an idempotency key or any write path: the invocation/action archive and status writes stay out.

Vibecoder outbox: hc ams operations outbox, dead-letter list and dead-letter retry

See whether the authoring side effects are stuck, and retry one dead-lettered event deliberately. operations outbox and operations dead-letter list are read-only single-request reads. operations dead-letter retry is the one write in this group: it requires hc login and --confirm, sends exactly one POST, and never replays. There is no idempotency key anywhere in this group.

uv run --frozen hc ams operations outbox --environment dev --tenant-id TENANT_ID
uv run --frozen hc ams operations dead-letter list --environment dev --tenant-id TENANT_ID \
  [--limit N]
uv run --frozen hc ams operations dead-letter retry --environment dev --tenant-id TENANT_ID \
  --event-id EVENT_ID [--confirm]

Every command makes exactly one GET after tenant-admin login: /vibecoder/operations/outbox or /vibecoder/operations/outbox/dead-letter. The stats route takes no query parameters at all; the dead-letter route takes one integer and nothing else. There are no filters, offsets or continuation tokens.

What it prints. --output pretty (the default) prints one key: value line per counter for operations outbox — pending, processing, dead_letter, oldest_pending, oldest_processing and measured_at — and an ID/EVENT TYPE/ATTEMPTS/ERROR SUMMARY/ERROR TRUNCATED/CREATED AT table for operations dead-letter list (with an entry count, and (no entries) when the queue is empty). --output json prints the stable result envelope. Every value is the server's own: measured_at is the server's clock and the two oldest_* timestamps are echoed as served (or null). The CLI never stamps its own clock, never computes an age and never derives a status from the counts. dead-letter list always sends a bounded limit — 50 by default, the server's own default page — and echoes the limit it applied plus the returned count in a page block; the server's cap is 100, and the CLI never asks for more (the server silently clamps, so the CLI owns the bound instead of echoing a limit the server ignored). The stats envelope has no page block: it is one aggregate body.

What it omits. A dead-letter row is projected to id, event_type, attempts, created_at, error_summary and error_truncated. The route's SELECT never serves the event payload — so no payload is requested, printed or invented — and tenant_id, status and max_attempts are not served either, so none is modelled. last_error is the outbox worker's arbitrary, multi-line exception text: only its first non-empty line is printed (error_summary, capped at 200 characters) and error_truncated says whether anything was dropped — extra lines or the length cap. null means the server recorded no error, never an empty string. There is no row identity check to make: the tenant filter is the server's, and the served row carries nothing to compare against the target, so the CLI claims nothing more. status is a plain text column with no CHECK and the route already filters status='dead_letter' in SQL, so no closed enum is enforced anywhere.

What it refuses. Target files, root credentials or base URLs, raw output, --limit that is not an integer from 1 to 100, and an installed SDK without the method the command uses — each checked before tenant-admin login, and each command only for the method it actually calls (the retry's signature is pinned too, so a drifted SDK is refused before anything is sent). Neither read route can 404 for a missing record: 404/400/422 are reported as a failed read by category.

A 503 is a failed read, never "nothing is stuck". Both read routes collapse every server-side failure into 503 {"detail": "Vibe Coder outbox is unavailable"}, so a 503 renders a failed envelope with category transport, exit code 1 and the message Outbox service is unavailable. It is never an empty collection, never zero counts and never not_found.

hc ams operations dead-letter retry

Retry one dead-lettered event deliberately. This is a send-once write: it needs a saved hc login session, and without --confirm it is a preview.

What it does. Without --confirm it makes one bounded read of the dead-letter queue (limit=100, the server's own cap), prints the reviewed event and the disclosure below, sends no POST, and exits 2 with --confirm is required; nothing was sent. With --confirm it makes the same read and then exactly one POST /vibecoder/operations/outbox/{event_id}/retry — no body, no query parameters, no second request and no replay. The reviewed block renders only under --output pretty (the default); --output json keeps stderr machine-parsable and prints the stable envelope, --output raw is refused as for every AMS command.

What the preview shows. The event's six-key projection (id, event_type, attempts, created_at, error_summary, error_truncated) when the id is among the newest 100 dead-letter events, and not_in_listing when it is not. A miss is honest, not a refusal: the event may be older than that page or no longer dead-lettered, there is no single-event read on this route family, the server's retry route never requires the listing, and a queue longer than 100 rows is the normal steady state. The confirmed run still sends exactly one POST.

What it prints. --output json prints the stable envelope with retry.event_id and retry.status exactly as the route served them, confirmation: "unobserved", confirmation_status: null, the reviewed block and the three disclosures. Both served values are the route's own: event_id is your own input echoed back and status (pending) is the route's literal — neither is a readback of the row.

What it does not claim. A 200 is an acceptance, never a delivery. The retry is asynchronous: the server's outbox worker drains eligible rows about every 60 seconds, so nothing is delivered when this command exits, and the event may fail again and return to dead_letter (which is why this command never reads it back). The retry also destroys the recorded diagnosis: the server resets attempts to 0 and clears last_error, while max_attempts is left as it was. No audit row is written for the retry, and there is no idempotency key — the server's status='dead_letter' predicate is the idempotency, so a blind retry never duplicates work and a second attempt answers 404.

What it refuses. A blank --event-id, one with leading/trailing whitespace, a ./.. segment or one containing / or \ — refused locally in both preview and confirmed runs, before login and before any request, because the id becomes the route's path segment and the server validates nothing at all. A missing --event-id is a usage error. A missing saved session is refused before any request. An installed SDK without the retry method, or whose retry signature cannot accept this CLI's call, is refused before login.

A 404 on the retry. It is reported as outcome: failed with category not_found, exit code 1, and a message naming all three cases the server conflates: the event may never have existed, may belong to another tenant, or may no longer be dead-lettered (already retried, being processed or delivered). A 404 after an earlier attempt is the expected answer and is not proof that attempt failed.

An uncertain outcome. A 5xx/408, a dropped connection, or a 2xx whose body cannot be read as a retry acknowledgement is reported as outcome: unknown with category transport, mutation_replayed: false and a not_read reconciliation naming the re-read command (hc ams operations dead-letter list) and the same "a 404 is not proof of failure" warning. Exactly one POST is ever sent and nothing loops or auto-retries.

Reports: hc ams usage, hc ams dashboard and hc ams audit

Read what an agent (or the tenant) has cost and what changed, without leaving the CLI. All five commands are read-only single-request reads; nothing here writes, and there is no --confirm or idempotency key anywhere in this group.

uv run --frozen hc ams usage list --environment dev --tenant-id TENANT_ID [--agent-id AGENT_ID]
uv run --frozen hc ams usage get --environment dev --tenant-id TENANT_ID --usage-id USAGE_ID
uv run --frozen hc ams usage analytics --environment dev --tenant-id TENANT_ID
uv run --frozen hc ams dashboard --environment dev --tenant-id TENANT_ID
uv run --frozen hc ams audit --environment dev --tenant-id TENANT_ID [--period today|last_month|last_year]

Each command makes exactly one GET after tenant-admin login: /usage, /usage/{usage_id}, /usage/analytics, /analytics/agents-dashboard or /audit-log. usage list takes only --agent-id, which is the route's own served filter; there is no --limit, no --offset and no continuation token, because those routes answer with a bare list and a bare aggregate body. dashboard takes no filter at all. audit takes only --period, the server's own closed set (today, the server's default, last_month or last_year), and the CLI always sends it explicitly so the printed window is never a guess. /analytics/org-chart is a different operation and is not part of this group; POST /usage is internal-only and has no command.

What it prints. --output pretty (the default) prints a table for usage list (ID/AGENT ID/OCCURRED AT/TOKENS USED/COST/REQUEST SUMMARY PRESENT) with an entry count and (no entries) when empty; key: value lines for usage get; the three totals (total_events, total_tokens, total_cost) followed by by_agent: and by_tenant: breakdown tables for usage analytics; the four dashboard series (agents_by_type, agents_by_department, top_agents_by_usage, top_tools_by_frequency) each with its own columns; and a window: block (period, start, end) plus an entries table for audit. --output json prints the stable result envelope. Every number and every name is the server's own: nothing is recomputed, rounded, re-ranked or re-capped (the two ranked dashboard series are capped server-side at TOP_N). The audit window is echoed from the response, so the rows can be read without assuming a period.

What it omits. A usage record carries request_summary (free prose written by the usage producer) and metadata (an arbitrary dict); the CLI projects neither and prints only request_summary_present, a boolean saying prose was recorded, with the text itself left out. event_key and event_hash are opaque idempotency material and are never printed. An audit entry carries details (an arbitrary, unmodelled dict) and event_key, both omitted; the projection keeps the identity and outcome — id, created_at, actor_user_id, action, resource_type, resource_id. tenant_id is dropped from every projection because it is already the command's own target. The dashboard's names (key, label, agent_name, tool_name) are the one thing printed as-is: they are server-derived (an agent type, a department name, an agent's configured name, a tool-catalog name), not model output, and they are the identity of the row.

What it refuses. Target files, root credentials or base URLs, raw output, blank or dot-segment IDs, a --period outside the server's three values (rejected by Click before any request is made), and an installed SDK without the usage, dashboard or audit resource (checked before tenant-admin login). Every row is identity-checked: a usage row whose tenant_id is not the target, a usage list row that is not the requested --agent-id, and an audit entry whose tenant_id is not the target are refused instead of printed (the server's audit-list filter is skipped when the token has no tenant, so the CLI is the last refusal point). A usage get that answers 404 — an unknown ID, or another tenant's — reports not_found and names the usage ID, and a 200 with a null body is classified the same way. The other four routes are the honest opposite: usage list, usage analytics, dashboard and audit always answer for the caller's tenant and can never 404 for a missing record, so a 404 there is reported by category as a failed read and is never dressed up as not_found. None of these commands has a write path: the invocation/action archive and status writes, and the internal usage POST, stay out.

AMS surfaces the CLI does not expose

These AMS routes exist on the server and deliberately have no hc ams command. Each is left out for its own reason, so its absence is not read as a gap:

  • Test-patient credentials (/test-patient-credentials, its per-ID reads and its login route): they store synthetic-patient credentials, and the login route mints a patient token. The CLI never handles patient credentials or patient tokens; hc login saves a tenant-admin session and nothing else.
  • Patient-scoped reads (/agents/patients/{patient_id}/actions, invocations and summary): they return what an agent did about a patient, which needs its own authorization and data-minimization decision rather than a flag. The shipped hc ams runs and hc ams actions reads are agent-scoped and stay.
  • WSS/live sessions (WSS /ws and WSS /ws/agents/{path_agent_id}/chat): a socket opens a live chat/execution session that can change the model's output, the tools it runs and the persisted conversation, so it needs its own execution approval and an exact tenant/patient/agent session binding.
  • The server's preview surface (POST /preview/session): it signs a configured synthetic preview user in and returns a patient token. That is not the CLI's own --confirm preview and the CLI does not drive it; the /preview/* mount is bundled static assets.
  • The invocation/action archive (/agents/{agent_id}/actions/{action_id}/archive and /agents/{agent_id}/invocations/{invocation_id}/archive): archiving changes archive state on a record — a write with its own approval and reconciliation requirements. The shipped reads report archived state; they never change it.
  • Acknowledge and status writes (/agents/{agent_id}/actions/{action_id}/acknowledge and /agents/{agent_id}/actions/{action_id}/status): acknowledging or re-statusing an action asserts a human clinical or operational judgement about a follow-up, which is a deliberate write rather than an administration convenience.
  • Knowledge search (POST /agents/{agent_id}/knowledge/search): a POST that is really a read — full-text search over an agent's protected knowledge, returning excerpts. Protected excerpts need a protected destination, so they do not belong on ordinary stdout.

AMS output modes

The read commands (hc ams skills|tools|policies|guardrails|data-sources|health-services|teams|departments|schedules list|get, hc ams runs list|get, hc ams actions list|get|stats, hc ams logs list, hc ams agents models|metrics, hc ams agents files list|status|download, hc ams usage list|get|analytics, hc ams dashboard, hc ams audit and hc ams organization hierarchy) render in two modes (--output on the root hc command; pretty is the default). The AMS writes (hc ams agents files upload|delete, hc ams health-services create|update|delete and hc ams schedules create|update|delete) render in the same two modes, with a write-shaped envelope (its own verification block and reconciled outcomes) rather than a read's:

  • pretty (default): a compact human view. Lists print an ID/NAME table with an entry count; a collection whose rows have no name (sessions, messages, attachments, runs, actions) prints a table of that command's own columns plus the count, and (no entries) when empty. A single record prints key: value lines, the organization hierarchy prints an indented tree, and write or reconciliation evidence prints labelled key: value lines (the write's verification: block included) instead of JSON. 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.

Pretty text displays terminal controls, Unicode format controls (including bidi and zero-width characters), line/paragraph separators, and lone surrogates as visible escapes. Literal backslashes are doubled so data cannot imitate those escapes. Other printable Unicode is preserved; table alignment counts code points. JSON mode preserves the original values through JSON escaping.

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. Mutating operations keep the block to report the evidence they observed; a local write refusal keeps not_applicable values because nothing was sent. For command authors, run_domain and the succeeded/failed result helpers all default to read-only mode. Mutation adapters must pass read_only=False to both the runner and result helper so success and failure agree.

--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 1 with category validation: 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 authentication with Not logged in; run \hc login --environment --tenant-id `.`
  • A get whose requested ID does not exist (HTTP 404): category not_found naming the ID, e.g. Skill 'nosuch' was not found. (a 404 on list stays validation for most domains; a department get 404 is not_found naming the requested department ID, while a department list 404 keeps its legacy transport classification. Department write 404s are not_found refusals naming the ID).
  • Skill, policy, guardrail, and data-source get also report not_found when the SDK receives a JSON null or no response body. Their SDK resource get methods return None in those cases; malformed non-null records remain validation failures. No HTTP status is inferred from an absent body.
  • HTTP 401/403 map to authentication/authorization; 409 to conflict; network failures to transport; local output failures to local_io.
  • Any unexpected internal error is category internal with a generic message; it is never labeled validation and 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-ams-services.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.

All AMS writes require a saved hc login session, including legacy plan, apply, and restore: plan creates a server session and plan, and restore creates an inverse server plan. Run hc login before these commands. Shared authentication refuses missing or mismatched sessions without falling back to environment credentials.

Read commands, including inspect and show, still accept HC_AMS_ADMIN_EMAIL and HC_AMS_ADMIN_PASSWORD when no session is saved. This read-only fallback logs in once per invocation and supports the existing onepassword-env wrapper. 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.14.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for healthcloud-cli 3.14.0
File Size Uploaded Provenance Actions
healthcloud_cli-3.14.0.tar.gz 396.3 kB With provenance Details for healthcloud_cli-3.14.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for healthcloud-cli 3.14.0
File Interpreter ABI Platform Actions
healthcloud_cli-3.14.0-py3-none-any.whl Python 3 none any Details for healthcloud_cli-3.14.0-py3-none-any.whl

Total release size: 810.0 kB

Release files / healthcloud_cli-3.14.0.tar.gz

Download URL healthcloud_cli-3.14.0.tar.gz
Size 396.3 kB
Tags Source
SHA-256 checksum
How to use checksums
6786b7e97d8ebaa2ceb5e154b2a9a7add19f53ab099bdcc1902fb16ef6ddbfb2
BLAKE2b-256 checksum
How to use checksums
54fc806f18654e2ac59b834c089914cc1ae2d542794cf6a3e233ec46dec14676
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 20, 2026.

Transparency log

Release files / healthcloud_cli-3.14.0-py3-none-any.whl

Download URL healthcloud_cli-3.14.0-py3-none-any.whl
Size 413.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a76ff29b9dc4db70727dcb0820a3100c4a67aedb64df2012cd55ae51a9800cb3
BLAKE2b-256 checksum
How to use checksums
d173b37511077d56013577986106b7fc4e4ac7d8d4e59641d9c62abe6277129b
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 20, 2026.

Transparency log

Security for healthcloud-cli 3.14.0

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.

Select from 2 files

Attestation for healthcloud_cli-3.14.0.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 20, 2026.

Transparency log

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

Release history Release notifications | RSS feed

This release

3.14.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page