docs(cli): document the harper deploy command - #624
Conversation
Add a full reference entry for `harper deploy` on the CLI commands page, covering both directory (current-working-directory) and package-reference deploys, local vs. remote (`target=`) usage, live SSE progress introduced in v5.1.0, and every supported parameter (restart/replicated, install options, deployment/replication controls, urlPath/host, credentials, and the directory-packaging options skip_node_modules/skip_symlinks). Cross-link the `deploy_component` operation for full server-side behavior. Also add `harper deploy` to the command table in the CLI overview. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-624 This preview will update automatically when you push new commits. |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request documents the 'harper deploy' CLI command. It adds a detailed section to 'reference/cli/commands.md' explaining how to package and deploy Harper components, along with parameters and packaging options. It also updates the command table in 'reference/cli/overview.md' to include 'harper deploy'. There are no review comments, so I have no feedback to provide.
kriszyp
left a comment
kriszyp
left a comment
There was a problem hiding this comment.
Looks good, but some timeline cleanup to address.
🤖 Reviewed with Codex
| - `install_command=<command>` - Override the install command run for the component. | ||
| - `install_timeout=<ms>` - Maximum time, in milliseconds, to allow the install to run. | ||
| - `install_allow_scripts=true` - Allow npm pre/post-install scripts to run (disabled by default). | ||
| - `deployment_timeout=<ms>` - How long, in milliseconds, a peer waits to receive the replicated payload before failing. |
There was a problem hiding this comment.
The current deploy_component contract at reference/operations-api/operations.md:592-603 does not include deployment_timeout or ignore_replication_errors. Repository history shows these controls originated in unfinished two-phase deployment work, so users of the released API may have these values rejected or silently fail to get the promised behavior. Unless the corresponding core implementation has landed for a documented release, please remove both bullets; otherwise add them to the canonical operation reference with the appropriate version annotation first.
— KrAIs (GPT-5.4)
| - `force=true` - Allow deploying over a protected core component name. | ||
| - `urlPath=<path>` - HTTP path the component is mounted at (e.g. `/api/v2`). Requires `package`. | ||
| - `host=<hostname>` - Virtual hostname the component is served on (e.g. `api.example.com`). Requires `package`. | ||
| - `credentials=<json>` - Authentication for installing from a private npm registry or git repository. See [`deploy_component` credentials](../operations-api/operations.md#deploy-credentials-credentials). |
There was a problem hiding this comment.
credentials is an array of nested credential objects, while the existing CLI contract explicitly says objects and arrays of objects are unsupported (reference/cli/operations-api-commands.md:301-306 and reference/cli/operations-api-commands.md:370-379). Advertising credentials=<json> therefore gives private-package users a command that cannot represent the required request shape. Please direct them to the HTTP Operations API instead, or, if the CLI has gained nested-JSON support, update the general CLI contract and provide a correctly shell-quoted array example here. This surface also needs its v5.2 availability called out if retained.
— KrAIs (GPT-5.4)
|
|
||
| ### `harper deploy` | ||
|
|
||
| <VersionBadge version="v4.4.18" /> |
There was a problem hiding this comment.
The existing command inventory dates both deploy_component and its deploy alias to v4.3.0 (reference/cli/operations-api-commands.md:79-83), while the 4.4.18 release note only says package deployment was added/fixed. Please use v4.3.0 for the command's introduction and annotate package-reference support separately as v4.4.18, or reconcile the older inventory if its date is incorrect.
— KrAIs (GPT-5.4)
| - `ignore_replication_errors=true` - Treat a peer that fails to receive the deploy as non-fatal instead of failing the whole operation. | ||
| - `force=true` - Allow deploying over a protected core component name. | ||
| - `urlPath=<path>` - HTTP path the component is mounted at (e.g. `/api/v2`). Requires `package`. | ||
| - `host=<hostname>` - Virtual hostname the component is served on (e.g. `api.example.com`). Requires `package`. |
There was a problem hiding this comment.
host was added in v5.2.0, but this parameter list sits under a v4.4.18 command badge. Without an inline availability marker, users on v4 or v5.1 can reasonably expect this option to work. Please add (Added in: v5.2.0) here, matching the repository's inline-option convention and the canonical operation reference.
— KrAIs (GPT-5.4)
…rams - Date the `deploy` command to v4.3.0 (matching the CLI operations inventory) and note package-reference support arrived in v4.4.18, instead of badging the whole command v4.4.18. - Annotate the v5.2.0 parameters inline: `host`, `deployment_timeout`, and `ignore_replication_errors`. - Add `deployment_timeout` and `ignore_replication_errors` to the canonical `deploy_component` operation reference (both v5.2.0) so the CLI page cross-reference resolves to a documented contract. - Rework the `credentials` bullet: it is an array of objects, which the CLI's key=value args cannot represent, so direct private-source deploys to the HTTP Operations API instead of advertising credentials=<json>. - Mention the legacy `username`/`password` auth params alongside `auth_username`/`auth_password`. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-624 This preview will update automatically when you push new commits. |
| - `deployment_timeout=<ms>` - How long, in milliseconds, a peer waits to receive the replicated payload before failing (default: `120000`). (Added in: v5.2.0) | ||
| - `ignore_replication_errors=true` - Treat a peer that fails to receive the deploy as non-fatal instead of failing the whole operation. (Added in: v5.2.0) |
There was a problem hiding this comment.
Medium: deployment_timeout and ignore_replication_errors shipped in v5.1.4, not v5.2.0
Both parameters were added on 2026-06-17 and the earliest release tag containing either commit is v5.1.4:
deployment_timeout—c4800b0e0"fix(deploy): make peer deployment-row wait configurable, default 120s (#1338)"ignore_replication_errors—65d20585c"deploy_component: fail the deploy on peer replication failures (non-zero exit) (#1334)"
(git tag --contains on both returns v5.1.4 as the first release.) Badging them v5.2.0 tells anyone on a 5.1.x server that a parameter they already have is unavailable. The host (v5.2.0, 79325af60) and credentials (v5.2.0, 3dbcf7b9e) annotations in this same commit are correct — it is only these two that are off.
Suggested fix:
| - `deployment_timeout=<ms>` - How long, in milliseconds, a peer waits to receive the replicated payload before failing (default: `120000`). (Added in: v5.2.0) | |
| - `ignore_replication_errors=true` - Treat a peer that fails to receive the deploy as non-fatal instead of failing the whole operation. (Added in: v5.2.0) | |
| - `deployment_timeout=<ms>` - How long, in milliseconds, a peer waits to receive the replicated payload before failing (default: `120000`). (Added in: v5.1.4) | |
| - `ignore_replication_errors=true` - Treat a peer that fails to receive the deploy as non-fatal instead of failing the whole operation. (Added in: v5.1.4) |
—
Generated by Barber AI
| - `deployment_timeout` <VersionBadge version="v5.2.0" /> — how long, in milliseconds, a peer waits to receive the replicated deployment payload before failing (default: `120000`) | ||
| - `ignore_replication_errors` <VersionBadge version="v5.2.0" /> — set to `true` to treat a peer that fails to receive the deploy as non-fatal instead of failing the whole operation. By default a failed peer causes `deploy_component` to return a non-2xx status; the component is still deployed (and, if requested, restarted) on the origin node. |
There was a problem hiding this comment.
Medium: same version error as the CLI page — these are v5.1.4 parameters
deployment_timeout (c4800b0e0, #1338) and ignore_replication_errors (65d20585c, #1334) both landed 2026-06-17 and first shipped in v5.1.4, not v5.2.0. Since this is the canonical operation reference the CLI page links to, the wrong badge here propagates.
Suggested fix:
| - `deployment_timeout` <VersionBadge version="v5.2.0" /> — how long, in milliseconds, a peer waits to receive the replicated deployment payload before failing (default: `120000`) | |
| - `ignore_replication_errors` <VersionBadge version="v5.2.0" /> — set to `true` to treat a peer that fails to receive the deploy as non-fatal instead of failing the whole operation. By default a failed peer causes `deploy_component` to return a non-2xx status; the component is still deployed (and, if requested, restarted) on the origin node. | |
| - `deployment_timeout` <VersionBadge version="v5.1.4" /> — how long, in milliseconds, a peer waits to receive the replicated deployment payload before failing (default: `120000`) | |
| - `ignore_replication_errors` <VersionBadge version="v5.1.4" /> — set to `true` to treat a peer that fails to receive the deploy as non-fatal instead of failing the whole operation. By default a failed peer causes `deploy_component` to return a non-2xx status; the component is still deployed (and, if requested, restarted) on the origin node. |
—
Generated by Barber AI
| - `host=<hostname>` - Virtual hostname the component is served on (e.g. `api.example.com`). Requires `package`. (Added in: v5.2.0) | ||
| - `json=true` - Print output as JSON instead of the default YAML. | ||
|
|
||
| Deploying from a private npm registry or git repository requires the `deploy_component` operation's `credentials` field (added in v5.2.0), which is an array of credential objects. The CLI's `key=value` arguments [do not support array-of-object parameters](./operations-api-commands.md#object-parameters), so supply `credentials` through the [Operations API](../operations-api/operations.md#deploy-credentials-credentials) over HTTP instead. |
There was a problem hiding this comment.
Medium: the CLI does have a path for private-git deploy credentials
The array-of-objects reasoning is right, but the conclusion ("use the Operations API over HTTP instead") is only true for a private npm registry. For a private git source the CLI builds the credentials array for you: bin/cliOperations.ts accepts by_ref / ref / credential as client-side-only args, and prepareDeployByRef() does
if (credentialHost && req.credentials === undefined) {
req.credentials = [{ host: credentialHost, secret: deriveGitSecretName(req.project, credentialHost) }];
}so harper deploy by_ref=true credential=true deploys a pinned private git commit with a sealed credential reference — no HTTP call needed. As written this line sends a reader to the Operations API for a case the CLI handles natively.
Suggested fix: scope the sentence to npm registries and point git users at the by_ref/credential args, e.g. "Deploying from a private npm registry requires the deploy_component operation's credentials field (added in v5.2.0) … supply it through the Operations API over HTTP instead. For a private git repository, use harper deploy by_ref=true credential=true, which builds the credential reference for you." (Note that by_ref, ref, and credential are currently undocumented anywhere in this repo — worth their own entry in the parameter list above.)
—
Generated by Barber AI
3 participants
Summary
Documents the
harper deployCLI command in the CLI reference. This command was undocumented on the commands page despite being available since v4.4.18 (with live streaming progress added in v5.1.0).Sourced from the Harper core code (
bin/cliOperations.ts,bin/help.ts,components/operations.js,components/operationsValidation.js).Changes
reference/cli/commands.md— new### harper deployentry under Process Management, covering:package=<ref>)target=<url>) deploys and how remote auth is resolveddeployment_id/system.hdb_deploymentrecordproject,package,target,restart(true/rolling),replicated,install_command,install_timeout,install_allow_scripts,deployment_timeout,ignore_replication_errors,force,urlPath,host,credentials,json, plus the directory-packaging optionsskip_node_modulesandskip_symlinksdeploy_componentoperation for full server-side behaviorreference/cli/overview.md— addedharper deployto the command table (Prettier realigned the table, hence the extra line churn)Verification
npm run format:check— cleannpm run build— succeeds; the two broken-anchor warnings are pre-existing (onbackups/overviewandrelease-notes/5.1) and unrelated to this changesent with Claude Opus 4.8