@xerg/cli 0.1.8 → 0.1.10

package/dist/index.js

@@ -4,6 +4,112 @@
 import { readFileSync as readFileSync7 } from "fs";
 import { styleText as styleText2 } from "util";
 
+// src/command-display.ts
+var PACKAGE_NAME = "@xerg/cli";
+var DEFAULT_COMMAND_PREFIX = "xerg";
+function resolveCommandDisplay(context) {
+  const runner = detectPackageExecutor(context);
+  if (!runner) {
+    return {
+      prefix: DEFAULT_COMMAND_PREFIX,
+      name: DEFAULT_COMMAND_PREFIX
+    };
+  }
+  return {
+    prefix: `${runner} ${PACKAGE_NAME}`,
+    name: PACKAGE_NAME
+  };
+}
+function formatCommand(command2, commandPrefix = resolveCommandDisplay().prefix) {
+  const suffix = Array.isArray(command2) ? command2.join(" ") : command2;
+  return suffix ? `${commandPrefix} ${suffix}` : commandPrefix;
+}
+function detectPackageExecutor(context) {
+  const env = context?.env ?? process.env;
+  const argv2 = context?.argv ?? process.argv;
+  const userAgent = normalizeSignal(env.npm_config_user_agent);
+  const execPath = normalizeSignal(env.npm_execpath);
+  const argvPath = normalizeSignal(argv2[1]);
+  const fromArgvPath = detectRunnerFromArgvPath(argvPath);
+  if (fromArgvPath) {
+    return fromArgvPath;
+  }
+  if (looksLikeInstalledCli(argvPath)) {
+    return null;
+  }
+  const fromUserAgent = detectRunnerFromSignal(userAgent);
+  if (fromUserAgent) {
+    return fromUserAgent;
+  }
+  const fromExecPath = detectRunnerFromSignal(execPath);
+  if (fromExecPath) {
+    return fromExecPath;
+  }
+  if (argvPath.includes("/_npx/") || argvPath.includes("\\_npx\\")) {
+    return "npx";
+  }
+  if (argvPath.includes("/.yarn/") && argvPath.includes("/dlx/")) {
+    return "yarn dlx";
+  }
+  if (argvPath.includes("/bunx/") || argvPath.includes("\\bunx\\")) {
+    return "bunx";
+  }
+  if (argvPath.includes("/dlx-") || argvPath.includes("\\dlx-")) {
+    return "pnpm dlx";
+  }
+  if (userAgent || execPath) {
+    return "npx";
+  }
+  return null;
+}
+function detectRunnerFromArgvPath(argvPath) {
+  if (!argvPath) {
+    return null;
+  }
+  if (argvPath.includes("/_npx/") || argvPath.includes("\\_npx\\")) {
+    return "npx";
+  }
+  if (argvPath.includes("/.yarn/") && argvPath.includes("/dlx/")) {
+    return "yarn dlx";
+  }
+  if (argvPath.includes("/bunx/") || argvPath.includes("\\bunx\\")) {
+    return "bunx";
+  }
+  if (argvPath.includes("/dlx-") || argvPath.includes("\\dlx-")) {
+    return "pnpm dlx";
+  }
+  return null;
+}
+function looksLikeInstalledCli(argvPath) {
+  if (!argvPath) {
+    return false;
+  }
+  const normalized = argvPath.replaceAll("\\", "/");
+  return normalized.endsWith("/node_modules/.bin/xerg") || normalized.includes("/node_modules/@xerg/cli/dist/index.js") || normalized.endsWith("/bin/xerg");
+}
+function detectRunnerFromSignal(signal) {
+  if (!signal) {
+    return null;
+  }
+  const tokens = signal.split(/[^a-z0-9]+/).filter(Boolean);
+  if (tokens.includes("pnpm")) {
+    return "pnpm dlx";
+  }
+  if (tokens.includes("yarn")) {
+    return "yarn dlx";
+  }
+  if (tokens.includes("bun")) {
+    return "bunx";
+  }
+  if (tokens.includes("npm")) {
+    return "npx";
+  }
+  return null;
+}
+function normalizeSignal(value) {
+  return value?.trim().toLowerCase() ?? "";
+}
+
 // src/commands/audit.ts
 import { readFileSync as readFileSync5 } from "fs";
 import { rmSync as rmSync4 } from "fs";
@@ -798,10 +904,17 @@ function segmentToRegExp(segment) {
   return new RegExp(`^${escaped}$`);
 }
 async function inspectOpenClawSources(options) {
+  options.onProgress?.("Checking local OpenClaw defaults...");
   const sources = await detectOpenClawSources(options);
   const notes = [];
+  options.onProgress?.(
+    sources.length > 0 ? `Detected ${sources.length} local source file${sources.length === 1 ? "" : "s"}.` : "No local OpenClaw source files were detected."
+  );
   if (sources.length === 0) {
     notes.push("No OpenClaw gateway logs or session files were detected.");
+    notes.push(
+      "Doctor checks local defaults by default. Use --remote or --railway to inspect remote targets."
+    );
     notes.push(
       "Use --log-file or --sessions-dir if your OpenClaw data lives outside the defaults."
     );
@@ -1383,6 +1496,7 @@ async function doctorOpenClaw(options) {
   return inspectOpenClawSources(options);
 }
 async function auditOpenClaw(options) {
+  options.onProgress?.("Scanning for OpenClaw source files...");
   if (options.compare && options.noDb) {
     throw new Error(
       "The --compare flag needs local snapshot history. Remove --no-db or provide --db <path>."
@@ -1390,13 +1504,19 @@ async function auditOpenClaw(options) {
   }
   const sources = await detectOpenClawSources(options);
   if (sources.length === 0) {
+    options.onProgress?.("No OpenClaw source files were detected.");
     throw new Error(
-      "No OpenClaw sources were detected. Run `xerg doctor` or provide --log-file / --sessions-dir."
+      `No OpenClaw sources were detected. Run \`${options.commandPrefix ?? "xerg"} doctor\` or provide --log-file / --sessions-dir.`
     );
   }
+  options.onProgress?.(`Detected ${sources.length} source file${sources.length === 1 ? "" : "s"}.`);
+  options.onProgress?.("Normalizing OpenClaw source files...");
   const runs = normalizeOpenClawSources(sources, options.since);
+  options.onProgress?.(`Normalized ${runs.length} run${runs.length === 1 ? "" : "s"}.`);
+  options.onProgress?.("Computing waste and savings findings...");
   const findings = buildFindings(runs);
   const dbPath = options.noDb ? void 0 : options.dbPath ?? getDefaultDbPath();
+  options.onProgress?.("Building audit summary...");
   const summary = buildAuditSummary({
     runs,
     findings,
@@ -1406,6 +1526,7 @@ async function auditOpenClaw(options) {
     comparisonKeyOverride: options.comparisonKeyOverride
   });
   if (options.compare && dbPath) {
+    options.onProgress?.("Looking for a comparable baseline audit...");
     const baseline = readLatestComparableAuditSummary({
       dbPath,
       comparisonKey: summary.comparisonKey,
@@ -1421,6 +1542,7 @@ async function auditOpenClaw(options) {
     }
   }
   if (dbPath) {
+    options.onProgress?.(`Persisting local snapshot to ${dbPath}...`);
     persistAudit(
       {
         summary,
@@ -1429,6 +1551,9 @@ async function auditOpenClaw(options) {
       },
       dbPath
     );
+    options.onProgress?.("Local snapshot stored.");
+  } else {
+    options.onProgress?.("Skipping local snapshot persistence (--no-db).");
   }
   return summary;
 }
@@ -1638,7 +1763,16 @@ function renderCompareBlock(summary) {
     ...findingChanges.length > 0 ? findingChanges : ["- High-confidence waste changes: none"]
   ];
 }
-function renderDoctorReport(report) {
+function renderDoctorReport(report, options) {
+  const commandPrefix = options?.commandPrefix ?? "xerg";
+  const nextSteps = report.canAudit ? [] : [
+    "",
+    "## Next steps",
+    `- Try explicit local paths: ${commandPrefix} doctor --log-file /path/to/openclaw.log --sessions-dir /path/to/sessions`,
+    `- Inspect an SSH host: ${commandPrefix} doctor --remote user@host`,
+    `- Inspect a Railway service: ${commandPrefix} doctor --railway`,
+    "- Remote audits still analyze locally after Xerg pulls the source files to your machine."
+  ];
   const sections = [
     "# Xerg doctor",
     "",
@@ -1652,7 +1786,8 @@ function renderDoctorReport(report) {
     ...report.sources.length > 0 ? report.sources.map((source) => `- [${source.kind}] ${source.path}`) : ["- none"],
     "",
     "## Notes",
-    ...report.notes.map((note) => `- ${note}`)
+    ...report.notes.map((note) => `- ${note}`),
+    ...nextSteps
   ];
   return sections.join("\n");
 }
@@ -1811,6 +1946,23 @@ var NoDataError = class extends Error {
   }
 };
 
+// src/log.ts
+function createCliLogger(options) {
+  return {
+    info(message) {
+      process.stderr.write(`${message}
+`);
+    },
+    verbose(message) {
+      if (!options.verbose) {
+        return;
+      }
+      process.stderr.write(`[verbose] ${message}
+`);
+    }
+  };
+}
+
 // src/push/client.ts
 async function pushAudit(payload, config) {
   const url = `${config.apiUrl}/v1/audits`;
@@ -1916,7 +2068,7 @@ function loadPushConfig() {
     };
   }
   throw new Error(
-    `No API key configured. Set XERG_API_KEY, add "apiKey" to ${CONFIG_PATH}, or run \`xerg login\`.
+    `No API key configured. Set XERG_API_KEY, add "apiKey" to ${CONFIG_PATH}, or run \`${formatCommand("login")}\`.
 Get your key at https://xerg.ai/dashboard/settings`
   );
 }
@@ -2124,14 +2276,19 @@ function buildComparisonKeyForRemote(source) {
   return `${source.host}:${logPath}:${sessPath}`;
 }
 async function pullRemoteFiles(opts) {
-  const { source, since, keepFiles = false } = opts;
+  const { source, since, keepFiles = false, onProgress } = opts;
+  onProgress?.(`Testing SSH connectivity to ${source.host}...`);
   const connectivity = testSshConnectivity(source);
   if (!connectivity.ok) {
     throw new Error(
       `Cannot connect to ${source.host}. Check SSH config and key access.${connectivity.error ? ` (${connectivity.error})` : ""}`
     );
   }
+  onProgress?.("SSH connectivity OK.");
   const useRsync = isRsyncAvailable();
+  onProgress?.(
+    useRsync ? "Local rsync detected. Xerg will prefer rsync and fall back to tar over SSH if needed." : "Local rsync not detected. Xerg will pull files with tar over SSH."
+  );
   const localBase = resolveLocalPath(source, keepFiles);
   const gatewayDir = join5(localBase, "gateway");
   const sessionsDir = join5(localBase, "sessions");
@@ -2139,6 +2296,7 @@ async function pullRemoteFiles(opts) {
   const remoteSessionsPath = source.sessionsDir ?? DEFAULT_SESSIONS_DIR;
   const { stdout: expandedSessions } = sshExec(source, `eval echo ${remoteSessionsPath}`);
   const resolvedSessionsPath = expandedSessions || remoteSessionsPath;
+  onProgress?.("Checking remote default paths for gateway logs and sessions...");
   const { status: logPathExists } = sshExec(source, `test -e ${remoteLogPath} && echo exists`);
   const { status: sessPathExists } = sshExec(
     source,
@@ -2147,6 +2305,7 @@ async function pullRemoteFiles(opts) {
   let pulledLog = false;
   let pulledSessions = false;
   if (logPathExists === 0) {
+    onProgress?.(`Pulling gateway logs from ${remoteLogPath}...`);
     const { stdout: isFile } = sshExec(source, `test -f ${remoteLogPath} && echo file`);
     if (isFile === "file") {
       const parentDir = remoteLogPath.slice(0, remoteLogPath.lastIndexOf("/")) || "/tmp";
@@ -2171,6 +2330,7 @@ async function pullRemoteFiles(opts) {
     }
   }
   if (sessPathExists === 0) {
+    onProgress?.(`Pulling session files from ${resolvedSessionsPath}...`);
     pulledSessions = pullDirectory({
       source,
       remotePath: resolvedSessionsPath,
@@ -2194,11 +2354,13 @@ async function pullRemoteFiles(opts) {
   };
   if (pulledLog) result.logFile = gatewayDir;
   if (pulledSessions) result.sessionsDir = sessionsDir;
+  onProgress?.("Remote files pulled successfully.");
   return result;
 }
 async function runRemoteDoctor(opts) {
-  const { source } = opts;
+  const { source, onProgress } = opts;
   const notes = [];
+  onProgress?.(`Testing SSH connectivity to ${source.host}...`);
   const connectivity = testSshConnectivity(source);
   if (!connectivity.ok) {
     return {
@@ -2222,7 +2384,9 @@ async function runRemoteDoctor(opts) {
       ]
     };
   }
+  onProgress?.("SSH connectivity OK.");
   notes.push("SSH connectivity: OK");
+  onProgress?.("Checking rsync availability locally and on the remote host...");
   const rsyncLocal = isRsyncAvailable();
   const rsyncRemote = isRemoteRsyncAvailable(source);
   notes.push(`rsync available locally: ${rsyncLocal ? "yes" : "no"}`);
@@ -2246,6 +2410,7 @@ async function runRemoteDoctor(opts) {
       totalBytes: Number.parseInt(sizeOut, 10) || 0
     };
   }
+  onProgress?.("Inspecting remote default paths...");
   const gateway = checkPath(DEFAULT_GATEWAY_DIR);
   const sessions = checkPath(DEFAULT_SESSIONS_DIR);
   if (gateway.exists) {
@@ -2458,23 +2623,27 @@ function buildComparisonKeyForRailway(source) {
   return `railway-linked:${logPath}:${sessPath}`;
 }
 async function pullRemoteFilesRailway(opts) {
-  const { source, since, keepFiles = false } = opts;
+  const { source, since, keepFiles = false, onProgress } = opts;
   const target = source.railway;
+  onProgress?.("Testing Railway service connectivity...");
   const { status } = railwayExec("echo ok", target);
   if (status !== 0) {
     throw new Error(
-      `Cannot reach Railway service${target ? ` (project: ${target.projectId})` : " (linked project)"}. Check railway CLI auth and service configuration.`
+      target ? `Cannot reach Railway service ${target.serviceId} (project: ${target.projectId}). Check the provided --project / --environment / --service values and confirm the Railway CLI can reach that service.` : "Cannot reach the Railway service linked to this directory. Run `railway link` here and choose the OpenClaw app service, or pass --project / --environment / --service explicitly."
     );
   }
+  onProgress?.("Railway service reachable.");
   const localBase = resolveLocalPath2(source, keepFiles);
   const gatewayDir = join6(localBase, "gateway");
   const sessionsDir = join6(localBase, "sessions");
   const remoteLogPath = source.logFile ?? DEFAULT_GATEWAY_DIR2;
+  onProgress?.("Checking Railway default paths for gateway logs and sessions...");
   const logCheck = checkRemotePath(remoteLogPath, target);
   const resolvedSessionsPath = findSessionsPath(target, source.sessionsDir);
   let pulledLog = false;
   let pulledSessions = false;
-  if (logCheck.exists) {
+  if (logCheck.fileCount > 0) {
+    onProgress?.(`Pulling gateway logs from ${remoteLogPath}...`);
     const { stdout: isFile } = railwayExec(`test -f ${remoteLogPath} && echo file`, target);
     if (isFile === "file") {
       const parentDir = remoteLogPath.slice(0, remoteLogPath.lastIndexOf("/")) || "/tmp";
@@ -2494,6 +2663,7 @@ async function pullRemoteFilesRailway(opts) {
     }
   }
   if (resolvedSessionsPath) {
+    onProgress?.(`Pulling session files from ${resolvedSessionsPath}...`);
     pulledSessions = tarRailwayPull({
       target,
       remotePath: resolvedSessionsPath,
@@ -2508,8 +2678,9 @@ async function pullRemoteFilesRailway(opts) {
     const checkedPaths = [remoteLogPath, DEFAULT_SESSIONS_DIR2, ...ALTERNATE_SESSION_PATHS].join(
       ", "
     );
+    const wrongServiceHint = target ? " Verify that the selected service is the OpenClaw app, or use --remote-log-file / --remote-sessions-dir for custom paths." : " If this directory is linked to a database or sidecar instead of the OpenClaw app, run `railway link` again and choose the app service.";
     throw new Error(
-      `No OpenClaw data found on Railway service. Checked: ${checkedPaths}. Use --remote-log-file or --remote-sessions-dir to specify custom paths.`
+      `No OpenClaw data found on Railway service. Checked: ${checkedPaths}. Use --remote-log-file or --remote-sessions-dir to specify custom paths.${wrongServiceHint}`
     );
   }
   const result = {
@@ -2518,12 +2689,14 @@ async function pullRemoteFilesRailway(opts) {
   };
   if (pulledLog) result.logFile = gatewayDir;
   if (pulledSessions) result.sessionsDir = sessionsDir;
+  onProgress?.("Railway files pulled successfully.");
   return result;
 }
 async function runRailwayDoctor(opts) {
-  const { source } = opts;
+  const { source, onProgress } = opts;
   const target = source.railway;
   const notes = [];
+  onProgress?.("Checking whether the Railway CLI is installed...");
   const whichCheck = spawnSync2("which", ["railway"], { stdio: "pipe", timeout: 5e3 });
   const railwayCliInstalled = whichCheck.status === 0;
   if (!railwayCliInstalled) {
@@ -2539,6 +2712,7 @@ async function runRailwayDoctor(opts) {
     };
   }
   const railwayPath = whichCheck.stdout?.toString().trim() ?? "railway";
+  onProgress?.("Checking Railway CLI authentication...");
   const versionCheck = spawnSync2("railway", ["version"], { stdio: "pipe", timeout: 1e4 });
   const versionStr = versionCheck.status === 0 ? versionCheck.stdout?.toString().trim() : railwayPath;
   notes.push(`Railway CLI: installed (${versionStr})`);
@@ -2558,6 +2732,7 @@ async function runRailwayDoctor(opts) {
     };
   }
   notes.push(`Authenticated as: ${railwayAuthUser}`);
+  onProgress?.("Testing Railway service connectivity...");
   const { status: reachStatus } = railwayExec("echo ok", target);
   const serviceReachable = reachStatus === 0;
   if (!serviceReachable) {
@@ -2568,16 +2743,17 @@ async function runRailwayDoctor(opts) {
       railwayAuthenticated: true,
       railwayAuthUser,
       serviceReachable: false,
-      serviceError: target ? `Cannot reach service ${target.serviceId}` : "Cannot reach linked service. Run: railway link",
+      serviceError: target ? `Cannot reach service ${target.serviceId} in project ${target.projectId}` : "Current directory is not linked to a reachable Railway service. Run `railway link` here and choose the OpenClaw app service, or pass --project / --environment / --service.",
       defaultPaths: emptyDefaultPaths(),
       alternateSessionPaths: [],
       notes: [
         ...notes,
-        target ? `Service unreachable (project: ${target.projectId}, service: ${target.serviceId})` : "Service unreachable. Ensure a project is linked with: railway link"
+        target ? `Service unreachable (project: ${target.projectId}, service: ${target.serviceId}). Verify the provided Railway IDs point at the OpenClaw app service.` : "Service unreachable for the current directory. Run `railway link` here and choose the OpenClaw app service, or pass explicit Railway IDs."
       ]
     };
   }
   notes.push("Service connectivity: OK");
+  onProgress?.("Inspecting Railway default paths...");
   const gateway = checkRemotePath(DEFAULT_GATEWAY_DIR2, target);
   const { stdout: expandedDefault } = railwayExec(`eval echo ${DEFAULT_SESSIONS_DIR2}`, target);
   const resolvedDefault = expandedDefault || DEFAULT_SESSIONS_DIR2;
@@ -2632,9 +2808,11 @@ async function runRailwayDoctor(opts) {
     alternateSessionPaths,
     notes
   };
+  let logCheck = null;
+  let sessCheck = null;
   if (source.logFile || source.sessionsDir) {
-    const logCheck = source.logFile ? checkRemotePath(source.logFile, target) : null;
-    const sessCheck = source.sessionsDir ? checkRemotePath(source.sessionsDir, target) : null;
+    logCheck = source.logFile ? checkRemotePath(source.logFile, target) : null;
+    sessCheck = source.sessionsDir ? checkRemotePath(source.sessionsDir, target) : null;
     report.customPaths = {
       logFileExists: logCheck?.exists ?? false,
       logFilePath: source.logFile ?? "",
@@ -2657,6 +2835,12 @@ async function runRailwayDoctor(opts) {
       notes.push(`Custom sessions path ${source.sessionsDir}: not found`);
     }
   }
+  const foundOpenClawData = gateway.fileCount > 0 || sessions.fileCount > 0 || alternateSessionPaths.some((path) => path.fileCount > 0) || (logCheck?.fileCount ?? 0) > 0 || (sessCheck?.fileCount ?? 0) > 0;
+  if (!foundOpenClawData) {
+    notes.push(
+      target ? "No OpenClaw data was found on this Railway service. Verify that the selected service is the OpenClaw app, or use --remote-log-file / --remote-sessions-dir for custom paths." : "No OpenClaw data was found on the linked Railway service. If this directory is linked to a database or sidecar instead of the OpenClaw app, run `railway link` again and choose the app service."
+    );
+  }
   return report;
 }
 function emptyDefaultPaths() {
@@ -2770,6 +2954,7 @@ async function auditOrNoData(...args) {
   }
 }
 async function runAuditCommand(options) {
+  const logger = createCliLogger({ verbose: options.verbose });
   if (options.dryRun && !options.push) {
     throw new Error("--dry-run requires --push.");
   }
@@ -2780,7 +2965,7 @@ async function runAuditCommand(options) {
     throw new Error("Use only one of --remote, --remote-config, or --railway.");
   }
   if (!options.remote && !options.remoteConfig && !options.railway) {
-    return runLocalAudit(options);
+    return runLocalAudit(options, logger);
   }
   if (options.railway) {
     const railwayTarget = buildRailwayTarget(options);
@@ -2789,14 +2974,14 @@ async function runAuditCommand(options) {
       remoteLogFile: options.remoteLogFile,
       remoteSessionsDir: options.remoteSessionsDir
     });
-    return runSingleRemoteAudit(source2, options);
+    return runSingleRemoteAudit(source2, options, logger);
   }
   if (options.remoteConfig) {
     const sources = loadRemoteConfig(options.remoteConfig);
     if (sources.length === 1) {
-      return runSingleRemoteAudit(sources[0], options);
+      return runSingleRemoteAudit(sources[0], options, logger);
     }
-    return runMultiRemoteAudit(sources, options);
+    return runMultiRemoteAudit(sources, options, logger);
   }
   const remote = options.remote;
   const source = buildSourceFromFlags({
@@ -2804,7 +2989,7 @@ async function runAuditCommand(options) {
     remoteLogFile: options.remoteLogFile,
     remoteSessionsDir: options.remoteSessionsDir
   });
-  return runSingleRemoteAudit(source, options);
+  return runSingleRemoteAudit(source, options, logger);
 }
 function buildRailwayTarget(options) {
   if (options.railwayProject && options.railwayEnvironment && options.railwayService) {
@@ -2816,14 +3001,23 @@ function buildRailwayTarget(options) {
   }
   return void 0;
 }
-async function runLocalAudit(options) {
+async function runLocalAudit(options, logger) {
+  logger.verbose("Running a local audit.");
+  if (options.logFile) {
+    logger.verbose(`Using explicit local log file: ${options.logFile}`);
+  }
+  if (options.sessionsDir) {
+    logger.verbose(`Using explicit local sessions directory: ${options.sessionsDir}`);
+  }
   const summary = await auditOrNoData({
     logFile: options.logFile,
     sessionsDir: options.sessionsDir,
     since: options.since,
     compare: options.compare,
     dbPath: options.db,
-    noDb: options.noDb
+    noDb: options.noDb,
+    commandPrefix: options.commandPrefix,
+    onProgress: logger.verbose
   });
   renderOutput(summary, options);
   if (options.push) {
@@ -2838,11 +3032,11 @@ function getComparisonKey(source) {
   }
   return buildComparisonKeyForRemote(source);
 }
-function pullFiles(source, since, keepFiles) {
+function pullFiles(source, since, keepFiles, onProgress) {
   if (source.transport === "railway") {
-    return pullRemoteFilesRailway({ source, since, keepFiles });
+    return pullRemoteFilesRailway({ source, since, keepFiles, onProgress });
   }
-  return pullRemoteFiles({ source, since, keepFiles });
+  return pullRemoteFiles({ source, since, keepFiles, onProgress });
 }
 function describeSource(source) {
   if (source.transport === "railway") {
@@ -2853,10 +3047,15 @@ function describeSource(source) {
 function sourceEnvironment(source) {
   return source.transport === "railway" ? "railway" : "remote";
 }
-async function runSingleRemoteAudit(source, options) {
-  process.stderr.write(`Pulling files from ${describeSource(source)}...
-`);
-  const pullResult = await pullFiles(source, options.since, options.keepRemoteFiles);
+async function runSingleRemoteAudit(source, options, logger) {
+  logger.info(`Pulling files from ${describeSource(source)}...`);
+  const pullResult = await pullFiles(
+    source,
+    options.since,
+    options.keepRemoteFiles,
+    logger.verbose
+  );
+  logger.verbose(`Files staged at ${pullResult.localPath}.`);
   try {
     const comparisonKeyOverride = getComparisonKey(source);
     const summary = await auditOrNoData({
@@ -2866,7 +3065,9 @@ async function runSingleRemoteAudit(source, options) {
       compare: options.compare,
       dbPath: options.db,
       noDb: options.noDb,
-      comparisonKeyOverride
+      comparisonKeyOverride,
+      commandPrefix: options.commandPrefix,
+      onProgress: logger.verbose
     });
     renderOutput(summary, options);
     if (options.push) {
@@ -2882,14 +3083,18 @@ async function runSingleRemoteAudit(source, options) {
     cleanupPullResult(pullResult, options.keepRemoteFiles);
   }
 }
-async function runMultiRemoteAudit(sources, options) {
+async function runMultiRemoteAudit(sources, options, logger) {
   const results = [];
   const errors = [];
   for (const source of sources) {
-    process.stderr.write(`Pulling files from ${source.name} (${describeSource(source)})...
-`);
+    logger.info(`Pulling files from ${source.name} (${describeSource(source)})...`);
     try {
-      const pullResult = await pullFiles(source, options.since, options.keepRemoteFiles);
+      const pullResult = await pullFiles(
+        source,
+        options.since,
+        options.keepRemoteFiles,
+        logger.verbose
+      );
       results.push({ source, pullResult });
     } catch (err) {
       const message = err instanceof Error ? err.message : "Unknown error";
@@ -2914,7 +3119,9 @@ ${errorMessages}`);
         compare: options.compare,
         dbPath: options.db,
         noDb: options.noDb,
-        comparisonKeyOverride
+        comparisonKeyOverride,
+        commandPrefix: options.commandPrefix,
+        onProgress: logger.verbose
       });
       summaries.push({ name: source.name, source, summary });
     }
@@ -3058,34 +3265,45 @@ function cleanupPullResult(pullResult, keepFiles) {
 
 // src/commands/doctor.ts
 async function runDoctorCommand(options) {
+  const logger = createCliLogger({ verbose: options.verbose });
   if (options.railway) {
+    logger.verbose("Inspecting Railway audit readiness.");
     const railwayTarget = buildRailwayTarget2(options);
     const source = buildRailwaySourceFromFlags({
       railway: railwayTarget,
       remoteLogFile: options.remoteLogFile,
       remoteSessionsDir: options.remoteSessionsDir
     });
-    const report2 = await runRailwayDoctor({ source });
+    const report2 = await runRailwayDoctor({ source, onProgress: logger.verbose });
     process.stdout.write(`${renderRailwayDoctorReport(report2)}
 `);
     return;
   }
   if (options.remote) {
+    logger.verbose(`Inspecting SSH audit readiness for ${options.remote}.`);
     const source = buildSourceFromFlags({
       remote: options.remote,
       remoteLogFile: options.remoteLogFile,
       remoteSessionsDir: options.remoteSessionsDir
     });
-    const report2 = await runRemoteDoctor({ source });
+    const report2 = await runRemoteDoctor({ source, onProgress: logger.verbose });
     process.stdout.write(`${renderRemoteDoctorReport(report2)}
 `);
     return;
   }
+  logger.verbose("Inspecting local OpenClaw audit readiness.");
+  if (options.logFile) {
+    logger.verbose(`Using explicit local log file: ${options.logFile}`);
+  }
+  if (options.sessionsDir) {
+    logger.verbose(`Using explicit local sessions directory: ${options.sessionsDir}`);
+  }
   const report = await doctorOpenClaw({
     logFile: options.logFile,
-    sessionsDir: options.sessionsDir
+    sessionsDir: options.sessionsDir,
+    onProgress: logger.verbose
   });
-  process.stdout.write(`${renderDoctorReport(report)}
+  process.stdout.write(`${renderDoctorReport(report, { commandPrefix: options.commandPrefix })}
 `);
 }
 function buildRailwayTarget2(options) {
@@ -3209,7 +3427,7 @@ async function runLoginCommand() {
   if (existing) {
     process.stderr.write(
       `Already logged in. Credentials stored at ${getCredentialsPath()}.
-Run ${colorBold("xerg logout")} first to re-authenticate.
+Run ${colorBold(formatCommand("logout"))} first to re-authenticate.
 `
     );
     return;
@@ -3275,7 +3493,7 @@ Credentials saved to ${getCredentialsPath()}.
         continue;
       }
       if (res.status === 410) {
-        throw new Error("Device code expired. Please run `xerg login` again.");
+        throw new Error(`Device code expired. Please run \`${formatCommand("login")}\` again.`);
       }
       const body = await res.json().catch(() => ({}));
       throw new Error(body.error || `Unexpected response: HTTP ${res.status}`);
@@ -3285,7 +3503,7 @@ Credentials saved to ${getCredentialsPath()}.
       }
     }
   }
-  throw new Error("Authentication timed out. Please run `xerg login` again.");
+  throw new Error(`Authentication timed out. Please run \`${formatCommand("login")}\` again.`);
 }
 async function openBrowser(url) {
   const { exec } = await import("child_process");
@@ -3373,12 +3591,12 @@ function loadPayloadFromCache() {
     summaries = listStoredAuditSummaries(dbPath);
   } catch {
     throw new NoDataError(
-      "No local audit database found. Run `xerg audit` first, or use `xerg push --file <path>`."
+      `No local audit database found. Run \`${formatCommand("audit")}\` first, or use \`${formatCommand("push --file <path>")}\`.`
     );
   }
   if (summaries.length === 0) {
     throw new NoDataError(
-      "No cached audit snapshots found. Run `xerg audit` first, or use `xerg push --file <path>`."
+      `No cached audit snapshots found. Run \`${formatCommand("audit")}\` first, or use \`${formatCommand("push --file <path>")}\`.`
     );
   }
   const latest = summaries[0];
@@ -3410,9 +3628,10 @@ function buildMeta2() {
 // src/index.ts
 var VERSION = readVersion();
 var argv = process.argv.slice(2);
+var commandDisplay = resolveCommandDisplay();
 var command = argv[0];
 if (!command || command === "--help" || command === "-h" || command === "help") {
-  process.stdout.write(renderRootHelp());
+  process.stdout.write(renderRootHelp(commandDisplay));
   process.exit(0);
 }
 if (command === "--version" || command === "-v" || command === "version") {
@@ -3422,7 +3641,7 @@ if (command === "--version" || command === "-v" || command === "version") {
 }
 run().catch((error) => {
   const message = error instanceof Error ? error.message : "Unknown error";
-  process.stderr.write(`${colorError(`xerg failed: ${message}`)}
+  process.stderr.write(`${colorError(`${commandDisplay.name} failed: ${message}`)}
 `);
   process.exitCode = error instanceof NoDataError ? 2 : 1;
 });
@@ -3432,12 +3651,18 @@ async function run() {
     if (options.json && options.markdown) {
       throw new Error("Use either --json or --markdown, not both.");
     }
-    await runAuditCommand(options);
+    await runAuditCommand({
+      ...options,
+      commandPrefix: commandDisplay.prefix
+    });
     return;
   }
   if (command === "doctor") {
     const options = parseDoctorOptions(argv.slice(1));
-    await runDoctorCommand(options);
+    await runDoctorCommand({
+      ...options,
+      commandPrefix: commandDisplay.prefix
+    });
     return;
   }
   if (command === "push") {
@@ -3453,7 +3678,9 @@ async function run() {
     runLogoutCommand();
     return;
   }
-  throw new Error(`Unknown command "${command}". Run \`xerg --help\` to see available commands.`);
+  throw new Error(
+    `Unknown command "${command}". Run \`${formatCommand("--help", commandDisplay.prefix)}\` to see available commands.`
+  );
 }
 function parseAuditOptions(raw) {
   const argv2 = expandEqualsArgs(raw);
@@ -3463,7 +3690,7 @@ function parseAuditOptions(raw) {
     switch (arg) {
       case "--help":
       case "-h":
-        process.stdout.write(renderAuditHelp());
+        process.stdout.write(renderAuditHelp(commandDisplay.prefix));
         process.exit(0);
         break;
       case "--log-file":
@@ -3534,6 +3761,9 @@ function parseAuditOptions(raw) {
       case "--dry-run":
         options.dryRun = true;
         break;
+      case "--verbose":
+        options.verbose = true;
+        break;
       case "--fail-above-waste-rate":
         options.failAboveWasteRate = readFloat(arg, argv2[index + 1]);
         index += 1;
@@ -3543,7 +3773,9 @@ function parseAuditOptions(raw) {
         index += 1;
         break;
       default:
-        throw new Error(`Unknown audit option "${arg}". Run \`xerg audit --help\` for usage.`);
+        throw new Error(
+          `Unknown audit option "${arg}". Run \`${formatCommand(["audit", "--help"], commandDisplay.prefix)}\` for usage.`
+        );
     }
   }
   return options;
@@ -3556,7 +3788,7 @@ function parsePushOptions(raw) {
     switch (arg) {
       case "--help":
       case "-h":
-        process.stdout.write(renderPushHelp());
+        process.stdout.write(renderPushHelp(commandDisplay.prefix));
         process.exit(0);
         break;
       case "--file":
@@ -3567,7 +3799,9 @@ function parsePushOptions(raw) {
         options.dryRun = true;
         break;
       default:
-        throw new Error(`Unknown push option "${arg}". Run \`xerg push --help\` for usage.`);
+        throw new Error(
+          `Unknown push option "${arg}". Run \`${formatCommand(["push", "--help"], commandDisplay.prefix)}\` for usage.`
+        );
     }
   }
   return options;
@@ -3580,7 +3814,7 @@ function parseDoctorOptions(raw) {
     switch (arg) {
       case "--help":
       case "-h":
-        process.stdout.write(renderDoctorHelp());
+        process.stdout.write(renderDoctorHelp(commandDisplay.prefix));
         process.exit(0);
         break;
       case "--log-file":
@@ -3618,8 +3852,13 @@ function parseDoctorOptions(raw) {
         options.railwayService = readValue(arg, argv2[index + 1]);
         index += 1;
         break;
+      case "--verbose":
+        options.verbose = true;
+        break;
       default:
-        throw new Error(`Unknown doctor option "${arg}". Run \`xerg doctor --help\` for usage.`);
+        throw new Error(
+          `Unknown doctor option "${arg}". Run \`${formatCommand(["doctor", "--help"], commandDisplay.prefix)}\` for usage.`
+        );
     }
   }
   return options;
@@ -3650,13 +3889,13 @@ function readFloat(flag, value) {
   }
   return num;
 }
-function renderRootHelp() {
-  return `xerg ${VERSION}
+function renderRootHelp(display = commandDisplay) {
+  return `${display.name} ${VERSION}
 
 Waste intelligence for OpenClaw workflows.
 
 Usage:
-  xerg <command> [options]
+  ${formatCommand("<command> [options]", display.prefix)}
 
 Commands:
   audit    Analyze OpenClaw logs and produce a waste intelligence report.
@@ -3670,13 +3909,13 @@ Global options:
   -v, --version  Show version
 `;
 }
-function renderAuditHelp() {
-  return `xerg audit
+function renderAuditHelp(commandPrefix = commandDisplay.prefix) {
+  return `${formatCommand("audit", commandPrefix)}
 
 Analyze OpenClaw logs and produce a waste intelligence report.
 
 Usage:
-  xerg audit [options]
+  ${formatCommand("audit [options]", commandPrefix)}
 
 Options:
   --log-file <path>           Explicit OpenClaw gateway log file to analyze
@@ -3709,6 +3948,7 @@ Railway options:
 Push options:
   --push                      Push the audit summary to the Xerg API after computing it
   --dry-run                   With --push: print the payload to stdout without sending it
+  --verbose                   Print progress updates to stderr while the audit runs
 
 Threshold options:
   --fail-above-waste-rate <n> Exit with code 3 if structural waste rate exceeds threshold (e.g. 0.30)
@@ -3717,13 +3957,13 @@ Threshold options:
   -h, --help                  Show help
 `;
 }
-function renderPushHelp() {
-  return `xerg push
+function renderPushHelp(commandPrefix = commandDisplay.prefix) {
+  return `${formatCommand("push", commandPrefix)}
 
 Push a cached audit snapshot to the Xerg API.
 
 Usage:
-  xerg push [options]
+  ${formatCommand("push [options]", commandPrefix)}
 
 Options:
   --file <path>               Push a specific snapshot file instead of the most recent cached audit
@@ -3733,21 +3973,22 @@ Options:
 
 Authentication:
   Set XERG_API_KEY in your environment, add "apiKey" to ~/.xerg/config.json,
-  or run \`xerg login\` to authenticate via browser.
+  or run \`${formatCommand("login", commandPrefix)}\` to authenticate via browser.
   Browser login stores a token at ~/.config/xerg/credentials.json by default.
 `;
 }
-function renderDoctorHelp() {
-  return `xerg doctor
+function renderDoctorHelp(commandPrefix = commandDisplay.prefix) {
+  return `${formatCommand("doctor", commandPrefix)}
 
 Inspect your machine for OpenClaw sources and audit readiness.
 
 Usage:
-  xerg doctor [options]
+  ${formatCommand("doctor [options]", commandPrefix)}
 
 Options:
   --log-file <path>           Explicit OpenClaw gateway log file to inspect
   --sessions-dir <path>       Explicit OpenClaw sessions directory to inspect
+  --verbose                   Print progress updates to stderr while doctor runs
 
 Remote options (SSH):
   --remote <user@host>        SSH target in user@host or user@host:port format