@envsync-cloud/deploy-cli 0.6.3 → 0.6.4

package/README.md

@@ -40,13 +40,13 @@ bunx @envsync-cloud/deploy-cli <command>
 ```text
 envsync-deploy preinstall
 envsync-deploy setup
-envsync-deploy bootstrap
-envsync-deploy deploy
+envsync-deploy bootstrap [--dry-run]
+envsync-deploy deploy [--dry-run]
 envsync-deploy health [--json]
-envsync-deploy upgrade
-envsync-deploy upgrade-deps
-envsync-deploy backup
-envsync-deploy restore <archive>
+envsync-deploy upgrade [--dry-run]
+envsync-deploy upgrade-deps [--dry-run]
+envsync-deploy backup [--dry-run]
+envsync-deploy restore <archive> [--dry-run]
 ```
 
 ## Quick Start
@@ -100,6 +100,13 @@ Restore from an existing backup archive:
 npx @envsync-cloud/deploy-cli restore /path/to/envsync-backup.tar.gz
 ```
 
+Preview mutating commands without changing the host:
+
+```bash
+npx @envsync-cloud/deploy-cli bootstrap --dry-run
+npx @envsync-cloud/deploy-cli deploy --dry-run
+```
+
 ## Links
 
 - Repository: https://github.com/EnvSync-Cloud/envsync

package/dist/index.js

@@ -6,6 +6,7 @@ import { spawnSync } from "child_process";
 import fs from "fs";
 import path from "path";
 import readline from "readline";
+import chalk from "chalk";
 var HOST_ROOT = "/opt/envsync";
 var DEPLOY_ROOT = "/opt/envsync/deploy";
 var RELEASES_ROOT = "/opt/envsync/releases";
@@ -47,6 +48,33 @@ var REQUIRED_BOOTSTRAP_ENV_KEYS = [
   "OPENFGA_MODEL_ID"
 ];
 var SEMVER_VERSION_RE = /^\d+\.\d+\.\d+$/;
+var currentOptions = { dryRun: false };
+function formatShellArg(arg) {
+  if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(arg)) return arg;
+  return JSON.stringify(arg);
+}
+function formatCommand(cmd, args) {
+  return [cmd, ...args].map(formatShellArg).join(" ");
+}
+function logSection(title) {
+  console.log(`
+${chalk.bold.blue(title)}`);
+}
+function logStep(message) {
+  console.log(`${chalk.cyan("[step]")} ${message}`);
+}
+function logInfo(message) {
+  console.log(`${chalk.blue("[info]")} ${message}`);
+}
+function logSuccess(message) {
+  console.log(`${chalk.green("[ok]")} ${message}`);
+}
+function logDryRun(message) {
+  console.log(`${chalk.magenta("[dry-run]")} ${message}`);
+}
+function logCommand(cmd, args) {
+  console.log(chalk.dim(`$ ${formatCommand(cmd, args)}`));
+}
 function run(cmd, args, opts = {}) {
   const result = spawnSync(cmd, args, {
     cwd: opts.cwd,
@@ -85,6 +113,13 @@ function writeFile(target, content, mode) {
   fs.writeFileSync(target, content, "utf8");
   if (mode != null) fs.chmodSync(target, mode);
 }
+function writeFileMaybe(target, content, mode) {
+  if (currentOptions.dryRun) {
+    logDryRun(`Would write ${target}`);
+    return;
+  }
+  writeFile(target, content, mode);
+}
 function exists(target) {
   return fs.existsSync(target);
 }
@@ -767,8 +802,9 @@ ${renderEnvList({
     KC_BOOTSTRAP_ADMIN_USERNAME: config.auth.admin_user,
     KC_BOOTSTRAP_ADMIN_PASSWORD: config.auth.admin_password,
     KC_HTTP_ENABLED: "true",
+    KC_HEALTH_ENABLED: "true",
     KC_PROXY_HEADERS: "xforwarded",
-    KC_HOSTNAME: hosts.auth
+    KC_HOSTNAME_STRICT: "false"
   })}
     volumes:
       - ${KEYCLOAK_REALM_FILE}:/opt/keycloak/data/import/realm.json:ro
@@ -897,40 +933,59 @@ volumes:
 }
 function writeDeployArtifacts(config, generated) {
   const runtimeEnv = buildRuntimeEnv(config, generated);
-  writeFile(DEPLOY_ENV, renderEnvFile(runtimeEnv), 384);
-  writeFile(
+  logStep("Rendering deploy artifacts");
+  writeFileMaybe(DEPLOY_ENV, renderEnvFile(runtimeEnv), 384);
+  writeFileMaybe(
     INTERNAL_CONFIG_JSON,
     JSON.stringify({ config, generated: mergeGeneratedState(runtimeEnv, generated) }, null, 2) + "\n"
   );
-  writeFile(VERSIONS_LOCK, JSON.stringify(config.images, null, 2) + "\n");
-  writeFile(KEYCLOAK_REALM_FILE, renderKeycloakRealm(config, runtimeEnv));
-  writeFile(TRAEFIK_DYNAMIC_FILE, renderTraefikDynamicConfig(config));
-  writeFile(BOOTSTRAP_BASE_STACK_FILE, renderStack(config, runtimeEnv, "base"));
-  writeFile(BOOTSTRAP_STACK_FILE, renderStack(config, runtimeEnv, "bootstrap"));
-  writeFile(STACK_FILE, renderStack(config, runtimeEnv, "full"));
-  writeFile(NGINX_WEB_CONF, renderNginxConf("web"));
-  writeFile(NGINX_LANDING_CONF, renderNginxConf("landing"));
-  writeFile(OTEL_AGENT_CONF, renderOtelAgentConfig(config));
+  writeFileMaybe(VERSIONS_LOCK, JSON.stringify(config.images, null, 2) + "\n");
+  writeFileMaybe(KEYCLOAK_REALM_FILE, renderKeycloakRealm(config, runtimeEnv));
+  writeFileMaybe(TRAEFIK_DYNAMIC_FILE, renderTraefikDynamicConfig(config));
+  writeFileMaybe(BOOTSTRAP_BASE_STACK_FILE, renderStack(config, runtimeEnv, "base"));
+  writeFileMaybe(BOOTSTRAP_STACK_FILE, renderStack(config, runtimeEnv, "bootstrap"));
+  writeFileMaybe(STACK_FILE, renderStack(config, runtimeEnv, "full"));
+  writeFileMaybe(NGINX_WEB_CONF, renderNginxConf("web"));
+  writeFileMaybe(NGINX_LANDING_CONF, renderNginxConf("landing"));
+  writeFileMaybe(OTEL_AGENT_CONF, renderOtelAgentConfig(config));
+  logSuccess(currentOptions.dryRun ? "Deploy artifacts previewed" : "Deploy artifacts written");
 }
 function saveDesiredConfig(config) {
   const internal = readInternalState();
   const generated = mergeGeneratedState(loadGeneratedEnv(), internal?.generated);
-  writeFile(DEPLOY_YAML, toYaml(config) + "\n");
-  writeFile(
+  logStep(`Saving desired config to ${DEPLOY_YAML}`);
+  writeFileMaybe(DEPLOY_YAML, toYaml(config) + "\n");
+  writeFileMaybe(
     INTERNAL_CONFIG_JSON,
     JSON.stringify({ config, generated }, null, 2) + "\n"
   );
+  logSuccess(currentOptions.dryRun ? "Desired config previewed" : "Desired config saved");
 }
 function ensureRepoCheckout(config) {
+  logStep(`Ensuring pinned repo checkout at ${config.source.ref}`);
+  if (currentOptions.dryRun) {
+    logDryRun(`Would ensure repo checkout at ${REPO_ROOT}`);
+    return;
+  }
   ensureDir(REPO_ROOT);
   if (!exists(path.join(REPO_ROOT, ".git"))) {
+    logCommand("git", ["clone", config.source.repo_url, REPO_ROOT]);
     run("git", ["clone", config.source.repo_url, REPO_ROOT]);
   }
+  logCommand("git", ["remote", "set-url", "origin", config.source.repo_url]);
   run("git", ["remote", "set-url", "origin", config.source.repo_url], { cwd: REPO_ROOT });
+  logCommand("git", ["fetch", "--tags", "--force", "origin"]);
   run("git", ["fetch", "--tags", "--force", "origin"], { cwd: REPO_ROOT });
+  logCommand("git", ["checkout", "--force", config.source.ref]);
   run("git", ["checkout", "--force", config.source.ref], { cwd: REPO_ROOT });
+  logSuccess(`Pinned repo checkout ready at ${config.source.ref}`);
 }
 function extractStaticBundle(image, targetDir) {
+  logStep(`Extracting static bundle from ${image}`);
+  if (currentOptions.dryRun) {
+    logDryRun(`Would extract ${image} into ${targetDir}`);
+    return;
+  }
   ensureDir(targetDir);
   const containerId = run("docker", ["create", image], { quiet: true }).trim();
   try {
@@ -938,24 +993,43 @@ function extractStaticBundle(image, targetDir) {
   } finally {
     run("docker", ["rm", "-f", containerId], { quiet: true });
   }
+  logSuccess(`Static bundle extracted to ${targetDir}`);
 }
 function buildKeycloakImage(imageTag, repoRoot = REPO_ROOT) {
   const buildContext = path.join(repoRoot, "packages/envsync-keycloak-theme");
   if (!exists(path.join(buildContext, "Dockerfile"))) {
     throw new Error(`Missing Keycloak Docker build context at ${buildContext}`);
   }
+  logStep(`Building Keycloak image ${imageTag}`);
+  if (currentOptions.dryRun) {
+    logDryRun(`Would build ${imageTag} from ${buildContext}`);
+    return;
+  }
+  logCommand("docker", ["build", "-t", imageTag, buildContext]);
   run("docker", ["build", "-t", imageTag, buildContext]);
+  logSuccess(`Built Keycloak image ${imageTag}`);
 }
 function stackNetworkName(config) {
   return `${config.services.stack_name}_envsync`;
 }
 function assertSwarmManager() {
+  if (currentOptions.dryRun) {
+    logDryRun("Skipping Docker Swarm manager validation");
+    return;
+  }
+  logStep("Validating Docker Swarm manager state");
   const state = tryRun("docker", ["info", "--format", "{{.Swarm.LocalNodeState}}|{{.Swarm.ControlAvailable}}"], { quiet: true }).trim();
   if (state !== "active|true") {
     throw new Error("Docker Swarm is not initialized on this node. Run 'docker swarm init' or 'envsync-deploy preinstall' first.");
   }
+  logSuccess("Docker Swarm manager is ready");
 }
 function waitForCommand(config, label, image, command, timeoutSeconds = 120, env = {}, volumes = []) {
+  if (currentOptions.dryRun) {
+    logDryRun(`Would wait for ${label}`);
+    return;
+  }
+  logStep(`Waiting for ${label}`);
   const deadline = Date.now() + timeoutSeconds * 1e3;
   while (Date.now() < deadline) {
     const args = ["run", "--rm", "--network", stackNetworkName(config)];
@@ -967,6 +1041,7 @@ function waitForCommand(config, label, image, command, timeoutSeconds = 120, env
     }
     args.push(image, "sh", "-lc", command);
     if (commandSucceeds("docker", args)) {
+      logSuccess(`${label} is ready`);
       return;
     }
     sleepSeconds(2);
@@ -998,6 +1073,23 @@ function waitForHttpService(config, label, url, timeoutSeconds = 120) {
   waitForCommand(config, `${label} HTTP readiness`, "alpine:3.20", `wget -q -O /dev/null ${JSON.stringify(url)}`, timeoutSeconds);
 }
 function runOpenFgaMigrate(config, runtimeEnv) {
+  logStep("Running OpenFGA datastore migrations");
+  if (currentOptions.dryRun) {
+    logDryRun("Would run OpenFGA datastore migrations");
+    logCommand("docker", [
+      "run",
+      "--rm",
+      "--network",
+      stackNetworkName(config),
+      "-e",
+      "OPENFGA_DATASTORE_ENGINE=postgres",
+      "-e",
+      `OPENFGA_DATASTORE_URI=postgres://openfga:${runtimeEnv.OPENFGA_DB_PASSWORD}@openfga_db:5432/openfga?sslmode=disable`,
+      "openfga/openfga:v1.12.0",
+      "migrate"
+    ]);
+    return;
+  }
   run("docker", [
     "run",
     "--rm",
@@ -1010,8 +1102,28 @@ function runOpenFgaMigrate(config, runtimeEnv) {
     "openfga/openfga:v1.12.0",
     "migrate"
   ]);
+  logSuccess("OpenFGA datastore migrations completed");
 }
 function runMiniKmsMigrate(config, runtimeEnv) {
+  logStep("Running miniKMS datastore migrations");
+  if (currentOptions.dryRun) {
+    logDryRun("Would run miniKMS datastore migrations");
+    logCommand("docker", [
+      "run",
+      "--rm",
+      "--network",
+      stackNetworkName(config),
+      "-e",
+      `PGPASSWORD=${runtimeEnv.MINIKMS_DB_PASSWORD}`,
+      "-v",
+      `${path.join(REPO_ROOT, "docker/minikms/migrations")}:/migrations:ro`,
+      "postgres:17",
+      "sh",
+      "-lc",
+      "psql -h minikms_db -U postgres -d minikms -f /migrations/001_initial_schema.sql && psql -h minikms_db -U postgres -d minikms -f /migrations/002_vault_storage.sql"
+    ]);
+    return;
+  }
   run("docker", [
     "run",
     "--rm",
@@ -1026,8 +1138,35 @@ function runMiniKmsMigrate(config, runtimeEnv) {
     "-lc",
     "psql -h minikms_db -U postgres -d minikms -f /migrations/001_initial_schema.sql && psql -h minikms_db -U postgres -d minikms -f /migrations/002_vault_storage.sql"
   ]);
+  logSuccess("miniKMS datastore migrations completed");
 }
 function runBootstrapInit(config) {
+  logStep("Running API bootstrap init");
+  if (currentOptions.dryRun) {
+    logDryRun("Would run API bootstrap init and persist generated OpenFGA IDs");
+    logCommand("docker", [
+      "run",
+      "--rm",
+      "--network",
+      stackNetworkName(config),
+      "--env-file",
+      DEPLOY_ENV,
+      "-e",
+      "SKIP_ROOT_ENV=1",
+      "-e",
+      "SKIP_ROOT_ENV_WRITE=1",
+      config.images.api,
+      "bun",
+      "run",
+      "scripts/prod-init.ts",
+      "--json",
+      "--no-write-root-env"
+    ]);
+    return {
+      openfgaStoreId: "",
+      openfgaModelId: ""
+    };
+  }
   const output = run(
     "docker",
     [
@@ -1054,6 +1193,7 @@ function runBootstrapInit(config) {
   if (!result.openfgaStoreId || !result.openfgaModelId) {
     throw new Error("Bootstrap init did not return OpenFGA IDs");
   }
+  logSuccess("API bootstrap init completed");
   return {
     openfgaStoreId: result.openfgaStoreId,
     openfgaModelId: result.openfgaModelId
@@ -1141,6 +1281,7 @@ async function cmdPreinstall() {
   run("bash", ["-lc", "curl -fsSL https://acme-v02.api.letsencrypt.org/directory >/dev/null"]);
 }
 async function cmdSetup() {
+  logSection("Setup");
   const rootDomain = await ask("Root domain", "example.com");
   const acmeEmail = await ask("ACME email", `admin@${rootDomain}`);
   const releaseVersion = await ask("Release version", getDeployCliVersion());
@@ -1216,20 +1357,30 @@ async function cmdSetup() {
     }
   };
   saveDesiredConfig(config);
-  console.log(`Config written to ${DEPLOY_YAML}`);
-  console.log(`Pinned source checkout: ${config.source.repo_url} @ ${config.source.ref}`);
-  console.log("Create these DNS records:");
+  logSuccess(`Config written to ${DEPLOY_YAML}`);
+  logInfo(`Pinned source checkout: ${config.source.repo_url} @ ${config.source.ref}`);
+  logInfo("Create these DNS records:");
   console.log(JSON.stringify(domainMap(rootDomain), null, 2));
 }
 async function cmdBootstrap() {
+  logSection("Bootstrap");
   const { config, generated } = loadState();
   const nextGenerated = ensureGeneratedRuntimeState(generated);
   const runtimeEnv = buildRuntimeEnv(config, nextGenerated);
+  logInfo(`Release version: ${config.release.version}`);
   assertSwarmManager();
   ensureRepoCheckout(config);
   writeDeployArtifacts(config, nextGenerated);
   buildKeycloakImage(config.images.keycloak);
-  run("docker", ["stack", "deploy", "-c", BOOTSTRAP_BASE_STACK_FILE, config.services.stack_name]);
+  if (currentOptions.dryRun) {
+    logDryRun(`Would deploy base bootstrap stack for ${config.services.stack_name}`);
+    logCommand("docker", ["stack", "deploy", "-c", BOOTSTRAP_BASE_STACK_FILE, config.services.stack_name]);
+  } else {
+    logStep("Deploying base bootstrap stack");
+    logCommand("docker", ["stack", "deploy", "-c", BOOTSTRAP_BASE_STACK_FILE, config.services.stack_name]);
+    run("docker", ["stack", "deploy", "-c", BOOTSTRAP_BASE_STACK_FILE, config.services.stack_name]);
+    logSuccess("Base bootstrap stack deployed");
+  }
   waitForPostgresService(config, "postgres", "postgres", "postgres", "envsync-postgres");
   waitForRedisService(config);
   waitForTcpService(config, "rustfs", "rustfs", 9e3);
@@ -1238,11 +1389,24 @@ async function cmdBootstrap() {
   waitForPostgresService(config, "minikms", "minikms_db", "postgres", runtimeEnv.MINIKMS_DB_PASSWORD);
   runOpenFgaMigrate(config, runtimeEnv);
   runMiniKmsMigrate(config, runtimeEnv);
-  run("docker", ["stack", "deploy", "-c", BOOTSTRAP_STACK_FILE, config.services.stack_name]);
-  waitForHttpService(config, "keycloak", "http://keycloak:8080/realms/master");
+  if (currentOptions.dryRun) {
+    logDryRun(`Would deploy runtime bootstrap stack for ${config.services.stack_name}`);
+    logCommand("docker", ["stack", "deploy", "-c", BOOTSTRAP_STACK_FILE, config.services.stack_name]);
+  } else {
+    logStep("Deploying runtime bootstrap stack");
+    logCommand("docker", ["stack", "deploy", "-c", BOOTSTRAP_STACK_FILE, config.services.stack_name]);
+    run("docker", ["stack", "deploy", "-c", BOOTSTRAP_STACK_FILE, config.services.stack_name]);
+    logSuccess("Runtime bootstrap stack deployed");
+  }
+  waitForHttpService(config, "keycloak", "http://keycloak:8080/health/ready", 180);
   waitForHttpService(config, "openfga", "http://openfga:8090/stores");
   waitForTcpService(config, "minikms", "minikms", 50051);
   const initResult = runBootstrapInit(config);
+  if (currentOptions.dryRun) {
+    logDryRun("Skipping generated OpenFGA ID persistence in preview mode");
+    logSuccess("Bootstrap dry-run completed");
+    return;
+  }
   const bootstrappedGenerated = normalizeGeneratedState({
     openfga: {
       store_id: initResult.openfgaStoreId,
@@ -1254,26 +1418,46 @@ async function cmdBootstrap() {
     }
   });
   writeDeployArtifacts(config, bootstrappedGenerated);
-  console.log("Bootstrap completed.");
+  logSuccess("Bootstrap completed");
 }
 async function cmdDeploy() {
+  logSection("Deploy");
   const { config, generated } = loadState();
+  logInfo(`Release version: ${config.release.version}`);
   assertSwarmManager();
   assertBootstrapState(generated);
-  const services = listStackServices(config);
-  if (serviceHealth(services, `${config.services.stack_name}_keycloak`) === "missing" || serviceHealth(services, `${config.services.stack_name}_openfga`) === "missing" || serviceHealth(services, `${config.services.stack_name}_minikms`) === "missing") {
-    throw new Error("Bootstrap has not completed successfully. Run 'envsync-deploy bootstrap' again.");
+  if (!currentOptions.dryRun) {
+    const services = listStackServices(config);
+    if (serviceHealth(services, `${config.services.stack_name}_keycloak`) === "missing" || serviceHealth(services, `${config.services.stack_name}_openfga`) === "missing" || serviceHealth(services, `${config.services.stack_name}_minikms`) === "missing") {
+      throw new Error("Bootstrap has not completed successfully. Run 'envsync-deploy bootstrap' again.");
+    }
+  } else {
+    logDryRun("Skipping runtime bootstrap service validation");
   }
   ensureRepoCheckout(config);
   writeDeployArtifacts(config, generated);
   buildKeycloakImage(config.images.keycloak);
-  ensureDir(`${RELEASES_ROOT}/web/current`);
-  ensureDir(`${RELEASES_ROOT}/landing/current`);
+  if (currentOptions.dryRun) {
+    logDryRun(`Would ensure ${RELEASES_ROOT}/web/current exists`);
+    logDryRun(`Would ensure ${RELEASES_ROOT}/landing/current exists`);
+  } else {
+    ensureDir(`${RELEASES_ROOT}/web/current`);
+    ensureDir(`${RELEASES_ROOT}/landing/current`);
+  }
   extractStaticBundle(config.images.web, `${RELEASES_ROOT}/web/current`);
   extractStaticBundle(config.images.landing, `${RELEASES_ROOT}/landing/current`);
-  writeFile(`${RELEASES_ROOT}/web/current/runtime-config.js`, renderFrontendRuntimeConfig(config));
-  writeFile(`${RELEASES_ROOT}/landing/current/runtime-config.js`, renderFrontendRuntimeConfig(config));
+  writeFileMaybe(`${RELEASES_ROOT}/web/current/runtime-config.js`, renderFrontendRuntimeConfig(config));
+  writeFileMaybe(`${RELEASES_ROOT}/landing/current/runtime-config.js`, renderFrontendRuntimeConfig(config));
+  if (currentOptions.dryRun) {
+    logDryRun(`Would deploy full stack for ${config.services.stack_name}`);
+    logCommand("docker", ["stack", "deploy", "-c", STACK_FILE, config.services.stack_name]);
+    logSuccess("Deploy dry-run completed");
+    return;
+  }
+  logStep("Deploying full stack");
+  logCommand("docker", ["stack", "deploy", "-c", STACK_FILE, config.services.stack_name]);
   run("docker", ["stack", "deploy", "-c", STACK_FILE, config.services.stack_name]);
+  logSuccess("Deploy completed");
 }
 async function cmdHealth(asJson) {
   const { config, generated } = loadState();
@@ -1314,20 +1498,28 @@ async function cmdHealth(asJson) {
   console.log(JSON.stringify(checks, null, 2));
 }
 async function cmdUpgrade() {
+  logSection("Upgrade");
   const { config } = loadState();
   config.images = {
     ...config.images,
     ...versionedImages(config.release.version)
   };
   saveDesiredConfig(config);
+  if (currentOptions.dryRun) {
+    logDryRun(`Would upgrade stack to release ${config.release.version}`);
+  }
   await cmdDeploy();
 }
 async function cmdUpgradeDeps() {
+  logSection("Upgrade Dependencies");
   const { config } = loadState();
   config.images.traefik = "traefik:v3.1";
   config.images.clickstack = "clickhouse/clickstack-all-in-one:latest";
   config.images.otel_agent = "otel/opentelemetry-collector-contrib:0.111.0";
   saveDesiredConfig(config);
+  if (currentOptions.dryRun) {
+    logDryRun("Would refresh dependency image tags and redeploy");
+  }
   await cmdDeploy();
 }
 function sha256File(filePath) {
@@ -1339,6 +1531,11 @@ function stackVolumeName(config, name) {
   return `${config.services.stack_name}_${name}`;
 }
 function backupDockerVolume(volumeName, targetDir) {
+  logStep(`Backing up Docker volume ${volumeName}`);
+  if (currentOptions.dryRun) {
+    logDryRun(`Would back up ${volumeName} into ${targetDir}`);
+    return;
+  }
   ensureDir(targetDir);
   run("docker", [
     "run",
@@ -1352,8 +1549,14 @@ function backupDockerVolume(volumeName, targetDir) {
     "-lc",
     "cd /from && tar -czf /to/volume.tar.gz ."
   ]);
+  logSuccess(`Backed up Docker volume ${volumeName}`);
 }
 function restoreDockerVolume(volumeName, sourceDir) {
+  logStep(`Restoring Docker volume ${volumeName}`);
+  if (currentOptions.dryRun) {
+    logDryRun(`Would restore ${volumeName} from ${sourceDir}`);
+    return;
+  }
   run("docker", ["volume", "create", volumeName], { quiet: true });
   run("docker", [
     "run",
@@ -1367,15 +1570,29 @@ function restoreDockerVolume(volumeName, sourceDir) {
     "-lc",
     "cd /to && tar -xzf /from/volume.tar.gz"
   ]);
+  logSuccess(`Restored Docker volume ${volumeName}`);
 }
 async function cmdBackup() {
+  logSection("Backup");
   const { config } = loadState();
-  ensureDir(config.backup.output_dir);
   const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:]/g, "-");
   const archiveBase = path.join(config.backup.output_dir, `envsync-backup-${timestamp}`);
   const manifestPath = `${archiveBase}.manifest.json`;
   const tarPath = `${archiveBase}.tar.gz`;
   const staged = path.join(BACKUPS_ROOT, `staging-${timestamp}`);
+  logInfo(`Backup archive target: ${tarPath}`);
+  if (currentOptions.dryRun) {
+    logDryRun(`Would stage backup files in ${staged}`);
+    for (const volume of STACK_VOLUMES) {
+      backupDockerVolume(stackVolumeName(config, volume), path.join(staged, "volumes", volume));
+    }
+    logDryRun(`Would write manifest ${manifestPath}`);
+    logDryRun(`Would create archive ${tarPath}`);
+    logSuccess("Backup dry-run completed");
+    console.log(tarPath);
+    return;
+  }
+  ensureDir(config.backup.output_dir);
   ensureDir(staged);
   writeFile(path.join(staged, "deploy.env"), fs.readFileSync(DEPLOY_ENV, "utf8"));
   writeFile(path.join(staged, "deploy.yaml"), fs.readFileSync(DEPLOY_YAML, "utf8"));
@@ -1400,11 +1617,21 @@ async function cmdBackup() {
     volumes: STACK_VOLUMES.map((volume) => stackVolumeName(config, volume))
   };
   writeFile(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+  logSuccess("Backup completed");
   console.log(tarPath);
 }
 async function cmdRestore(archivePath) {
   if (!archivePath) throw new Error("restore requires a .tar.gz path");
+  logSection("Restore");
   const restoreRoot = path.join(BACKUPS_ROOT, `restore-${Date.now()}`);
+  logInfo(`Restore archive: ${archivePath}`);
+  if (currentOptions.dryRun) {
+    logDryRun(`Would extract ${archivePath} into ${restoreRoot}`);
+    logDryRun(`Would restore deploy files into ${DEPLOY_ROOT} and ${ETC_ROOT}`);
+    logDryRun("Would restore all managed Docker volumes from the archive");
+    logSuccess("Restore dry-run completed");
+    return;
+  }
   ensureDir(restoreRoot);
   run("bash", ["-lc", `tar -xzf ${JSON.stringify(archivePath)} -C ${JSON.stringify(restoreRoot)}`]);
   writeFile(DEPLOY_ENV, fs.readFileSync(path.join(restoreRoot, "deploy.env"), "utf8"), 384);
@@ -1421,11 +1648,16 @@ async function cmdRestore(archivePath) {
   for (const volume of STACK_VOLUMES) {
     restoreDockerVolume(stackVolumeName(config, volume), path.join(restoreRoot, "volumes", volume));
   }
-  console.log("Restore completed. Run 'envsync-deploy deploy' to start services.");
+  logSuccess("Restore completed. Run 'envsync-deploy deploy' to start services.");
 }
 async function main() {
-  const command = process.argv[2];
-  const flag = process.argv[3];
+  const argv = process.argv.slice(2);
+  const command = argv[0];
+  const args = argv.slice(1);
+  currentOptions = {
+    dryRun: args.includes("--dry-run")
+  };
+  const positionals = args.filter((arg) => arg !== "--dry-run");
   switch (command) {
     case "preinstall":
       await cmdPreinstall();
@@ -1440,7 +1672,7 @@ async function main() {
       await cmdDeploy();
       break;
     case "health":
-      await cmdHealth(flag === "--json");
+      await cmdHealth(positionals[0] === "--json");
       break;
     case "upgrade":
       await cmdUpgrade();
@@ -1452,10 +1684,12 @@ async function main() {
       await cmdBackup();
       break;
     case "restore":
-      await cmdRestore(flag ?? "");
+      await cmdRestore(positionals[0] ?? "");
       break;
     default:
-      console.log("Usage: envsync-deploy <preinstall|setup|bootstrap|deploy|health|upgrade|upgrade-deps|backup|restore>");
+      console.log(
+        "Usage: envsync-deploy <preinstall|setup|bootstrap|deploy|health|upgrade|upgrade-deps|backup|restore> [--dry-run]"
+      );
       process.exit(command ? 1 : 0);
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@envsync-cloud/deploy-cli",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "CLI for self-hosted EnvSync deployment on Docker Swarm",
   "type": "module",
   "bin": {
@@ -39,6 +39,9 @@
     "cli",
     "secrets"
   ],
+  "dependencies": {
+    "chalk": "^5.6.2"
+  },
   "devDependencies": {
     "tsup": "^8.5.0",
     "typescript": "^5.9.2"