From 0420792e7b46dd5f5fe1e7d8349ecafc37b22966 Mon Sep 17 00:00:00 2001 From: Ethan Arrowood Date: Wed, 12 Aug 2026 10:54:31 -0400 Subject: [PATCH 1/3] docs(cli): document the `harper deploy` command for v5 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 --- reference/cli/commands.md | 63 +++++++++++++++++++++++++++++++++++++++ reference/cli/overview.md | 31 +++++++++---------- 2 files changed, 79 insertions(+), 15 deletions(-) diff --git a/reference/cli/commands.md b/reference/cli/commands.md index 549ef2cb5..ad5450453 100644 --- a/reference/cli/commands.md +++ b/reference/cli/commands.md @@ -92,6 +92,69 @@ harper dev /path/to/app - Uses a single thread for simpler debugging - Auto-restart on file changes +### `harper deploy` + + + +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=` 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=`. + +`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=`. + +**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 environment variables). See [Remote Operations](./overview.md#remote-operations). + +#### Live progress + + + +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=` - 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=` - An npm, GitHub, or tarball reference to deploy instead of the current directory (e.g. `HarperDB/app#semver:v1.0.0`). +- `target=` - Remote Harper instance to deploy to. Omit to deploy to the local instance. A bare host defaults to `https://: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=` - Override the install command run for the component. +- `install_timeout=` - 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=` - How long, in milliseconds, a peer waits to receive the replicated payload before failing. +- `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=` - HTTP path the component is mounted at (e.g. `/api/v2`). Requires `package`. +- `host=` - Virtual hostname the component is served on (e.g. `api.example.com`). Requires `package`. +- `credentials=` - Authentication for installing from a private npm registry or git repository. See [`deploy_component` credentials](../operations-api/operations.md#deploy-credentials-credentials). +- `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. + ### `harper restart` Available since: v4.1.0 diff --git a/reference/cli/overview.md b/reference/cli/overview.md index dbf522179..e177246c3 100644 --- a/reference/cli/overview.md +++ b/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 ` | Run Harper application from any directory | v4.2.0 | -| `harper dev ` | 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 ` | 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 ` | Run Harper application from any directory | v4.2.0 | +| `harper dev ` | 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.4.18 | +| `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 ` | 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. From 97153cb23043fdfdee714d8c758064b5ef3b7865 Mon Sep 17 00:00:00 2001 From: Ethan Arrowood Date: Thu, 13 Aug 2026 09:10:35 -0400 Subject: [PATCH 2/3] docs(cli): address review feedback on `harper deploy` timeline and params - 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=. - Mention the legacy `username`/`password` auth params alongside `auth_username`/`auth_password`. Co-Authored-By: Claude Opus 4.8 --- reference/cli/commands.md | 15 +++++++++------ reference/cli/overview.md | 2 +- reference/operations-api/operations.md | 2 ++ 3 files changed, 12 insertions(+), 7 deletions(-) diff --git a/reference/cli/commands.md b/reference/cli/commands.md index ad5450453..848dbab46 100644 --- a/reference/cli/commands.md +++ b/reference/cli/commands.md @@ -94,10 +94,12 @@ harper dev /path/to/app ### `harper deploy` - + 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=` 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=`. +`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**: @@ -120,7 +122,7 @@ harper deploy package=HarperDB/application-template 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). +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 @@ -142,14 +144,15 @@ All parameters are passed as `key=value` arguments. Every parameter is optional. - `install_command=` - Override the install command run for the component. - `install_timeout=` - 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=` - How long, in milliseconds, a peer waits to receive the replicated payload before failing. -- `ignore_replication_errors=true` - Treat a peer that fails to receive the deploy as non-fatal instead of failing the whole operation. +- `deployment_timeout=` - 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) - `force=true` - Allow deploying over a protected core component name. - `urlPath=` - HTTP path the component is mounted at (e.g. `/api/v2`). Requires `package`. -- `host=` - Virtual hostname the component is served on (e.g. `api.example.com`). Requires `package`. -- `credentials=` - Authentication for installing from a private npm registry or git repository. See [`deploy_component` credentials](../operations-api/operations.md#deploy-credentials-credentials). +- `host=` - 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. + **Packaging options** (directory deploy only): - `skip_node_modules=false` - Include the `node_modules` directory in the packaged tarball. Excluded by default. diff --git a/reference/cli/overview.md b/reference/cli/overview.md index e177246c3..37eac5a6e 100644 --- a/reference/cli/overview.md +++ b/reference/cli/overview.md @@ -100,7 +100,7 @@ kill -0 $(cat /path/to/hdb/hdb.pid) # Check if process is running | `harper` | Run Harper in foreground mode (default behavior) | v4.1.0 | | `harper run ` | Run Harper application from any directory | v4.2.0 | | `harper dev ` | 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.4.18 | +| `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 | diff --git a/reference/operations-api/operations.md b/reference/operations-api/operations.md index 72adbfd64..dfcce3589 100644 --- a/reference/operations-api/operations.md +++ b/reference/operations-api/operations.md @@ -599,6 +599,8 @@ Additional parameters: - `host` — 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` — how long, in milliseconds, a peer waits to receive the replicated deployment payload before failing (default: `120000`) +- `ignore_replication_errors` — 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. From 038d7c4fc0747739c86d3388dceaa07e139573cd Mon Sep 17 00:00:00 2001 From: Ethan Arrowood Date: Fri, 21 Aug 2026 15:24:15 -0600 Subject: [PATCH 3/3] docs(cli): correct deploy param versions and document deploy-by-reference - Fix `deployment_timeout` and `ignore_replication_errors` version to v5.1.4 (not v5.2.0) on both the CLI commands page and the canonical deploy_component operation reference. Both landed in #1338/#1334 and first shipped in v5.1.4; a human reviewer confirmed the version. - Document deploy-by-reference (v5.2.3): the `by_ref`, `ref`, `credential`, and `setup` args, with a "Deploy by reference" section. - Rework private-source deploy guidance: private git repositories use `harper deploy setup=true` to seal a durable credential, then `by_ref=true credential=true`; private npm registries still go through the HTTP Operations API (the CLI cannot express the nested credentials array). Co-Authored-By: Claude Opus 4.8 --- reference/cli/commands.md | 47 +++++++++++++++++++++++--- reference/operations-api/operations.md | 4 +-- 2 files changed, 45 insertions(+), 6 deletions(-) diff --git a/reference/cli/commands.md b/reference/cli/commands.md index 848dbab46..16cf42e13 100644 --- a/reference/cli/commands.md +++ b/reference/cli/commands.md @@ -144,20 +144,59 @@ All parameters are passed as `key=value` arguments. Every parameter is optional. - `install_command=` - Override the install command run for the component. - `install_timeout=` - 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=` - 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=` - 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=` - HTTP path the component is mounted at (e.g. `/api/v2`). Requires `package`. - `host=` - 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. - **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=` - 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 + + + +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//.git#` 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 + + + +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 diff --git a/reference/operations-api/operations.md b/reference/operations-api/operations.md index dfcce3589..8f4d2f39f 100644 --- a/reference/operations-api/operations.md +++ b/reference/operations-api/operations.md @@ -599,8 +599,8 @@ Additional parameters: - `host` — 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` — how long, in milliseconds, a peer waits to receive the replicated deployment payload before failing (default: `120000`) -- `ignore_replication_errors` — 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` — how long, in milliseconds, a peer waits to receive the replicated deployment payload before failing (default: `120000`) +- `ignore_replication_errors` — 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.