@hcmai/cli

The official HCM Next command-line interface for business APIs, tenant delivery, workspaces, and AI agents.

Install

npm install --global @hcmai/cli
hcm --version

Node.js 22 or newer is required.

First connection

hcm env add production --endpoint https://hcm.example.com
hcm login https://hcm.example.com --code <one-time-pairing-code>
hcm env current
hcm identity show <identity-alias> --output json

The npm package is public. Application credentials are not included in the package and are stored locally through the HCM login flow. identity show uses that alias's stored token to return the live userId, username, tenantId, and roles without printing the token.

Source and release automation are maintained in CNB.

Workspace revision conflicts

hcm workspace pull downloads workspace files and records a local snapshot. It does not reset the server's baseline against active. A mini app's target contains existing files error protects local files: keep the original directory and pull into a new empty directory, or use --force only after confirming those local files may be overwritten.

For a confirmed workspace/active revision conflict:

hcm workspace rebase --workspace <key> --dry-run --output json
hcm workspace rebase --workspace <key> --dry-run --plan /tmp/rebase-plan.json
# Edit reason and each path's resolution before applying.
hcm workspace rebase --workspace <key> --plan /tmp/rebase-plan.json --output json

Keep the same --env / --as; --dir can supply the local workspace binding. Without --plan, rebase only previews. --dry-run --plan creates a new draft and never overwrites an existing plan or submits a remote write. Base content is unavailable (baseContentAvailable: false); the preview includes hashes and the active/workspace contents for manual comparison.

Fill a nonempty reason, remove paths you will handle later, and replace every remaining UNRESOLVED with TAKE_ACTIVE, KEEP_WORKSPACE, MERGED, or DELETE. Only MERGED submits content, which must be a string (an empty string is valid). The server rejects a stale planDigest; preview again and review a new plan. Check resolvedPaths, baselineHash, and remainingConflicts in the receipt. Rebase does not rewrite local files or release/deploy. Do not delete and recreate files or the whole workspace to refresh the baseline.

Project environments

A project env.yaml can declare default and named environments, each with endpoint, frontend, tenant, optional roles, and danger. Legacy three-line files remain supported. --env first matches a project name, then a local slot. Connection provenance is printed to stderr; writes to danger: true environments require --allow-danger. Credentials stay in the local identity store.

Delivery projects

hcm chiron init scaffolds a consultant project: env.yaml, the working directories, and the managed block in AGENTS.md / CLAUDE.md. Skills come from hcm chiron skills sync (targets: codex, claude); the repo-local codex target maintains the skill index in AGENTS.md and mirrors it to an existing CLAUDE.md, so a dual-agent project shares one locked skill tree. Since 0.14.0 the codex target splits that tree by ownership: hcm-skills/sync/ is mirrored from the product (the CLI owns it outright, lockfile included) and hcm-skills/local/ holds the consultant's own skills, which the CLI never writes. Same id on both sides: local/ shadows sync/. The claude target stays flat (.claude/skills/) because Claude Code only discovers one level deep.

Page acceptance is hcm chiron page. It mints the same short-lived hcm open ticket, drives a headless Chromium through Playwright (the chromium_headless_shell-* build in your Playwright cache — the one Playwright MCP installs — works inside sandboxes such as Claude Code's macOS Seatbelt; run npx playwright install chromium-headless-shell if there is none), and writes a non-overwriting PNG under the project's evidence/ directory. --eval '<js>' runs an async function body in the page before the capture (click "regenerate", wait, type a follow-up question…) and its return value lands in the receipt. --cdp http://127.0.0.1:9222 attaches to a Chrome started outside the sandbox with --remote-debugging-port when even the headless shell cannot start. At least one --expect-text is mandatory — a login page, an error page and a blank page all produce a screenshot, so "a screenshot exists" is not evidence:

hcm chiron page /dashboard/<id> --env acme-dev --as consultant-acme-dev \
  --expect-text '<dashboard title>' --reject-text '未知组件类型' \
  --out evidence/acme-dev/<date>-dashboard/page.png

Exit code is 0 when the page carries every --expect-text and none of the --reject-text, and 3 when it does not; the screenshot is kept either way so a human can see whether it was a login page, an error page, or a real gap.

Workspace delivery checks

Raw workspace push requires Core workspace delivery protocol 1 and conditionalRawWrite. It hashes only locally added, modified or deleted candidates, checks existence for all baseline/local paths, and checkpoints normalized commit receipts per file. Exact desired remote values are marked observed; an unprovable normalized result stays UNKNOWN. The overall deadline remains 300 seconds. Mini apps currently have complete-list guards, but do not provide conditional writes, complete pagination or full workspace resume.

hcm workspace inspect --entries --output json
mkdir -p /tmp/hcm-delivery-review
hcm workspace cleanup-plan .tools/ --purpose 'temporary logs' --reason 'external backup retained' --owner-declaration --plan /tmp/hcm-delivery-review/cleanup-001.json
hcm workspace cleanup --plan /tmp/hcm-delivery-review/cleanup-001.json --output json
hcm workspace release-plan 1.2.3 --plan /tmp/hcm-delivery-review/release-001.json --output json
hcm workspace release --plan /tmp/hcm-delivery-review/release-001.json --output json

Review plans outside the workspace. Cleanup sends only the original exact execution paths and digest, and reports each committed, failed, notExecuted or UNKNOWN outcome. Owner declaration and known-consumer checks do not prove absence of every possible use. Release plans show the actual patch; unrecognized files still follow the current all-file policy. Controlled delivery retains the existing R3 restriction on release.

Run these commands from the bound local workspace. Plan files require an existing parent outside its real physical root and are created exclusively; use a new filename each time. For API boundaries, field-policy failures and recovery, see the workspace workflow.

Standard release lifecycle and scopes (ADR-464)

These commands require a Core build that implements ADR-464. They are standard product capabilities.

hcm workspace release-plan 2.0.0 --policy-version RUNTIME_ASSETS_V2 --plan /tmp/release-2.json
hcm workspace release --plan /tmp/release-2.json
hcm workspace cancel-release <releaseId> --reason 'Unused candidate'

New previews default to RUNTIME_ASSETS_V2. Unknown paths block publication. Choose ALL_WORKSPACE_PATCH_FILES_V1 explicitly to retain the previous all-patch behavior. The selected policy is saved with the reviewed digest and sent unchanged for checked creation; an older Core ignoring V2 is rejected before saving an executable plan. Existing V1 plans remain compatible.

Cancellation requires both workspace ownership and configuration administrator authorization. Any deployment/MR history, package installation/recovery dependency or unknown evidence blocks it. Release bytes, audit and version reservation remain; cancelled releases cannot be deployed, merged, or used for a new workspace. Cancellation disables automatic retries. A lost response remains UNKNOWN; read the original release and its cancellation audit before deciding whether to retry that exact ID.