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 1 commit into
base: main
Choose a base branch
from
+79 −15
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
63 changes: 63 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,69 @@ harper dev /path/to/app
- Uses a single thread for simpler debugging
- Auto-restart on file changes

### `harper deploy`

<VersionBadge version="v4.4.18" />

@kriszyp kriszyp Aug 12, 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.

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)


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

`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 environment variables). See [Remote Operations](./overview.md#remote-operations).

@cb1kenobi cb1kenobi Aug 12, 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.

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:

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


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

@kriszyp kriszyp Aug 12, 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.

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)

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

@kriszyp kriszyp Aug 12, 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.

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)

@cb1kenobi cb1kenobi Aug 12, 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.

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

- `credentials=<json>` - Authentication for installing from a private npm registry or git repository. See [`deploy_component` credentials](../operations-api/operations.md#deploy-credentials-credentials).

@kriszyp kriszyp Aug 12, 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.

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)

@cb1kenobi cb1kenobi Aug 12, 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.

High: credentials parameter doesn't exist, and the anchor is broken

Two issues on this line:

  1. credentials is not a real deploy_component parameter — it's absent from deployComponentValidator, from deployComponent()'s handling of req, and from Application.ts's install logic. I couldn't find it referenced anywhere in harper or harper-pro in connection with deploy/install/npm/registry auth.
  2. The link target ../operations-api/operations.md#deploy-credentials-credentials doesn't resolve — reference/operations-api/operations.md has no heading that produces that anchor (its deploy_component section 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

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