From 0420792e7b46dd5f5fe1e7d8349ecafc37b22966 Mon Sep 17 00:00:00 2001 From: Ethan Arrowood Date: Wed, 12 Aug 2026 10:54:31 -0400 Subject: [PATCH 1/2] 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 549ef2cb..ad545045 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 dbf52217..e177246c 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/2] 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 ad545045..848dbab4 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 e177246c..37eac5a6 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 72adbfd6..dfcce358 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.