Skip to content

docs(cli): document the harper deploy command #624

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Ethan-Arrowood wants to merge 2 commits into
base: main
Choose a base branch
from
+84 −15
Open

docs(cli): document the harper deploy command #624

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0420792
docs(cli): document the `harper deploy` command for v5
Ethan-Arrowood Aug 12, 2026
97153cb
docs(cli): address review feedback on `harper deploy` timeline and pa…
Ethan-Arrowood Aug 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 66 additions & 0 deletions reference/cli/commands.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,72 @@ 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.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)
Comment on lines +147 to +148

@cb1kenobi cb1kenobi Aug 15, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

Suggested change
- `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

@cb1kenobi cb1kenobi Aug 19, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I confirmed that it should be 5.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.

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.

@cb1kenobi cb1kenobi Aug 15, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


**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
Expand Down
31 changes: 16 additions & 15 deletions reference/cli/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
2 changes: 2 additions & 0 deletions reference/operations-api/operations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.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.
Comment on lines +602 to +603

@cb1kenobi cb1kenobi Aug 15, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

Suggested change
- `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

@cb1kenobi cb1kenobi Aug 19, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I confirmed that it should be 5.1.4.


`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.

Expand Down