feat(backup): add \backup restore\ command for restic snapshots

Restore a snapshot (or 'latest' by default) to a target directory on
the remote host, with --tag/--host filters. Snapshot files are
extracted but never applied — a bad restore would silently trash
production, so the user runs the actual recovery step (e.g. psql -f
db.sql, rsync -a shared/) manually with the extracted files as input.

Uses the systemd EnvironmentFile at /etc/shipnode/backup.env for
credentials, same as the scheduled backup, so restore works from any
host that can SSH in with sudo — no separate secret plumbing.

Author: devalade

src/cli/commands/backup.ts

@@ -364,6 +364,60 @@ export async function cmdBackupStatus(
   );
 }
 
+/**
+ * Restore a restic snapshot to a target directory on the remote host.
+ *
+ * We intentionally don't apply DB dumps automatically — a bad restore would
+ * silently trash production data. The user gets the files under `--target`
+ * (default: /tmp/shipnode-restore-<ts>) and runs whatever recovery command
+ * fits their situation (e.g. `psql -f db.sql`, `rsync -a shared/ /var/…`).
+ */
+export async function cmdBackupRestore(
+  cwd: string,
+  snapshot: string | undefined,
+  options: { config?: string; target?: string; tag?: string; host?: string },
+): Promise<void> {
+  await runRemoteCommand(
+    cwd,
+    async ({ config, executor }) => {
+      if (!config.backup || (config.backup.strategy ?? 'snapshot') !== 'restic') {
+        ui.error('backup restore only supports the restic strategy today.');
+        process.exit(1);
+      }
+
+      const target = options.target ?? `/tmp/shipnode-restore-${Date.now()}`;
+      const snap = snapshot ?? 'latest';
+      const flags = [
+        options.tag ? `--tag '${options.tag}'` : '',
+        options.host ? `--host '${options.host}'` : '',
+      ].filter(Boolean).join(' ');
+
+      ui.info(`Restoring snapshot ${snap} → ${target}`);
+      const cmd =
+        `SUDO=""; [ "$EUID" -ne 0 ] && SUDO="sudo"; ` +
+        `$SUDO bash -c '. ${BACKUP_ENV_PATH} && ` +
+        `export RESTIC_REPOSITORY RESTIC_PASSWORD AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY HOME && ` +
+        `mkdir -p "${target}" && ` +
+        `restic restore ${snap} --target "${target}" ${flags}'`;
+
+      const result = await executor.exec(cmd, { timeout: 600_000 });
+      console.log(result.stdout);
+      if (result.exitCode !== 0) {
+        ui.error(result.stderr || 'Restore failed');
+        process.exit(1);
+      }
+      ui.success(`Restored to ${target} on ${config.ssh.host}.`);
+      ui.info(
+        'Nothing has been applied — restored files are under the target dir. ' +
+        'Apply manually, e.g.:\n' +
+        '  psql -U <user> -d <db> < db.sql\n' +
+        '  rsync -a shared/ /var/www/<app>/shared/',
+      );
+    },
+    { configPath: options.config },
+  );
+}
+
 export async function cmdBackupList(
   cwd: string,
   options: { config?: string },

src/cli/index.ts

@@ -25,7 +25,7 @@ import { cmdEject } from './commands/eject.js';
 import { cmdHelp } from './commands/help.js';
 import { cmdUserAdd, cmdUserSync, cmdUserList, cmdUserRemove } from './commands/user.js';
 import { cmdUpgrade } from './commands/upgrade.js';
-import { cmdBackupSetup, cmdBackupRun, cmdBackupStatus, cmdBackupList } from './commands/backup.js';
+import { cmdBackupSetup, cmdBackupRun, cmdBackupStatus, cmdBackupList, cmdBackupRestore } from './commands/backup.js';
 import { cmdCloudflareInit, cmdCloudflareAudit, cmdCloudflareStatus } from './commands/cloudflare.js';
 
 // Read version from package.json so `shipnode --version` stays in sync with the published
@@ -246,6 +246,14 @@ backup.command('list')
   .option('--config <path>', 'Use a specific config file')
   .action((opts) => cmdBackupList(process.cwd(), opts));
 
+backup.command('restore [snapshot]')
+  .description('Restore a restic snapshot to a target directory (default: latest)')
+  .option('--target <path>', 'Where to restore files (default: /tmp/shipnode-restore-<ts>)')
+  .option('--tag <tag>', 'Filter by tag (db | files)')
+  .option('--host <host>', 'Filter by hostname')
+  .option('--config <path>', 'Use a specific config file')
+  .action((snapshot: string | undefined, opts) => cmdBackupRestore(process.cwd(), snapshot, opts));
+
 // ── Cloudflare ────────────────────────────────────────────────────
 
 const cloudflare = program.command('cloudflare').description('Cloudflare Tunnel integration');