@envsync-cloud/deploy-cli 0.6.3 → 0.6.5

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
@@ -71,6 +71,8 @@ Bootstrap infra, migrations, RustFS, and OpenFGA:
 npx @envsync-cloud/deploy-cli bootstrap
 ```
 
+`bootstrap` is destructive. It removes the existing EnvSync stack, matching containers, network, and managed volumes before rebuilding, and requires typing `ARE YOU SURE?` to continue.
+
 Deploy the pending API and frontend services:
 
 ```bash
@@ -79,7 +81,7 @@ npx @envsync-cloud/deploy-cli deploy
 
 The staged flow is:
 - `setup` writes desired config
-- `bootstrap` starts base infra, runs OpenFGA and miniKMS migrations, starts runtime infra, and persists generated runtime env state
+- `bootstrap` resets the existing EnvSync deployment, then starts base infra, runs OpenFGA and miniKMS migrations, starts runtime infra, and persists generated runtime env state
 - `deploy` starts the pending API and frontend services
 
 Check service health:
@@ -100,6 +102,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,36 @@ 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 logWarn(message) {
+  console.log(`${chalk.yellow("[warn]")} ${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 +116,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);
 }
@@ -181,6 +219,18 @@ async function ask(question, fallback = "") {
     });
   });
 }
+async function askRequired(question) {
+  if (!process.stdin.isTTY) {
+    throw new Error(`${question} confirmation requires an interactive terminal.`);
+  }
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return await new Promise((resolve) => {
+    rl.question(`${question} `, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
 function sleepSeconds(seconds) {
   spawnSync("sleep", [`${seconds}`], { stdio: "ignore" });
 }
@@ -329,6 +379,7 @@ function emptyGeneratedState() {
     },
     secrets: {
       s3_secret_key: "",
+      keycloak_db_password: "",
       keycloak_web_client_secret: "",
       keycloak_api_client_secret: "",
       openfga_db_password: "",
@@ -349,6 +400,7 @@ function normalizeGeneratedState(raw) {
     },
     secrets: {
       s3_secret_key: raw?.secrets?.s3_secret_key ?? defaults.secrets.s3_secret_key,
+      keycloak_db_password: raw?.secrets?.keycloak_db_password ?? defaults.secrets.keycloak_db_password,
       keycloak_web_client_secret: raw?.secrets?.keycloak_web_client_secret ?? defaults.secrets.keycloak_web_client_secret,
       keycloak_api_client_secret: raw?.secrets?.keycloak_api_client_secret ?? defaults.secrets.keycloak_api_client_secret,
       openfga_db_password: raw?.secrets?.openfga_db_password ?? defaults.secrets.openfga_db_password,
@@ -391,6 +443,7 @@ function mergeGeneratedState(env, generated) {
     },
     secrets: {
       s3_secret_key: env.S3_SECRET_KEY ?? normalized.secrets.s3_secret_key,
+      keycloak_db_password: env.KEYCLOAK_DB_PASSWORD ?? normalized.secrets.keycloak_db_password,
       keycloak_web_client_secret: env.KEYCLOAK_WEB_CLIENT_SECRET ?? normalized.secrets.keycloak_web_client_secret,
       keycloak_api_client_secret: env.KEYCLOAK_API_CLIENT_SECRET ?? normalized.secrets.keycloak_api_client_secret,
       openfga_db_password: env.OPENFGA_DB_PASSWORD ?? normalized.secrets.openfga_db_password,
@@ -411,6 +464,7 @@ function ensureGeneratedRuntimeState(generated) {
     openfga: generated.openfga,
     secrets: {
       s3_secret_key: generated.secrets.s3_secret_key || randomSecret(16),
+      keycloak_db_password: generated.secrets.keycloak_db_password || "",
       keycloak_web_client_secret: generated.secrets.keycloak_web_client_secret || randomSecret(),
       keycloak_api_client_secret: generated.secrets.keycloak_api_client_secret || randomSecret(),
       openfga_db_password: generated.secrets.openfga_db_password || randomSecret(),
@@ -453,6 +507,7 @@ function buildRuntimeEnv(config, generated) {
     KEYCLOAK_REALM: config.auth.keycloak_realm,
     KEYCLOAK_ADMIN_USER: config.auth.admin_user,
     KEYCLOAK_ADMIN_PASSWORD: config.auth.admin_password,
+    KEYCLOAK_DB_PASSWORD: generated.secrets.keycloak_db_password || config.auth.admin_password,
     KEYCLOAK_WEB_CLIENT_ID: config.auth.web_client_id,
     KEYCLOAK_WEB_CLIENT_SECRET: generated.secrets.keycloak_web_client_secret,
     KEYCLOAK_CLI_CLIENT_ID: config.auth.cli_client_id,
@@ -746,7 +801,7 @@ ${renderEnvList({
     environment:
 ${renderEnvList({
     POSTGRES_USER: "keycloak",
-    POSTGRES_PASSWORD: runtimeEnv.KEYCLOAK_ADMIN_PASSWORD,
+    POSTGRES_PASSWORD: runtimeEnv.KEYCLOAK_DB_PASSWORD,
     POSTGRES_DB: "keycloak"
   })}
     volumes:
@@ -763,12 +818,13 @@ ${renderEnvList({
     KC_DB: "postgres",
     KC_DB_URL: "jdbc:postgresql://keycloak_db:5432/keycloak",
     KC_DB_USERNAME: "keycloak",
-    KC_DB_PASSWORD: runtimeEnv.KEYCLOAK_ADMIN_PASSWORD,
+    KC_DB_PASSWORD: runtimeEnv.KEYCLOAK_DB_PASSWORD,
     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 +953,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 +1013,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 +1061,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 +1093,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 +1122,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 +1158,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 +1213,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
@@ -1111,6 +1271,95 @@ function listStackServices(config) {
   }
   return services;
 }
+function listManagedContainers(config) {
+  const output = tryRun("docker", ["ps", "-aq", "--filter", `name=^/${config.services.stack_name}_`], { quiet: true });
+  return output.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+}
+function stackExists(config) {
+  const output = tryRun("docker", ["stack", "ls", "--format", "{{.Name}}"], { quiet: true });
+  return output.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).includes(config.services.stack_name);
+}
+function waitForStackRemoval(config, timeoutSeconds = 60) {
+  if (currentOptions.dryRun) {
+    logDryRun(`Would wait for stack ${config.services.stack_name} to be removed`);
+    return;
+  }
+  const deadline = Date.now() + timeoutSeconds * 1e3;
+  while (Date.now() < deadline) {
+    if (!stackExists(config)) {
+      return;
+    }
+    sleepSeconds(2);
+  }
+  throw new Error(`Timed out waiting for stack ${config.services.stack_name} to be removed`);
+}
+async function confirmBootstrapReset(config) {
+  const volumeNames = STACK_VOLUMES.map((volume) => stackVolumeName(config, volume));
+  const containerIds = listManagedContainers(config);
+  const networkName = stackNetworkName(config);
+  logWarn("Bootstrap will delete existing EnvSync Docker resources before rebuilding infra.");
+  logWarn(`Stack: ${config.services.stack_name}`);
+  logWarn(`Network: ${networkName}`);
+  logWarn(`Volumes: ${volumeNames.join(", ")}`);
+  if (containerIds.length > 0) {
+    logWarn(`Containers: ${containerIds.join(", ")}`);
+  } else {
+    logWarn("Containers: none currently matched");
+  }
+  logWarn("This removes existing deployment data for the managed EnvSync services.");
+  const response = await askRequired(chalk.bold.red('Type "ARE YOU SURE?" to continue:'));
+  if (response !== "ARE YOU SURE?") {
+    throw new Error("Bootstrap aborted. Confirmation did not match 'ARE YOU SURE?'.");
+  }
+  logSuccess("Destructive bootstrap reset confirmed");
+}
+function cleanupBootstrapState(config) {
+  const volumeNames = STACK_VOLUMES.map((volume) => stackVolumeName(config, volume));
+  const containerIds = listManagedContainers(config);
+  const networkName = stackNetworkName(config);
+  logStep("Removing existing EnvSync deployment resources");
+  if (currentOptions.dryRun) {
+    if (stackExists(config)) {
+      logDryRun(`Would remove stack ${config.services.stack_name}`);
+      logCommand("docker", ["stack", "rm", config.services.stack_name]);
+    } else {
+      logDryRun(`No existing stack named ${config.services.stack_name} found`);
+    }
+    if (containerIds.length > 0) {
+      logDryRun(`Would remove containers: ${containerIds.join(", ")}`);
+      logCommand("docker", ["rm", "-f", ...containerIds]);
+    }
+    logDryRun(`Would remove network ${networkName} if present`);
+    logCommand("docker", ["network", "rm", networkName]);
+    for (const volumeName of volumeNames) {
+      logDryRun(`Would remove volume ${volumeName}`);
+      logCommand("docker", ["volume", "rm", "-f", volumeName]);
+    }
+    logSuccess("Bootstrap cleanup preview completed");
+    return;
+  }
+  if (stackExists(config)) {
+    logCommand("docker", ["stack", "rm", config.services.stack_name]);
+    run("docker", ["stack", "rm", config.services.stack_name]);
+    waitForStackRemoval(config);
+  }
+  const refreshedContainers = listManagedContainers(config);
+  if (refreshedContainers.length > 0) {
+    logCommand("docker", ["rm", "-f", ...refreshedContainers]);
+    run("docker", ["rm", "-f", ...refreshedContainers]);
+  }
+  if (commandSucceeds("docker", ["network", "inspect", networkName])) {
+    logCommand("docker", ["network", "rm", networkName]);
+    run("docker", ["network", "rm", networkName]);
+  }
+  for (const volumeName of volumeNames) {
+    if (commandSucceeds("docker", ["volume", "inspect", volumeName])) {
+      logCommand("docker", ["volume", "rm", "-f", volumeName]);
+      run("docker", ["volume", "rm", "-f", volumeName]);
+    }
+  }
+  logSuccess("Existing EnvSync deployment resources removed");
+}
 function serviceHealth(services, name) {
   return services.get(`${name}`) ?? "missing";
 }
@@ -1141,6 +1390,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,33 +1466,62 @@ 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();
+  if (currentOptions.dryRun) {
+    logWarn("Dry-run mode: bootstrap reset will be previewed but not executed.");
+  } else {
+    await confirmBootstrapReset(config);
+  }
+  cleanupBootstrapState(config);
   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);
-  waitForPostgresService(config, "keycloak", "keycloak_db", "keycloak", runtimeEnv.KEYCLOAK_ADMIN_PASSWORD);
+  waitForPostgresService(config, "keycloak", "keycloak_db", "keycloak", runtimeEnv.KEYCLOAK_DB_PASSWORD);
   waitForPostgresService(config, "openfga", "openfga_db", "openfga", runtimeEnv.OPENFGA_DB_PASSWORD);
   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 +1533,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 +1613,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 +1646,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 +1664,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 +1685,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 +1732,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 +1763,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 +1787,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 +1799,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.5",
   "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"