docs(cli): document the harper deploy command

reference/cli/commands.md

@@ -92,6 +92,111 @@ harper dev /path/to/app
 - Uses a single thread for simpler debugging
 - Auto-restart on file changes
 
+### `harper deploy`
+
+<VersionBadge version="v4.3.0" />
+
+Package and deploy a Harper component (application). With no `package`, `harper deploy` packages the current working directory into a tarball and deploys it; with `package=<reference>` it deploys from an npm, GitHub, or tarball reference instead of packaging local files. It deploys to the local Harper instance by default, or to a remote instance with `target=<url>`.
+
+`deploy` is an alias for the `deploy_component` operation, available through the CLI since v4.3.0. Deploying from a package reference was added in v4.4.18.
+
+`harper deploy` is a shorthand for the [`deploy_component`](../operations-api/operations.md#deploy_component) operation run against the current directory. See that operation for the full server-side behavior (deployment records, credentials, replication semantics); this page covers CLI-specific usage.
+
+**Deploy the current directory to the local instance**:
+
+```bash
+harper deploy
+```
+
+The project name defaults to the current directory's name. Override it with `project=<name>`.
+
+**Deploy a package reference**:
+
+```bash
+harper deploy package=HarperDB/application-template
+```
+
+**Deploy to a remote instance and restart it afterward**:
+
+```bash
+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 the legacy `username`/`password`, or environment variables). See [Remote Operations](./overview.md#remote-operations).
+
+#### Live progress
+
+<VersionBadge type="changed" version="v5.1.0" />
+
+Deploys stream live progress: an upload progress bar followed by real-time install output, as the deploy advances through its phases (prepare → load → replicate → restart). Against Harper servers older than 5.1, the CLI automatically falls back to a non-streaming deploy without live progress.
+
+Every deploy is recorded in the `system.hdb_deployment` table and the response includes a `deployment_id` you can use to query the deployment record. See [Deployment Operations](../operations-api/operations.md#deployment-operations).
+
+#### Parameters
+
+All parameters are passed as `key=value` arguments. Every parameter is optional.
+
+- `project=<name>` - Component project name. Defaults to the current directory's name for a directory deploy, or is derived from the package for a package deploy.
+- `package=<reference>` - An npm, GitHub, or tarball reference to deploy instead of the current directory (e.g. `HarperDB/app#semver:v1.0.0`).
+- `target=<url>` - Remote Harper instance to deploy to. Omit to deploy to the local instance. A bare host defaults to `https://<host>:9925`.
+- `restart=true` or `restart=rolling` - Restart Harper after deploying. Use `rolling` for a staggered, zero-downtime restart across a cluster.
+- `replicated=true` - Replicate the deploy to cluster peers.
+- `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 (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)
+- `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`. (Added in: v5.2.0)
+- `json=true` - Print output as JSON instead of the default YAML.
+
+**Packaging options** (directory deploy only):
+
+- `skip_node_modules=false` - Include the `node_modules` directory in the packaged tarball. Excluded by default.
+- `skip_symlinks=true` - Exclude symlinks from the packaged tarball. Included by default; broken (dangling) symlinks are always skipped with a warning.
+
+**Deploy-by-reference options** (see [Deploy by reference](#deploy-by-reference)):
+
+- `by_ref=true` - Deploy the current project from its GitHub `origin` remote as a pinned commit (`git+https`) instead of uploading a packaged tarball. (Added in: v5.2.3)
+- `ref=<committish>` - The branch, tag, or commit to deploy. Resolved to an immutable commit SHA so every cluster node deploys the same commit. Defaults to the current `HEAD`; implies `by_ref`. (Added in: v5.2.3)
+- `credential=true` - Attach the sealed credential reference so the cluster can clone a private repository. Provision it first with `harper deploy setup=true`. (Added in: v5.2.3)
+- `setup=true` - Provision (seal) a durable encrypted credential for a private deploy source instead of deploying. Interactive. (Added in: v5.2.3)
+
+#### Deploy by reference
+
+<VersionBadge version="v5.2.3" />
+
+Instead of packaging and uploading the working directory, `harper deploy by_ref=true` deploys a pinned git commit by reference: it resolves the project's GitHub `origin` remote and commit (from the local checkout or the GitHub Actions environment) and hands the cluster a `git+https://github.com/<owner>/<repo>.git#<sha>` package to clone. The commit is pinned to an immutable SHA so every cluster node deploys the same code.
+
+```bash
+# Deploy the current HEAD by reference
+harper deploy by_ref=true
+
+# Deploy a specific branch, tag, or commit
+harper deploy by_ref=true ref=v1.2.3
+```
+
+The commit must be pushed to the remote before deploying, so the cluster can clone it; the CLI warns if the working tree is dirty or the commit is not on any remote branch. Only GitHub `origin` remotes are supported.
+
+#### Private deploy sources
+
+<VersionBadge version="v5.2.3" />
+
+Installing a component from a private npm registry or a private git repository requires the `deploy_component` operation's [`credentials`](../operations-api/operations.md#deploy-credentials-credentials) field, 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 there are two supported paths:
+
+- **Private git repository** - Provision the credential once with `harper deploy setup=true`, which seals an encrypted token (from `gh auth token` or a pasted PAT) on your machine using the cluster's public key and stores only the ciphertext. Then deploy with `credential=true`, which attaches the sealed credential reference for the clone:
+
+  ```bash
+  # One-time: seal a durable credential for the private repo
+  harper deploy setup=true
+
+  # Deploy the private repo by reference, using the sealed credential
+  harper deploy by_ref=true credential=true
+  ```
+
+- **Private npm registry** - Supply the `credentials` array through the [Operations API](../operations-api/operations.md#deploy-credentials-credentials) over HTTP, which can represent the nested object shape the CLI arguments cannot.
+
 ### `harper restart`
 
 Available since: v4.1.0

reference/cli/overview.md

@@ -95,21 +95,22 @@ kill -0 $(cat /path/to/hdb/hdb.pid)  # Check if process is running
 
 ## System Management Commands
 
-| Command                            | Description                                                  | Available Since |
-| ---------------------------------- | ------------------------------------------------------------ | --------------- |
-| `harper`                           | Run Harper in foreground mode (default behavior)             | v4.1.0          |
-| `harper run <path/to/app>`         | Run Harper application from any directory                    | v4.2.0          |
-| `harper dev <path/to/app>`         | Run Harper in dev mode with auto-restart and console logging | v4.2.0          |
-| `harper restart`                   | Restart Harper                                               | v4.1.0          |
-| `harper start`                     | Start Harper in background (daemon mode)                     | v4.1.0          |
-| `harper stop`                      | Stop a running Harper instance                               | v4.1.0          |
-| `harper login`                     | Log in to a Harper instance                                  | v5.0.0          |
-| `harper logout`                    | Log out of a Harper instance                                 | v5.0.0          |
-| `harper status`                    | Display Harper and clustering status                         | v4.1.0          |
-| `harper version`                   | Show installed Harper version                                | v4.1.0          |
-| `harper renew-certs`               | Renew Harper-generated self-signed certificates              | v4.1.0          |
-| `harper copy-db <source> <target>` | Copy a database with compaction                              | v4.1.0          |
-| `harper help`                      | Display all available CLI commands                           | v4.1.0          |
+| Command                            | Description                                                     | Available Since |
+| ---------------------------------- | --------------------------------------------------------------- | --------------- |
+| `harper`                           | Run Harper in foreground mode (default behavior)                | v4.1.0          |
+| `harper run <path/to/app>`         | Run Harper application from any directory                       | v4.2.0          |
+| `harper dev <path/to/app>`         | Run Harper in dev mode with auto-restart and console logging    | v4.2.0          |
+| `harper deploy`                    | Package and deploy the current directory or a package reference | v4.3.0          |
+| `harper restart`                   | Restart Harper                                                  | v4.1.0          |
+| `harper start`                     | Start Harper in background (daemon mode)                        | v4.1.0          |
+| `harper stop`                      | Stop a running Harper instance                                  | v4.1.0          |
+| `harper login`                     | Log in to a Harper instance                                     | v5.0.0          |
+| `harper logout`                    | Log out of a Harper instance                                    | v5.0.0          |
+| `harper status`                    | Display Harper and clustering status                            | v4.1.0          |
+| `harper version`                   | Show installed Harper version                                   | v4.1.0          |
+| `harper renew-certs`               | Renew Harper-generated self-signed certificates                 | v4.1.0          |
+| `harper copy-db <source> <target>` | Copy a database with compaction                                 | v4.1.0          |
+| `harper help`                      | Display all available CLI commands                              | v4.1.0          |
 
 See [CLI Commands](./commands.md) for detailed documentation on each command.
 

reference/operations-api/operations.md

@@ -599,6 +599,8 @@ Additional parameters:
 - `host` <VersionBadge version="v5.2.0" /> — the virtual hostname the component is served on (e.g. `"api.example.com"`). Must be a bare hostname or IPv6 literal — no scheme, port, path, or brackets. Persisted alongside `urlPath`.
 - `install_allow_scripts` — set to `true` to allow npm pre/post install scripts (disabled by default)
 - `credentials` — credentials for installing a component from a private npm registry or private git repository (see below)
+- `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.
 
 `urlPath` and `host` both require `package` and are rejected on a payload-only deploy. To mount a payload-deployed component, add `host`/`urlPath` to its entry in the root `harper-config.yaml` instead.