@harperfast/harper 5.2.0-beta.4 → 5.2.1

package/bin/backup.ts

@@ -0,0 +1,169 @@
+'use strict';
+
+import { createWriteStream } from 'node:fs';
+import { rename, unlink } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import * as YAML from 'yaml';
+import * as envMgr from '../utility/environment/environmentManager.ts';
+envMgr.initSync();
+import * as terms from '../utility/hdbTerms.ts';
+import { buildRequest, cliOperations, resolveRequestOptions } from './cliOperations.ts';
+import { loadCredentials } from './cliCredentials.ts';
+import { httpRequest } from '../utility/common_utils.ts';
+import { initConfig } from '../config/configUtils.ts';
+import { getHdbPid } from '../utility/processManagement/processManagement.js';
+import {
+	createBackupOffline,
+	deleteBackupOffline,
+	listBackupsOffline,
+	purgeBackupsOffline,
+	restoreBackupOffline,
+	verifyBackupOffline,
+} from '../dataLayer/rocksdbBackup.ts';
+
+const { OPERATIONS_ENUM } = terms;
+
+/**
+ * Runs a backup operation from the CLI. `command` is the operation name (e.g. `create_backup`);
+ * there is no hyphenated alias. Each works whether or not Harper is running: RocksDB is
+ * single-writer, so when a server is reachable the running process must own the database handle
+ * and the operation is forwarded to it (also handling remote `target=` and auth); only when the
+ * *local* server is stopped do we open the database/backup files directly. `get_backup` is the
+ * exception — it streams a live snapshot from a running server and has no offline form.
+ */
+export async function runBackupCommand(command: string): Promise<void> {
+	// Load .env before anything reads process.env — useOperationApi and resolveRequestOptions key
+	// the local-vs-remote routing off HARPER_CLI_TARGET/CLI_TARGET, and without this a `.env`-
+	// configured remote target would be invisible, silently running a destructive op locally
+	// (cliOperations does the same on its first line).
+	require('dotenv').config();
+	const request = buildRequest();
+	const databaseName = request.database || 'data';
+
+	// We print results here (not by returning a string) so the CLI's top-level handler doesn't
+	// re-emit them through logger.notify — this keeps output identical to forwarding the operation
+	// to a running server, which the online branch below simply delegates to.
+	if (command === OPERATIONS_ENUM.GET_BACKUP) {
+		console.log(await downloadBackup(request, databaseName));
+		return;
+	}
+
+	// Fall back to direct file access only when there is no server to talk to (no target and the
+	// local instance is stopped). We never fall back on a *reachable* server's error response —
+	// e.g. restore_backup rejecting the system/component-held database (whose offline path is to
+	// stop the server and rerun this same command, which then takes the branch below).
+	if (useOperationApi(request)) {
+		request.operation = command;
+		await cliOperations(request); // prints its own result, exactly like any forwarded operation
+		return;
+	}
+
+	let result: any;
+	switch (command) {
+		case OPERATIONS_ENUM.CREATE_BACKUP:
+			result = await createBackupOffline(databaseName, request.exclude_blobs === true);
+			break;
+		case OPERATIONS_ENUM.LIST_BACKUPS:
+			result = await listBackupsOffline(databaseName);
+			break;
+		case OPERATIONS_ENUM.VERIFY_BACKUP:
+			result = await verifyBackupOffline(databaseName, request.backup_id, request.verify_checksum);
+			break;
+		case OPERATIONS_ENUM.DELETE_BACKUP:
+			result = await deleteBackupOffline(databaseName, request.backup_id);
+			break;
+		case OPERATIONS_ENUM.PURGE_BACKUPS:
+			result = await purgeBackupsOffline(databaseName, request.keep_count);
+			break;
+		case OPERATIONS_ENUM.RESTORE_BACKUP:
+			result = await restoreBackupOffline(databaseName, request.backup_id, request.target_database);
+			break;
+		default:
+			throw new Error(`Unknown backup command '${command}'`);
+	}
+	console.log(YAML.stringify(result).trim());
+}
+
+/**
+ * Whether the target of a saved `last_target` is the local instance (localhost / loopback). A
+ * `harper login` against a local server saves `http://localhost:9925/`, which must NOT be treated as
+ * a remote target — otherwise the offline backup commands would try to reach a stopped local server
+ * instead of falling back to direct file access.
+ */
+function isLocalTarget(target: string): boolean {
+	try {
+		const url = new URL(target.includes('://') ? target : `http://${target}`);
+		const host = url.hostname.replace(/^\[|\]$/g, ''); // strip IPv6 brackets
+		return host === 'localhost' || host === '::1' || host.startsWith('127.');
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Whether to route a backup command through the operation API rather than direct file access. An
+ * explicit `target=`/env target, or a saved `last_target` pointing at a *remote* server, always
+ * implies talking to a server. A saved *local* `last_target` does not: the offline backup commands
+ * exist to work on local files while the local server is stopped, so a local/absent target falls
+ * through to the liveness check — the API only when the local instance is actually running
+ * (`getHdbPid` verifies process liveness, so a stale pid file reads as stopped).
+ */
+function useOperationApi(request: any): boolean {
+	const lastTarget = loadCredentials()?.last_target;
+	if (
+		request.target ||
+		process.env.HARPER_CLI_TARGET ||
+		process.env.CLI_TARGET ||
+		(lastTarget && !isLocalTarget(lastTarget))
+	) {
+		return true;
+	}
+	initConfig();
+	return Boolean(getHdbPid());
+}
+
+/**
+ * `get_backup` streams a full-snapshot tar of the database's current state from a running server
+ * into a local file. It works against a remote server (`target=…`) or the local instance, resolving
+ * the target and auth the same way as any other CLI operation; a local connection requires Harper to
+ * be running (there is no offline form). For RocksDB the stream is gzipped by default (pass
+ * `gzip=false` for a plain tar) and includes the database's file-backed blobs by default (pass
+ * `exclude_blobs=true` for an engine-only archive). While stopped, use `create_backup` — a local
+ * incremental directory backup — instead.
+ */
+async function downloadBackup(request: any, databaseName: string): Promise<string> {
+	// only forward gzip/exclude_blobs when the user passed them — they are RocksDB-only options
+	// (sending them unconditionally would fail LMDB downloads), and when unset the server applies its
+	// own defaults (RocksDB gzips and includes blobs)
+	const body: any = { operation: terms.OPERATIONS_ENUM.GET_BACKUP, database: databaseName };
+	if (request.gzip !== undefined) body.gzip = request.gzip;
+	if (request.exclude_blobs !== undefined) body.exclude_blobs = request.exclude_blobs;
+	// resolveRequestOptions connects to a remote target (target=/env/saved) or the local domain
+	// socket with auth; for a local connection it enforces that Harper is running.
+	const { options } = await resolveRequestOptions(request);
+	options.streamResponse = true;
+	const response = await httpRequest(options, body);
+	if (response.statusCode !== 200) {
+		const chunks: Buffer[] = [];
+		for await (const chunk of response) chunks.push(Buffer.from(chunk));
+		throw new Error(`get_backup failed (${response.statusCode}): ${Buffer.concat(chunks).toString('utf8')}`);
+	}
+	// name the file after what the server is sending (RocksDB: <db>.tar[.gz]; LMDB: the database file).
+	// basename() strips any path from the server-supplied filename — a malicious/compromised target
+	// could otherwise return `../../…` and steer the write outside the cwd.
+	const serverFilename = response.headers['content-disposition']?.match(/filename="([^"]+)"/)?.[1];
+	const outputPath = request.out || (serverFilename && basename(serverFilename)) || `${databaseName}.backup`;
+	// Stream to a temporary sibling and rename on success, so a network/server failure mid-download
+	// neither truncates an existing known-good backup at `outputPath` nor leaves a partial file that
+	// looks complete. The temp name is unique per process+time so concurrent downloads never collide.
+	const tempPath = `${outputPath}.${process.pid}-${Date.now()}.part`;
+	try {
+		await pipeline(response, createWriteStream(tempPath, { flags: 'wx' }));
+		await rename(tempPath, outputPath);
+	} catch (error) {
+		await unlink(tempPath).catch(() => {});
+		throw error;
+	}
+	return `Backup of database '${databaseName}' written to ${outputPath}`;
+}

package/bin/cliOperations.ts

@@ -389,9 +389,16 @@ async function refreshExpiredOperationToken(
  * @param skipResponseLog By default, the response is logged to the console. Set this to true to skip logging it, which can be useful for sensitive responses like login calls!
  * @returns {Promise<void>}
  */
-async function cliOperations(req: any, skipResponseLog = false) {
-	require('dotenv').config();
-
+/**
+ * Resolve the transport options for a CLI operation request: a remote target URL (with auth) when
+ * one is configured (`target=`, env, or a saved `last_target`), otherwise the local domain socket.
+ * Returns the `options` object ready for `httpRequest` (method + Content-Type, and an Authorization
+ * header for remote targets, refreshing an expired operation token when possible) plus the resolved
+ * `target` (undefined for a local connection). Exits the process if a local connection is required
+ * but Harper is not running or has no domain socket. Shared by `cliOperations` and the CLI's
+ * streaming `get_backup` download so both reach local and remote servers the same way.
+ */
+export async function resolveRequestOptions(req: any): Promise<{ options: any; target: any }> {
 	const allCredentials = loadCredentials();
 	const rawTarget = resolveTarget(req, allCredentials);
 	// Userinfo is a transport credential, and `normalizeTarget` strips it so the resolved target can
@@ -434,81 +441,93 @@ async function cliOperations(req: any, skipResponseLog = false) {
 			process.exit(1);
 		}
 	}
-	await PREPARE_OPERATION[req.operation]?.(req);
-	try {
-		let options = target ?? {
-			protocol: 'http:',
-			socketPath: getConfigPath(terms.CONFIG_PARAMS.OPERATIONSAPI_NETWORK_DOMAINSOCKET),
-		};
-		options.method = 'POST';
-		options.headers = { 'Content-Type': 'application/json' };
-		options.timeout = SSE_OPERATIONS.has(req.operation) ? SSE_OPERATION_TIMEOUT_MS : CLI_OPERATION_TIMEOUT_MS;
-		// Authentication precedence: explicitly configured credentials (dedicated args, URL
-		// userinfo, env vars) beat everything, then env-var tokens, then the saved `harper login`
-		// token, and only then the legacy `username=`/`password=` payload fallback below. The
-		// tokens must outrank that fallback: for add_user/alter_user those args are the credentials
-		// of the user being created/altered, so treating them as auth would authenticate as a user
-		// who doesn't exist yet (or as the wrong identity) instead of using the admin's session.
-		const transportCredentials = target ? resolveTransportCredentials(req, urlCredentials) : undefined;
-		if (transportCredentials) {
-			options.headers.Authorization = basicAuthHeader(transportCredentials.username, transportCredentials.password);
-		} else if (target) {
-			// Bearer-token auth, for remote targets ONLY. A local operation goes over the domain
-			// socket, which the server trusts via `bypassLocalAuth` — but that bypass is an
-			// `else if` on "no Authorization header present" (security/auth.ts), so attaching a
-			// Bearer token to a local request opts out of the trust and gets validated instead,
-			// 401ing on a token minted for some other cluster. Since these env vars are meant to
-			// persist across a whole CI job (or a developer's shell), an ungated read here would
-			// break every local `harper` command run in that environment.
-			//
-			// Env-var tokens (for CI/CD — see `harper login --for-ci`) take precedence over the
-			// stored ~/.harperdb/credentials.json entry: they're an explicit per-invocation override
-			// that needs no prior `harper login` on the runner. A token refreshed from env vars is
-			// used in-memory only (there's no file to write back to); a token refreshed from the
-			// credentials file is persisted as before.
-			//
-			// Whichever namespace supplies a token owns both halves. Resolving them independently
-			// would let `HARPER_CLI_OPERATION_TOKEN` from one user pair with
-			// `CLI_TARGET_REFRESH_TOKEN` from another: commands would run as the first identity
-			// until its operation token expired, then silently continue as the second. `login.ts`
-			// selects its username/password namespace as a unit for exactly this reason.
-			const tokenPrefix = ['HARPER_CLI', 'CLI_TARGET'].find(
-				(prefix) =>
-					process.env[`${prefix}_OPERATION_TOKEN`] !== undefined || process.env[`${prefix}_REFRESH_TOKEN`] !== undefined
+	let options = target ?? {
+		protocol: 'http:',
+		socketPath: getConfigPath(terms.CONFIG_PARAMS.OPERATIONSAPI_NETWORK_DOMAINSOCKET),
+	};
+	options.method = 'POST';
+	options.headers = { 'Content-Type': 'application/json' };
+	options.timeout = SSE_OPERATIONS.has(req.operation) ? SSE_OPERATION_TIMEOUT_MS : CLI_OPERATION_TIMEOUT_MS;
+	// Authentication precedence: explicitly configured credentials (dedicated args, URL
+	// userinfo, env vars) beat everything, then env-var tokens, then the saved `harper login`
+	// token, and only then the legacy `username=`/`password=` payload fallback below. The
+	// tokens must outrank that fallback: for add_user/alter_user those args are the credentials
+	// of the user being created/altered, so treating them as auth would authenticate as a user
+	// who doesn't exist yet (or as the wrong identity) instead of using the admin's session.
+	const transportCredentials = target ? resolveTransportCredentials(req, urlCredentials) : undefined;
+	if (transportCredentials) {
+		options.headers.Authorization = basicAuthHeader(transportCredentials.username, transportCredentials.password);
+	} else if (target) {
+		// Bearer-token auth, for remote targets ONLY. A local operation goes over the domain
+		// socket, which the server trusts via `bypassLocalAuth` — but that bypass is an
+		// `else if` on "no Authorization header present" (security/auth.ts), so attaching a
+		// Bearer token to a local request opts out of the trust and gets validated instead,
+		// 401ing on a token minted for some other cluster. Since these env vars are meant to
+		// persist across a whole CI job (or a developer's shell), an ungated read here would
+		// break every local `harper` command run in that environment.
+		//
+		// Env-var tokens (for CI/CD — see `harper login --for-ci`) take precedence over the
+		// stored ~/.harperdb/credentials.json entry: they're an explicit per-invocation override
+		// that needs no prior `harper login` on the runner. A token refreshed from env vars is
+		// used in-memory only (there's no file to write back to); a token refreshed from the
+		// credentials file is persisted as before.
+		//
+		// Whichever namespace supplies a token owns both halves. Resolving them independently
+		// would let `HARPER_CLI_OPERATION_TOKEN` from one user pair with
+		// `CLI_TARGET_REFRESH_TOKEN` from another: commands would run as the first identity
+		// until its operation token expired, then silently continue as the second. `login.ts`
+		// selects its username/password namespace as a unit for exactly this reason.
+		const tokenPrefix = ['HARPER_CLI', 'CLI_TARGET'].find(
+			(prefix) =>
+				process.env[`${prefix}_OPERATION_TOKEN`] !== undefined || process.env[`${prefix}_REFRESH_TOKEN`] !== undefined
+		);
+		const envOperationToken = tokenPrefix ? process.env[`${tokenPrefix}_OPERATION_TOKEN`]?.trim() : undefined;
+		const envRefreshToken = tokenPrefix ? process.env[`${tokenPrefix}_REFRESH_TOKEN`]?.trim() : undefined;
+		// A namespace that is set but blank is a broken CI secret, not a request to fall back to
+		// whatever the developer last logged in as — say so rather than switching identity silently.
+		if (tokenPrefix && !envOperationToken && !envRefreshToken) {
+			console.error(
+				`Ignoring empty ${tokenPrefix}_OPERATION_TOKEN/${tokenPrefix}_REFRESH_TOKEN; falling back to saved login credentials.`
 			);
-			const envOperationToken = tokenPrefix ? process.env[`${tokenPrefix}_OPERATION_TOKEN`]?.trim() : undefined;
-			const envRefreshToken = tokenPrefix ? process.env[`${tokenPrefix}_REFRESH_TOKEN`]?.trim() : undefined;
-			// A namespace that is set but blank is a broken CI secret, not a request to fall back to
-			// whatever the developer last logged in as — say so rather than switching identity silently.
-			if (tokenPrefix && !envOperationToken && !envRefreshToken) {
-				console.error(
-					`Ignoring empty ${tokenPrefix}_OPERATION_TOKEN/${tokenPrefix}_REFRESH_TOKEN; falling back to saved login credentials.`
-				);
-			}
+		}
 
-			let tokens: { operation_token?: string; refresh_token?: string } | null = null;
-			let persistKey: string | null = null; // non-null => persist a refreshed operation token back to the file
-			if (envOperationToken || envRefreshToken) {
-				tokens = { operation_token: envOperationToken, refresh_token: envRefreshToken };
-			} else if (allCredentials?.targets) {
-				persistKey = target.resolvedTarget;
-				tokens = allCredentials.targets[persistKey] ?? null;
-			}
+		let tokens: { operation_token?: string; refresh_token?: string } | null = null;
+		let persistKey: string | null = null; // non-null => persist a refreshed operation token back to the file
+		if (envOperationToken || envRefreshToken) {
+			tokens = { operation_token: envOperationToken, refresh_token: envRefreshToken };
+		} else if (allCredentials?.targets) {
+			persistKey = target.resolvedTarget;
+			tokens = allCredentials.targets[persistKey] ?? null;
+		}
 
-			if (tokens?.operation_token || tokens?.refresh_token) {
-				await refreshExpiredOperationToken(options, tokens, persistKey);
-				if (tokens.operation_token) {
-					options.headers.Authorization = `Bearer ${tokens.operation_token}`;
-				}
+		if (tokens?.operation_token || tokens?.refresh_token) {
+			await refreshExpiredOperationToken(options, tokens, persistKey);
+			if (tokens.operation_token) {
+				options.headers.Authorization = `Bearer ${tokens.operation_token}`;
 			}
 		}
-		// Legacy fallback for operations where `username=`/`password=` genuinely ARE the caller's
-		// credentials (e.g. `create_table username= password=`) and nothing else is configured.
-		// Both are required — a lone `username=` (as in `drop_user username=bob`) is payload, not
-		// a credential.
-		if (target && !options.headers.Authorization && req.username && req.password) {
-			options.headers.Authorization = basicAuthHeader(req.username, req.password);
-		}
+	}
+	// Legacy fallback for operations where `username=`/`password=` genuinely ARE the caller's
+	// credentials (e.g. `create_table username= password=`) and nothing else is configured.
+	// Both are required — a lone `username=` (as in `drop_user username=bob`) is payload, not
+	// a credential.
+	if (target && !options.headers.Authorization && req.username && req.password) {
+		options.headers.Authorization = basicAuthHeader(req.username, req.password);
+	}
+	return { options, target };
+}
+
+async function cliOperations(req: any, skipResponseLog = false) {
+	require('dotenv').config();
+
+	// Resolve target/auth inside the try so a credential or connection error (e.g. an incomplete
+	// `auth_username=`/`auth_password=` pair, which resolveRequestOptions throws on) is mapped to the
+	// same console.error + process.exit(1) as every other failure below, rather than escaping as an
+	// unhandled rejection. `target` is declared out here so the catch can still reference it.
+	let options: any, target: any;
+	try {
+		({ options, target } = await resolveRequestOptions(req));
+		await PREPARE_OPERATION[req.operation]?.(req);
 		// Streaming deploy (multipart upload + SSE progress) only works against >= 5.1 servers.
 		// When deploying to a remote target, probe its version first and downgrade to the
 		// legacy JSON deploy if it predates 5.1. Local (domain-socket) deploys always

package/bin/copyDb.ts

@@ -1,4 +1,10 @@
-import { getDatabases, getDefaultCompression, resetDatabases } from '../resources/databases.ts';
+import {
+	getDatabases,
+	getDefaultCompression,
+	resetDatabases,
+	getRocksCompression,
+	toRocksCompression,
+} from '../resources/databases.ts';
 import { open, asBinary } from 'lmdb';
 import { join } from 'path';
 import { move, remove } from 'fs-extra';
@@ -329,6 +335,10 @@ export function shapeForStructure(value: any): any {
 
 function openRocksDb(path: string, options: RocksDatabaseOptions & { dupSort?: boolean } = {}) {
 	options.disableWAL ??= false;
+	// Migration creates a complete replacement database, so use the deployment codec for the files
+	// it writes; runtime opens additionally reconcile pre-existing sibling column families.
+	const legacyOptions = options as { compression?: unknown };
+	legacyOptions.compression = getRocksCompression() ?? toRocksCompression(legacyOptions.compression);
 	if (!existsSync(path)) {
 		mkdirSync(path, { recursive: true });
 	}
@@ -510,7 +520,14 @@ export async function migrateDatabaseToRocks(sourceRootStore, databaseName: stri
 export async function copyDbToRocks(sourceRootStore, sourceDatabase: string, targetPath: string) {
 	console.log(`Migrating database ${sourceDatabase} to RocksDB at ${targetPath}`);
 	const sourceDbisDb = sourceRootStore.dbisDb;
-
+	// Runtime Harper stores disable RocksDB's native WAL for data/index column families and recover
+	// them from rocksdb-js transaction logs. This copier does not write those transaction logs, so
+	// only use the same fast write path for migrateOnStart's disposable staging directory: after an
+	// interruption it is deleted and recopied from LMDB. Direct copyDbToRocks callers retain WAL.
+	const disableDataWAL = targetPath.endsWith(MIGRATING_DIR_SUFFIX);
+
+	// Keep native WAL for the root/log-owner and __dbis__ handles, matching Harper's runtime policy.
+	// Their migration writes are metadata-sized; the 600 GB bulk is in the data/index handles below.
 	const targetRootStore = openRocksDb(targetPath, { disableWAL: false });
 	// Every handle opened on targetPath. All must be closed before returning so the caller can
 	// atomically rename a staging directory into place — rocksdb-js registers descriptors by
@@ -587,10 +604,10 @@ export async function copyDbToRocks(sourceRootStore, sourceDatabase: string, tar
 			let observerEncoder: any;
 			let canonicalStructures: any;
 			if (!isPrimary) {
-				targetDbi = openRocksDb(targetPath, { dupSort: true, name: key });
+				targetDbi = openRocksDb(targetPath, { disableWAL: disableDataWAL, dupSort: true, name: key });
 				targetHandles.push(targetDbi);
 			} else {
-				targetDbi = openRocksDb(targetPath, { name: key });
+				targetDbi = openRocksDb(targetPath, { disableWAL: disableDataWAL, name: key });
 				targetHandles.push(targetDbi);
 				// Patch the existing encoder (encoder is a getter-only property on RocksDatabase, cannot be replaced)
 				// to install RecordEncoder's encode method so metadata headers (timestamps, HAS_BLOBS flag) are written

package/bin/harper.ts

@@ -5,62 +5,39 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import logger from '../utility/logging/harper_logger.ts';
 import * as cliOperations from './cliOperations.ts';
+import { help } from './help.ts';
 import { packageJson } from '../utility/packageUtils.js';
 import checkNode from '../launchServiceScripts/utility/checkNodeVersion.js';
 import * as hdbTerms from '../utility/hdbTerms.ts';
-const { SERVICE_ACTIONS_ENUM } = hdbTerms as any;
+const { SERVICE_ACTIONS_ENUM, OPERATIONS_ENUM } = hdbTerms as any;
 if (typeof process.setSourceMapsEnabled === 'function') {
 	process.setSourceMapsEnabled(true); // this is necessary for source maps to work, at least on the main thread.
 }
 
-const HELP = `
-Usage: harperdb [command]
-
-With no command, harper will simply run Harper (in the foreground)
-
-Documentation: https://docs.harperdb.io/
-
-By default, the CLI also supports certain Operation APIs. Specify the operation name and any required parameters, and omit the 'operation' command.
+/**
+ * Format a CLI error for the terminal. Expected, user-facing errors (a `ClientError` from an
+ * operation — bad args, not found, a locked backup repo — which carry a numeric `statusCode`) get
+ * just their message, not a Node stack trace. A genuinely unexpected error keeps its stack so a bug
+ * is still debuggable. Mirrors the clean `error: <message>` output of a forwarded operation.
+ */
+export function formatCliError(error: any): string {
+	const message = `error: ${error?.message ?? error}`;
+	if (error?.stack && typeof error?.statusCode !== 'number') return `${message}\n${error.stack}`;
+	return message;
+}
 
-Commands:
-agent [message]                 - Chat with the built-in agent (interactive, or one-shot with a message; alias: chat)
-copy-db <source> <target>       - Copies a database from source path to target path
-dev <path>                      - Run the application in dev mode with debugging, foreground logging, no auth
-install                         - Install harperdb
-<api-operation> <param>=<value> - Run an API operation and return result to the CLI, not all operations are supported
-                                   To authenticate as a different user than the one being operated on
-                                   (e.g. add_user/alter_user), set HARPER_CLI_USERNAME/HARPER_CLI_PASSWORD
-                                   or run 'harper login'. The equivalent auth_username=<value>
-                                   auth_password=<value> args also work, but a password passed as an
-                                   argument is exposed in shell history, process listings and CI logs.
-                                   A saved login token always outranks username=/password=, so a
-                                   stale token that fails to refresh will 401 rather than falling
-                                   back to them — run 'harper logout' or pass auth_username=/
-                                   auth_password= to override it.
-login [target] [username]       - Login to a remote or local Harper instance
-                                   --for-ci prints the CI/CD credentials (target + long-lived
-                                   refresh token) to stdout in dotenv format, and everything else
-                                   to stderr, so it pipes without the token hitting your screen:
-                                     harper login --for-ci | gh secret set --env-file -
-                                   Log in as a user dedicated to that one CI consumer: Harper
-                                   stores a single refresh token per user, so this revokes any
-                                   refresh token that user already holds — another runner, another
-                                   machine, or an earlier 'harper login' will 401 on its next
-                                   refresh. Two consumers cannot share a user.
-logout [target]                 - Logout from Harper and clear saved JWT
-mcp [subcommand]                - MCP stdio bridge / print-config / doctor (see 'harper mcp help')
-register                        - Register harperdb
-renew-certs                     - Generate a new set of self-signed certificates
-restart                         - Restart the harperdb background process
-run <path>                      - Run the application in the specified path
-start                           - Starts a separate background process for harperdb and CLI will exit
-status                          - Print the status of Harper
-stop                            - Stop the harperdb background process
-help                            - Display this output
-upgrade                         - Upgrade harperdb
-version                         - Print the version
-deploy                          - Deploy the application locally or remotely with target=<remote url>
-`;
+/**
+ * Whether a `-h`/`--help` anywhere in `argv` should print the top-level help. Returns false for the
+ * subcommands that own their own `--help` — mcp and agent/chat parse `process.argv.slice(3)`
+ * themselves downstream — so `harper mcp --help` reaches the mcp handler instead of this help.
+ */
+export function wantsTopLevelHelp(argv: readonly string[], service: string | undefined): boolean {
+	const delegatesHelp =
+		service === SERVICE_ACTIONS_ENUM.MCP ||
+		service === SERVICE_ACTIONS_ENUM.AGENT ||
+		service === SERVICE_ACTIONS_ENUM.CHAT;
+	return !delegatesHelp && (argv.includes('-h') || argv.includes('--help'));
+}
 
 async function harper() {
 	let nodeResults = checkNode();
@@ -78,13 +55,17 @@ async function harper() {
 
 	let service;
 
-	if (process.argv && process.argv[2] && !process.argv[2].startsWith('-')) {
+	if (process.argv?.[2] && !process.argv[2].startsWith('-')) {
 		service = process.argv[2].toLowerCase();
 	}
 
+	if (wantsTopLevelHelp(process.argv, service)) {
+		return help();
+	}
+
 	switch (service) {
 		case SERVICE_ACTIONS_ENUM.HELP:
-			return HELP;
+			return help();
 		case SERVICE_ACTIONS_ENUM.START:
 			return require('./run').launch();
 		case SERVICE_ACTIONS_ENUM.INSTALL:
@@ -140,6 +121,14 @@ async function harper() {
 			let targetDbPath = process.argv[4];
 			return require('./copyDb').copyDb(sourceDb, targetDbPath);
 		}
+		case OPERATIONS_ENUM.CREATE_BACKUP:
+		case OPERATIONS_ENUM.LIST_BACKUPS:
+		case OPERATIONS_ENUM.VERIFY_BACKUP:
+		case OPERATIONS_ENUM.DELETE_BACKUP:
+		case OPERATIONS_ENUM.PURGE_BACKUPS:
+		case OPERATIONS_ENUM.GET_BACKUP:
+		case OPERATIONS_ENUM.RESTORE_BACKUP:
+			return require('./backup').runBackupCommand(service);
 		case SERVICE_ACTIONS_ENUM.DEV:
 			process.env.DEV_MODE = 'true';
 		// fall through
@@ -191,18 +180,17 @@ if (require.main === module) {
 	harper()
 		.then((message) => {
 			if (message) {
+				// console.log is the canonical terminal output for CLI results; logger.notify would
+				// print the same message a second time (its Console transport is stdout in CLI mode),
+				// so `harper help` and friends were emitted twice.
 				console.log(message);
-				logger.notify(message);
 			}
 			// Intentionally not calling `process.exit(0);` so if a CLI
 			// command resulted in a long running process (aka `run`),
 			// it continues to run.
 		})
 		.catch((error) => {
-			if (error) {
-				console.error(error);
-				logger.error(error);
-			}
+			if (error) console.error(formatCliError(error));
 			process.exit(1);
 		});
 }