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.
| harper deploy target=https://server.com:9925 restart=true | ||
| ``` | ||
|
|
||
| Remote deploys authenticate the same way as any other remote CLI operation (stored login token, `auth_username`/`auth_password`, or environment variables). See [Remote Operations](./overview.md#remote-operations). |
There was a problem hiding this comment.
High: wrong parameter names for remote auth
This says remote deploys can authenticate with auth_username/auth_password, but that's not a real parameter name. Both the CLI source (bin/cliOperations.ts, which reads req.username/req.password) and this repo's own Remote Operations section document the parameters as username=<user> password=<pass> (no auth_ prefix). A reader following this line would pass a parameter the CLI silently ignores.
Suggested fix:
| Remote deploys authenticate the same way as any other remote CLI operation (stored login token, `auth_username`/`auth_password`, or environment variables). See [Remote Operations](./overview.md#remote-operations). | |
| Remote deploys authenticate the same way as any other remote CLI operation (stored login token, `username`/`password`, or environment variables). See [Remote Operations](./overview.md#remote-operations). |
—
Generated by Barber AI
| - `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.
High: host parameter is not implemented for deploy
deployComponent in components/operations.js never reads req.host, and deployComponentValidator in components/operationsValidation.js doesn't include it either. The applicationConfig object written via configUtils.addConfig() is built explicitly as { package, install?, urlPath? } — there is no path that writes a host/virtual-hostname value. Passing host=<hostname> to harper deploy is a silent no-op, not a way to set the component's virtual hostname.
Suggested fix: remove this parameter (or confirm with the Harper team whether it's planned/unshipped, and mark it as such rather than documenting it as supported).
—
Generated by Barber AI
| - `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.
High: credentials parameter doesn't exist, and the anchor is broken
Two issues on this line:
credentialsis not a realdeploy_componentparameter — it's absent fromdeployComponentValidator, fromdeployComponent()'s handling ofreq, and fromApplication.ts's install logic. I couldn't find it referenced anywhere inharperorharper-proin connection with deploy/install/npm/registry auth.- The link target
../operations-api/operations.md#deploy-credentials-credentialsdoesn't resolve —reference/operations-api/operations.mdhas no heading that produces that anchor (itsdeploy_componentsection has no credentials subsection at all).
Suggested fix: remove this parameter/line, or replace it with the real mechanism for private-registry auth during deploy (e.g. add_ssh_key for private git deploys, documented at ../operations-api/operations.md#add_ssh_key), if that's what was intended.
—
Generated by Barber AI
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)
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