CLI Commands

This page documents the core Harper CLI commands for managing Harper instances. For Operations API commands available through the CLI, see Operations API Commands.

Process Management Commands

harper

Added in: v4.1.0

Run Harper in the foreground as a standard process. This is the recommended way to run Harper.

harper

When you run harper:

• If Harper is not installed, it will guide you through the installation process
• Once installed, it runs Harper in the foreground as a standard process, compatible with systemd, Docker, and other process management tools

First-Time Installation:

If Harper is not installed, you can provide configuration parameters via environment variables or command line arguments:

Using Environment Variables:

# Minimum required parameters for no additional CLI prompts
export TC_AGREEMENT=yes
export HDB_ADMIN_USERNAME=HDB_ADMIN
export HDB_ADMIN_PASSWORD=password
export ROOTPATH=/hdb/
harper

note

If you specify DEFAULT_MODE=dev you will also need to specify the REPLICATION_HOSTNAME=localhost

Using Command Line Arguments:

# Minimum required parameters for no additional CLI prompts
harper \
  --TC_AGREEMENT=yes \
  --HDB_ADMIN_USERNAME=HDB_ADMIN \
  --HDB_ADMIN_PASSWORD=password \
  --ROOTPATH='/hdb'

Note: When used in conjunction, command line arguments override environment variables. See Configuration for a full list of configuration parameters.

info

For more information on installation, see Getting Started / Install and Connect Harper.

harper run

Added in: v4.2.0

Run a Harper application from any location as a foreground, standard process (similar to harper).

harper run /path/to/app

This command runs Harper with the specified application directory without automatic reloading or dev-specific features.

harper dev

Added in: v4.2.0

Run Harper in development mode from a specified directory with automatic reloading. Recommended for local application development. Operates similar to harper and harper run.

harper dev /path/to/app

Features:

• Pushes logs to standard streams automatically
• Uses a single thread for simpler debugging
• Auto-restart on file changes

harper deploy

Added in: v4.4.18

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 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:

harper deploy

The project name defaults to the current directory's name. Override it with project=<name>.

Deploy a package reference:

harper deploy package=HarperDB/application-template

Deploy to a remote instance and restart it afterward:

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.

Live progress

Changed in: 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.

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.
• 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.
• credentials=<json> - Authentication for installing from a private npm registry or git repository. See deploy_component 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

Restart a running Harper instance regardless if its a foreground (harper, harper run, or harper dev) or background (harper start) process.

harper restart

harper start

Available since: v4.1.0

Start Harper in background (daemon mode).

harper start

After installation, this command launches Harper as a background process. Remember that the Harper PID is available in a hdb.pid file within the installation directory.

harper stop

Available since: v4.1.0

Stop a running Harper instance.

harper stop

Installation Commands

harper install

Available since: v4.1.0

Install Harper with interactive prompts or automated configuration.

harper install

The harper install command operates exactly like the harper command, but exits as soon as the installation completes. See the harper command documentation above for details on providing configuration parameters via environment variables or command line arguments.

Note: We recommend using harper instead of harper install as it provides a consistent workflow for both installation and running Harper.

harper login

Available since: v5.0.0

Log in to a Harper instance to store authentication tokens locally. Once logged in, subsequent commands targeting this instance (via target) will automatically use the stored token.

The CLI also supports .env files. When you log in, the HARPER_CLI_TARGET environment variable will be automatically added to a .env file in your current directory if it exists. This allows you to omit the target parameter in subsequent commands within that directory.

harper login <URL>

Optional Parameters:

• <URL> - The URL of the Harper instance to log in to.

Prompts:

You'll be asked to type in the following information:

• <URL> - If a URL parameter is not provided, you'll be prompted to enter the URL of the Harper instance to log in to.
• <username> - Harper admin username.
• <password> - Harper admin password.

harper logout

Available since: v5.0.0

Log out of a Harper instance and remove the stored authentication token.

harper logout <URL>

Optional Parameters:

• <URL> - The URL of the Harper instance to log out from. If none is provided, you'll be signed out of all instances.

Information Commands

harper version

Available since: v4.1.0

Display the installed Harper version.

harper version

Example Output:

4.7.0

harper status

Available since: v4.1.0

Display the status of Harper and clustering.

harper status

Shows:

• Harper process status
• Clustering network status
• Replication statuses

In Harper versions where NATS is supported, this command also shows the clustering hub and leaf processes too.

harper help

Available since: v4.1.0

Display all available Harper CLI commands with brief descriptions.

harper help

Maintenance Commands

harper renew-certs

Available since: v4.1.0

Renew Harper-generated self-signed certificates.

harper renew-certs

This command regenerates the self-signed SSL/TLS certificates used by Harper.

harper copy-db

Available since: v4.1.0

Copy a Harper database with compaction to eliminate free-space and fragmentation.

harper copy-db <source-database> <target-database-path>

Parameters:

• <source-database> - Name of the source database
• <target-database-path> - Full path to the target database file

Example:

harper copy-db data /home/user/hdb/database/copy.mdb

This copies the default data database to a new location with compaction applied.

Use Cases:

• Database optimization
• Eliminating fragmentation
• Creating compacted backups
• Reclaiming free space

See also: Database Compaction for more information.

How Backups Work

Which backup approach to use depends on the storage engine: use volume snapshots for LMDB databases, and the RocksDB backup engine (harper create_backup) for RocksDB databases. The RocksDB backup engine produces incremental, checksum-verified backups directly, with no need for atomic volume snapshots. The rest of this section covers the volume-snapshot approach.

Harper uses a transactional commit process that ensures data on disk is always transactionally consistent with storage. This means Harper maintains database integrity in the event of a crash and allows you to use standard volume snapshot tools to make backups.

Backup Process:

Database files are stored in the hdb/database directory. As long as the snapshot is an atomic snapshot of these database files, the data can be copied/moved back into the database directory to restore a previous backup (with Harper shut down), and database integrity will be preserved.

Important Notes:

• Atomic Snapshots: Use volume snapshot tools for LMDB databases and the RocksDB backup engine for RocksDB databases.
• Not Safe: Simply copying an in-use database file using cp is not reliable
  • Progressive reads occur at different points in time
  • Results in an unreliable copy that likely won't be usable
• Safe Copying: Standard file copying is only reliable for database files that are not in use

Recommended Backup Tools:

• LVM snapshots
• ZFS snapshots
• BTRFS snapshots
• Cloud provider volume snapshots (AWS EBS, Azure Disk, GCP Persistent Disk)
• Enterprise backup solutions with snapshot capabilities

Remote Operations

The CLI supports executing commands on remote Harper instances. For details, see CLI Overview - Remote Operations.

See Also

• CLI Overview - General CLI information
• Operations API Commands - Operations available through CLI
• CLI Authentication - Authentication mechanisms
• Configuration - Configuration parameters for installation
• Database Compaction - More on database compaction