postgresai 0.14.0 → 0.15.0-dev.10

package/bin/postgres-ai.ts

@@ -1,18 +1,21 @@
 #!/usr/bin/env bun
 
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import pkg from "../package.json";
 import * as config from "../lib/config";
 import * as yaml from "js-yaml";
 import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
+import { fileURLToPath } from "url";
 import * as crypto from "node:crypto";
 import { Client } from "pg";
 import { startMcpServer } from "../lib/mcp-server";
 import { fetchIssues, fetchIssueComments, createIssueComment, fetchIssue, createIssue, updateIssue, updateIssueComment, fetchActionItem, fetchActionItems, createActionItem, updateActionItem, type ConfigChange } from "../lib/issues";
+import { fetchReports, fetchAllReports, fetchReportFiles, fetchReportFileData, renderMarkdownForTerminal, parseFlexibleDate } from "../lib/reports";
 import { resolveBaseUrls } from "../lib/util";
-import { applyInitPlan, applyUninitPlan, buildInitPlan, buildUninitPlan, connectWithSslFallback, DEFAULT_MONITORING_USER, KNOWN_PROVIDERS, redactPasswordsInSql, resolveAdminConnection, resolveMonitoringPassword, validateProvider, verifyInitSetup } from "../lib/init";
+import { uploadFile, downloadFile, buildMarkdownLink } from "../lib/storage";
+import { applyInitPlan, applyUninitPlan, buildInitPlan, buildUninitPlan, checkCurrentUserPermissions, connectWithSslFallback, DEFAULT_MONITORING_USER, formatPermissionCheckMessages, KNOWN_PROVIDERS, redactPasswordsInSql, resolveAdminConnection, resolveMonitoringPassword, validateProvider, verifyInitSetup } from "../lib/init";
 import { SupabaseClient, resolveSupabaseConfig, extractProjectRefFromUrl, applyInitPlanViaSupabase, verifyInitSetupViaSupabase, fetchPoolerDatabaseUrl, type PgCompatibleError } from "../lib/supabase";
 import * as pkce from "../lib/pkce";
 import * as authServer from "../lib/auth-server";
@@ -24,6 +27,18 @@ import { getCheckupEntry } from "../lib/checkup-dictionary";
 import { createCheckupReport, uploadCheckupReportJson, convertCheckupReportJsonToMarkdown, RpcError, formatRpcErrorForDisplay, withRetry } from "../lib/checkup-api";
 import { generateCheckSummary } from "../lib/checkup-summary";
 
+// Node.js version check - require Node 18+
+// Node 14 reached EOL in April 2023, Node 16 in September 2023.
+// Node 18+ is required for native ESM, modern crypto APIs, and security updates.
+const nodeVersion = parseInt(process.versions.node.split('.')[0], 10);
+if (nodeVersion < 18) {
+  console.error(`\x1b[31mError: postgresai requires Node 18 or higher.\x1b[0m`);
+  console.error(`You are running Node.js ${process.versions.node}.`);
+  console.error(`Please upgrade to Node.js 20 LTS or Node.js 22 for security updates.`);
+  console.error(`\nDownload: https://nodejs.org/`);
+  process.exit(1);
+}
+
 // Singleton readline interface for stdin prompts
 let rl: ReturnType<typeof createInterface> | null = null;
 function getReadline() {
@@ -39,21 +54,16 @@ function closeReadline() {
   }
 }
 
-// Helper functions for spawning processes - use Node.js child_process for compatibility
-async function execPromise(command: string): Promise<{ stdout: string; stderr: string }> {
-  return new Promise((resolve, reject) => {
-    childProcess.exec(command, (error, stdout, stderr) => {
-      if (error) {
-        const err = error as Error & { code: number };
-        err.code = typeof error.code === "number" ? error.code : 1;
-        reject(err);
-      } else {
-        resolve({ stdout, stderr });
-      }
-    });
-  });
+function stripMatchingQuotes(value: string): string {
+  const trimmed = value.trim();
+  const quote = trimmed[0];
+  if (trimmed.length >= 2 && (quote === '"' || quote === "'") && trimmed.endsWith(quote)) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
 }
 
+// Helper functions for spawning processes - use Node.js child_process for compatibility
 async function execFilePromise(file: string, args: string[]): Promise<{ stdout: string; stderr: string }> {
   return new Promise((resolve, reject) => {
     childProcess.execFile(file, args, (error, stdout, stderr) => {
@@ -330,7 +340,8 @@ function writeReportFiles(reports: Record<string, any>, outputPath: string): voi
   for (const [checkId, report] of Object.entries(reports)) {
     const filePath = path.join(outputPath, `${checkId}.json`);
     fs.writeFileSync(filePath, JSON.stringify(report, null, 2), "utf8");
-    console.log(`✓ ${checkId}: ${filePath}`);
+    const title = report.checkTitle || checkId;
+    console.log(`✓ ${checkId} ${title}: ${filePath}`);
   }
 }
 
@@ -398,6 +409,7 @@ interface CliOptions {
   apiKey?: string;
   apiBaseUrl?: string;
   uiBaseUrl?: string;
+  storageBaseUrl?: string;
 }
 
 /**
@@ -487,7 +499,11 @@ async function ensureDefaultMonitoringProject(): Promise<PathResolution> {
     }
   }
 
-  // Ensure instances.yml exists as a FILE (avoid Docker creating a directory)
+  // Ensure instances.yml exists as a FILE (avoid Docker creating a directory).
+  // Docker bind-mounts create missing paths as directories; replace if so.
+  if (fs.existsSync(instancesFile) && fs.lstatSync(instancesFile).isDirectory()) {
+    fs.rmSync(instancesFile, { recursive: true, force: true });
+  }
   if (!fs.existsSync(instancesFile)) {
     const header =
       "# PostgreSQL instances to monitor\n" +
@@ -566,6 +582,10 @@ program
   .option(
     "--ui-base-url <url>",
     "UI base URL for browser routes (overrides PGAI_UI_BASE_URL)"
+  )
+  .option(
+    "--storage-base-url <url>",
+    "Storage base URL for file uploads (overrides PGAI_STORAGE_BASE_URL)"
   );
 
 program
@@ -582,6 +602,27 @@ program
     console.log(`Default project saved: ${value}`);
   });
 
+program
+  .command("set-storage-url <url>")
+  .description("store storage base URL for file uploads")
+  .action(async (url: string) => {
+    const value = (url || "").trim();
+    if (!value) {
+      console.error("Error: url is required");
+      process.exitCode = 1;
+      return;
+    }
+    try {
+      const { normalizeBaseUrl } = await import("../lib/util");
+      const normalized = normalizeBaseUrl(value);
+      config.writeConfig({ storageBaseUrl: normalized });
+      console.log(`Storage URL saved: ${normalized}`);
+    } catch {
+      console.error(`Error: invalid URL: ${value}`);
+      process.exitCode = 1;
+    }
+  });
+
 program
   .command("prepare-db [conn]")
   .description("prepare database for monitoring: create monitoring user, required view(s), and grant permissions (idempotent)")
@@ -827,8 +868,8 @@ program
             } else {
               console.log("✓ prepare-db verify: OK");
               if (v.missingOptional.length > 0) {
-                console.log("⚠ Optional items missing:");
-                for (const m of v.missingOptional) console.log(`- ${m}`);
+                console.error("⚠ Optional items missing:");
+                for (const m of v.missingOptional) console.error(`- ${m}`);
               }
             }
             return;
@@ -959,8 +1000,8 @@ program
         } else {
           console.log(opts.resetPassword ? "✓ prepare-db password reset completed" : "✓ prepare-db completed");
           if (skippedOptional.length > 0) {
-            console.log("⚠ Some optional steps were skipped (not supported or insufficient privileges):");
-            for (const s of skippedOptional) console.log(`- ${s}`);
+            console.error("⚠ Some optional steps were skipped (not supported or insufficient privileges):");
+            for (const s of skippedOptional) console.error(`- ${s}`);
           }
           if (process.stdout.isTTY) {
             console.log(`Applied ${applied.length} steps`);
@@ -1141,8 +1182,8 @@ program
           } else {
             console.log(`✓ prepare-db verify: OK${opts.provider ? ` (provider: ${opts.provider})` : ""}`);
             if (v.missingOptional.length > 0) {
-              console.log("⚠ Optional items missing:");
-              for (const m of v.missingOptional) console.log(`- ${m}`);
+              console.error("⚠ Optional items missing:");
+              for (const m of v.missingOptional) console.error(`- ${m}`);
             }
           }
           return;
@@ -1269,8 +1310,8 @@ program
       } else {
         console.log(opts.resetPassword ? "✓ prepare-db password reset completed" : "✓ prepare-db completed");
         if (skippedOptional.length > 0) {
-          console.log("⚠ Some optional steps were skipped (not supported or insufficient privileges):");
-          for (const s of skippedOptional) console.log(`- ${s}`);
+          console.error("⚠ Some optional steps were skipped (not supported or insufficient privileges):");
+          for (const s of skippedOptional) console.error(`- ${s}`);
         }
         // Keep output compact but still useful
         if (process.stdout.isTTY) {
@@ -1586,11 +1627,11 @@ program
           console.log("✓ unprepare-db completed");
           console.log(`Applied ${applied.length} steps`);
         } else {
-          console.log("⚠ unprepare-db completed with errors");
+          console.error("⚠ unprepare-db completed with errors");
           console.log(`Applied ${applied.length} steps`);
-          console.log("Errors:");
+          console.error("Errors:");
           for (const err of errors) {
-            console.log(`  - ${err}`);
+            console.error(`  - ${err}`);
           }
           process.exitCode = 1;
         }
@@ -1785,6 +1826,24 @@ program
       const connResult = await connectWithSslFallback(Client, adminConn);
       client = connResult.client as Client;
 
+      // Preflight: verify the connected user has sufficient permissions
+      spinner.update("Checking database permissions");
+      const permCheck = await checkCurrentUserPermissions(client);
+      const permMessages = formatPermissionCheckMessages(permCheck);
+
+      for (const w of permMessages.warnings) {
+        console.error(w);
+      }
+
+      if (permMessages.failed) {
+        spinner.stop();
+        for (const e of permMessages.errors) {
+          console.error(e);
+        }
+        process.exitCode = 1;
+        return;
+      }
+
       // Generate reports
       let reports: Record<string, any>;
       if (checkId === "ALL") {
@@ -1912,8 +1971,8 @@ program
         }
       }
 
-      // Output JSON to stdout
-      if (shouldPrintJson) {
+      // Output JSON to stdout (unless --output is specified, in which case files are written instead)
+      if (shouldPrintJson && !outputPath) {
         console.log(JSON.stringify(reports, null, 2));
       }
 
@@ -2030,13 +2089,16 @@ function isDockerRunning(): boolean {
 }
 
 /**
- * Get docker compose command
+ * Get docker compose command.
+ * Prefer "docker compose" (V2 plugin) over legacy "docker-compose" (V1 standalone)
+ * because docker-compose V1 (<=1.29) is incompatible with modern Docker engines
+ * (KeyError: 'ContainerConfig' on container recreation).
  */
 function getComposeCmd(): string[] | null {
   const tryCmd = (cmd: string, args: string[]): boolean =>
     spawnSync(cmd, args, { stdio: "ignore", timeout: 5000 } as Parameters<typeof spawnSync>[2]).status === 0;
-  if (tryCmd("docker-compose", ["version"])) return ["docker-compose"];
   if (tryCmd("docker", ["compose", "version"])) return ["docker", "compose"];
+  if (tryCmd("docker-compose", ["version"])) return ["docker-compose"];
   return null;
 }
 
@@ -2061,6 +2123,85 @@ function checkRunningContainers(): { running: boolean; containers: string[] } {
   }
 }
 
+/**
+ * Register monitoring instance with the API (non-blocking).
+ * Returns immediately, logs result in background.
+ */
+function registerMonitoringInstance(
+  apiKey: string,
+  projectName: string,
+  opts?: { apiBaseUrl?: string; debug?: boolean }
+): void {
+  const { apiBaseUrl } = resolveBaseUrls(opts);
+  const url = `${apiBaseUrl}/rpc/monitoring_instance_register`;
+  const debug = opts?.debug;
+
+  if (debug) {
+    console.error(`\nDebug: Registering monitoring instance...`);
+    console.error(`Debug: POST ${url}`);
+    console.error(`Debug: project_name=${projectName}`);
+  }
+
+  // Fire and forget - don't block the main flow
+  fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      api_token: apiKey,
+      project_name: projectName,
+    }),
+  })
+    .then(async (res) => {
+      const body = await res.text().catch(() => "");
+      if (!res.ok) {
+        if (debug) {
+          console.error(`Debug: Monitoring registration failed: HTTP ${res.status}`);
+          console.error(`Debug: Response: ${body}`);
+        }
+        return;
+      }
+      if (debug) {
+        console.error(`Debug: Monitoring registration response: ${body}`);
+      }
+    })
+    .catch((err) => {
+      if (debug) {
+        console.error(`Debug: Monitoring registration error: ${err.message}`);
+      }
+    });
+}
+
+/**
+ * Update .pgwatch-config file with key=value pairs.
+ * Preserves existing values not being updated.
+ */
+function updatePgwatchConfig(configPath: string, updates: Record<string, string>): void {
+  let lines: string[] = [];
+
+  // Read existing config if it exists
+  if (fs.existsSync(configPath)) {
+    const stats = fs.statSync(configPath);
+    if (!stats.isDirectory()) {
+      const content = fs.readFileSync(configPath, "utf8");
+      lines = content.split(/\r?\n/).filter(l => l.trim() !== "");
+    }
+  }
+
+  // Update or add each key
+  for (const [key, value] of Object.entries(updates)) {
+    const existingIndex = lines.findIndex(l => l.startsWith(key + "="));
+    if (existingIndex >= 0) {
+      lines[existingIndex] = `${key}=${value}`;
+    } else {
+      lines.push(`${key}=${value}`);
+    }
+  }
+
+  fs.writeFileSync(configPath, lines.join("\n") + "\n", { encoding: "utf8", mode: 0o600 });
+}
+
 /**
  * Run docker compose command
  */
@@ -2115,6 +2256,26 @@ async function runCompose(args: string[], grafanaPassword?: string): Promise<num
     }
   }
 
+  // Load VM auth credentials from .env if not already set
+  const envFilePath = path.resolve(projectDir, ".env");
+  if (fs.existsSync(envFilePath)) {
+    try {
+      const envContent = fs.readFileSync(envFilePath, "utf8");
+      if (!env.VM_AUTH_USERNAME) {
+        const m = envContent.match(/^VM_AUTH_USERNAME=([^\r\n]+)/m);
+        if (m) env.VM_AUTH_USERNAME = stripMatchingQuotes(m[1]);
+      }
+      if (!env.VM_AUTH_PASSWORD) {
+        const m = envContent.match(/^VM_AUTH_PASSWORD=([^\r\n]+)/m);
+        if (m) env.VM_AUTH_PASSWORD = stripMatchingQuotes(m[1]);
+      }
+    } catch (err) {
+      if (process.env.DEBUG) {
+        console.warn(`Warning: Could not read VM auth from .env: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+  }
+
   // On macOS, self-node-exporter can't mount host root filesystem - skip it
   const finalArgs = [...args];
   if (process.platform === "darwin" && args.includes("up")) {
@@ -2145,12 +2306,13 @@ mon
   .option("--api-key <key>", "Postgres AI API key for automated report uploads")
   .option("--db-url <url>", "PostgreSQL connection URL to monitor")
   .option("--tag <tag>", "Docker image tag to use (e.g., 0.14.0, 0.14.0-dev.33)")
+  .option("--project <name>", "Docker Compose project name (default: postgres_ai)")
   .option("-y, --yes", "accept all defaults and skip interactive prompts", false)
-  .action(async (opts: { demo: boolean; apiKey?: string; dbUrl?: string; tag?: string; yes: boolean }) => {
+  .action(async (opts: { demo: boolean; apiKey?: string; dbUrl?: string; tag?: string; project?: string; yes: boolean }) => {
     // Get apiKey from global program options (--api-key is defined globally)
     // This is needed because Commander.js routes --api-key to the global option, not the subcommand's option
     const globalOpts = program.opts<CliOptions>();
-    const apiKey = opts.apiKey || globalOpts.apiKey;
+    let apiKey = opts.apiKey || globalOpts.apiKey;
 
     console.log("\n=================================");
     console.log("  PostgresAI monitoring local install");
@@ -2158,16 +2320,26 @@ mon
     console.log("This will install, configure, and start the monitoring system\n");
 
     // Ensure we have a project directory with docker-compose.yml even if running from elsewhere
-    const { projectDir } = await resolveOrInitPaths();
+    const { projectDir, instancesFile: instancesPath } = await resolveOrInitPaths();
     console.log(`Project directory: ${projectDir}\n`);
 
+    // Save project name to .pgwatch-config if provided (used by reporter container)
+    if (opts.project) {
+      const cfgPath = path.resolve(projectDir, ".pgwatch-config");
+      updatePgwatchConfig(cfgPath, { project_name: opts.project });
+      console.log(`Using project name: ${opts.project}\n`);
+    }
+
     // Update .env with custom tag if provided
     const envFile = path.resolve(projectDir, ".env");
 
-    // Build .env content, preserving important existing values (registry, password)
-    // Note: PGAI_TAG is intentionally NOT preserved - the CLI version should always match Docker images
+    // Build .env content, preserving important existing values.
+    // Note: PGAI_TAG is intentionally NOT preserved - the CLI version should always match Docker images.
     let existingRegistry: string | null = null;
     let existingPassword: string | null = null;
+    let existingReplicatorPassword: string | null = null;
+    let existingVmAuthUsername: string | null = null;
+    let existingVmAuthPassword: string | null = null;
 
     if (fs.existsSync(envFile)) {
       const existingEnv = fs.readFileSync(envFile, "utf8");
@@ -2176,6 +2348,12 @@ mon
       if (registryMatch) existingRegistry = registryMatch[1].trim();
       const pwdMatch = existingEnv.match(/^GF_SECURITY_ADMIN_PASSWORD=(.+)$/m);
       if (pwdMatch) existingPassword = pwdMatch[1].trim();
+      const replicatorPwdMatch = existingEnv.match(/^REPLICATOR_PASSWORD=(.+)$/m);
+      if (replicatorPwdMatch) existingReplicatorPassword = replicatorPwdMatch[1].trim();
+      const vmAuthUserMatch = existingEnv.match(/^VM_AUTH_USERNAME=(.+)$/m);
+      if (vmAuthUserMatch) existingVmAuthUsername = stripMatchingQuotes(vmAuthUserMatch[1]);
+      const vmAuthPasswordMatch = existingEnv.match(/^VM_AUTH_PASSWORD=(.+)$/m);
+      if (vmAuthPasswordMatch) existingVmAuthPassword = stripMatchingQuotes(vmAuthPasswordMatch[1]);
     }
 
     // Priority: CLI --tag flag > package version
@@ -2191,6 +2369,11 @@ mon
     if (existingPassword) {
       envLines.push(`GF_SECURITY_ADMIN_PASSWORD=${existingPassword}`);
     }
+    envLines.push(
+      `REPLICATOR_PASSWORD=${existingReplicatorPassword || crypto.randomBytes(32).toString("hex")}`,
+    );
+    envLines.push(`VM_AUTH_USERNAME=${existingVmAuthUsername || "vmauth"}`);
+    envLines.push(`VM_AUTH_PASSWORD=${existingVmAuthPassword || crypto.randomBytes(18).toString("base64")}`);
     fs.writeFileSync(envFile, envLines.join("\n") + "\n", { encoding: "utf8", mode: 0o600 });
 
     if (opts.tag) {
@@ -2199,8 +2382,8 @@ mon
 
     // Validate conflicting options
     if (opts.demo && opts.dbUrl) {
-      console.log("⚠ Both --demo and --db-url provided. Demo mode includes its own database.");
-      console.log("⚠ The --db-url will be ignored in demo mode.\n");
+      console.error("⚠ Both --demo and --db-url provided. Demo mode includes its own database.");
+      console.error("⚠ The --db-url will be ignored in demo mode.\n");
       opts.dbUrl = undefined;
     }
 
@@ -2216,7 +2399,7 @@ mon
     // Check if containers are already running
     const { running, containers } = checkRunningContainers();
     if (running) {
-      console.log(`⚠ Monitoring services are already running: ${containers.join(", ")}`);
+      console.error(`⚠ Monitoring services are already running: ${containers.join(", ")}`);
       console.log("Use 'postgres-ai mon restart' to restart them\n");
       return;
     }
@@ -2230,15 +2413,12 @@ mon
         console.log("Using API key provided via --api-key parameter");
         config.writeConfig({ apiKey });
         // Keep reporter compatibility (docker-compose mounts .pgwatch-config)
-        fs.writeFileSync(path.resolve(projectDir, ".pgwatch-config"), `api_key=${apiKey}\n`, {
-          encoding: "utf8",
-          mode: 0o600
-        });
+        updatePgwatchConfig(path.resolve(projectDir, ".pgwatch-config"), { api_key: apiKey });
         console.log("✓ API key saved\n");
       } else if (opts.yes) {
         // Auto-yes mode without API key - skip API key setup
         console.log("Auto-yes mode: no API key provided, skipping API key setup");
-        console.log("⚠ Reports will be generated locally only");
+        console.error("⚠ Reports will be generated locally only");
         console.log("You can add an API key later with: postgres-ai add-key <api_key>\n");
       } else {
         const answer = await question("Do you have a Postgres AI API key? (Y/n): ");
@@ -2252,24 +2432,22 @@ mon
             if (trimmedKey) {
               config.writeConfig({ apiKey: trimmedKey });
               // Keep reporter compatibility (docker-compose mounts .pgwatch-config)
-              fs.writeFileSync(path.resolve(projectDir, ".pgwatch-config"), `api_key=${trimmedKey}\n`, {
-                encoding: "utf8",
-                mode: 0o600
-              });
+              updatePgwatchConfig(path.resolve(projectDir, ".pgwatch-config"), { api_key: trimmedKey });
+              apiKey = trimmedKey;  // Update for later use in registerMonitoringInstance
               console.log("✓ API key saved\n");
               break;
             }
 
-            console.log("⚠ API key cannot be empty");
+            console.error("⚠ API key cannot be empty");
             const retry = await question("Try again or skip API key setup, retry? (Y/n): ");
             if (retry.toLowerCase() === "n") {
-              console.log("⚠ Skipping API key setup - reports will be generated locally only");
+              console.error("⚠ Skipping API key setup - reports will be generated locally only");
               console.log("You can add an API key later with: postgres-ai add-key <api_key>\n");
               break;
             }
           }
         } else {
-          console.log("⚠ Skipping API key setup - reports will be generated locally only");
+          console.error("⚠ Skipping API key setup - reports will be generated locally only");
           console.log("You can add an API key later with: postgres-ai add-key <api_key>\n");
         }
       }
@@ -2315,21 +2493,25 @@ mon
 
         // Test connection
         console.log("Testing connection to the added instance...");
-        try {
-          const client = new Client({ connectionString: connStr });
-          await client.connect();
-          const result = await client.query("select version();");
-          console.log("✓ Connection successful");
-          console.log(`${result.rows[0].version}\n`);
-          await client.end();
-        } catch (error) {
-          const message = error instanceof Error ? error.message : String(error);
-          console.error(`✗ Connection failed: ${message}\n`);
+        {
+          let testClient: InstanceType<typeof Client> | null = null;
+          try {
+            testClient = new Client({ connectionString: connStr, connectionTimeoutMillis: 10000 });
+            await testClient.connect();
+            const result = await testClient.query("select version();");
+            console.log("✓ Connection successful");
+            console.log(`${result.rows[0].version}\n`);
+          } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`✗ Connection failed: ${message}\n`);
+          } finally {
+            if (testClient) await testClient.end();
+          }
         }
       } else if (opts.yes) {
         // Auto-yes mode without database URL - skip database setup
         console.log("Auto-yes mode: no database URL provided, skipping database setup");
-        console.log("⚠ No PostgreSQL instance added");
+        console.error("⚠ No PostgreSQL instance added");
         console.log("You can add one later with: postgres-ai mon targets add\n");
       } else {
         console.log("You need to add at least one PostgreSQL instance to monitor");
@@ -2347,7 +2529,7 @@ mon
             const m = connStr.match(/^postgresql:\/\/([^:]+):([^@]+)@([^:\/]+)(?::(\d+))?\/(.+)$/);
             if (!m) {
               console.error("✗ Invalid connection string format");
-              console.log("⚠ Continuing without adding instance\n");
+              console.error("⚠ Continuing without adding instance\n");
             } else {
               const host = m[3];
               const db = m[5];
@@ -2359,27 +2541,62 @@ mon
 
               // Test connection
               console.log("Testing connection to the added instance...");
-              try {
-                const client = new Client({ connectionString: connStr });
-                await client.connect();
-                const result = await client.query("select version();");
-                console.log("✓ Connection successful");
-                console.log(`${result.rows[0].version}\n`);
-                await client.end();
-              } catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                console.error(`✗ Connection failed: ${message}\n`);
+              {
+                let testClient: InstanceType<typeof Client> | null = null;
+                try {
+                  testClient = new Client({ connectionString: connStr, connectionTimeoutMillis: 10000 });
+                  await testClient.connect();
+                  const result = await testClient.query("select version();");
+                  console.log("✓ Connection successful");
+                  console.log(`${result.rows[0].version}\n`);
+                } catch (error) {
+                  const message = error instanceof Error ? error.message : String(error);
+                  console.error(`✗ Connection failed: ${message}\n`);
+                } finally {
+                  if (testClient) await testClient.end();
+                }
               }
             }
           } else {
-            console.log("⚠ No PostgreSQL instance added - you can add one later with: postgres-ai mon targets add\n");
+            console.error("⚠ No PostgreSQL instance added - you can add one later with: postgres-ai mon targets add\n");
           }
         } else {
-          console.log("⚠ No PostgreSQL instance added - you can add one later with: postgres-ai mon targets add\n");
+          console.error("⚠ No PostgreSQL instance added - you can add one later with: postgres-ai mon targets add\n");
         }
       }
     } else {
-      console.log("Step 2: Demo mode enabled - using included demo PostgreSQL database\n");
+      // Demo mode: configure instances.yml from the bundled demo template.
+      //
+      // Side effects:
+      //   - Writes instancesPath (instances.yml next to docker-compose.yml)
+      //   - If Docker previously bind-mounted instances.yml as a directory, removes it first.
+      //
+      // Failure modes:
+      //   - Exits with code 1 if instances.demo.yml is not found in any candidate path.
+      //     This is fatal because starting without a target produces empty dashboards that
+      //     look like a bug rather than a misconfiguration.
+      //
+      // Template search order (import.meta.url is resolved at runtime, not baked in at build):
+      //   1. npm layout:  dist/bin/../../instances.demo.yml  →  package-root/instances.demo.yml
+      //   2. dev layout:  cli/bin/../../../instances.demo.yml →  repo-root/instances.demo.yml
+      console.log("Step 2: Demo mode enabled - using included demo PostgreSQL database");
+      const currentDir = path.dirname(fileURLToPath(import.meta.url));
+      const demoCandidates = [
+        path.resolve(currentDir, "..", "..", "instances.demo.yml"),        // npm: dist/bin -> package root
+        path.resolve(currentDir, "..", "..", "..", "instances.demo.yml"),  // dev: cli/bin -> repo root
+      ];
+      const demoSrc = demoCandidates.find(p => fs.existsSync(p));
+      if (demoSrc) {
+        // Remove directory artifact left by Docker bind-mounts before copying
+        if (fs.existsSync(instancesPath) && fs.lstatSync(instancesPath).isDirectory()) {
+          fs.rmSync(instancesPath, { recursive: true, force: true });
+        }
+        fs.copyFileSync(demoSrc, instancesPath);
+        console.log("✓ Demo monitoring target configured\n");
+      } else {
+        console.error(`Error: instances.demo.yml not found — cannot configure demo target.\nSearched: ${demoCandidates.join(", ")}\n`);
+        process.exit(1);
+      }
     }
 
     // Step 3: Update configuration
@@ -2395,6 +2612,8 @@ mon
     console.log(opts.demo ? "Step 4: Configuring Grafana security..." : "Step 4: Configuring Grafana security...");
     const cfgPath = path.resolve(projectDir, ".pgwatch-config");
     let grafanaPassword = "";
+    let vmAuthUsername = "";
+    let vmAuthPassword = "";
 
     try {
       if (fs.existsSync(cfgPath)) {
@@ -2410,8 +2629,8 @@ mon
 
       if (!grafanaPassword) {
         console.log("Generating secure Grafana password...");
-        const { stdout: password } = await execPromise("openssl rand -base64 12 | tr -d '\n'");
-        grafanaPassword = password.trim();
+        const { stdout: password } = await execFilePromise("openssl", ["rand", "-base64", "12"]);
+        grafanaPassword = password.trim().replace(/\n/g, "");
 
         let configContent = "";
         if (fs.existsSync(cfgPath)) {
@@ -2428,12 +2647,58 @@ mon
 
       console.log("✓ Grafana password configured\n");
     } catch (error) {
-      console.log("⚠ Could not generate Grafana password automatically");
+      console.error("⚠ Could not generate Grafana password automatically");
       console.log("Using default password: demo\n");
       grafanaPassword = "demo";
     }
 
+    // Generate VictoriaMetrics auth credentials
+    try {
+      const envFile = path.resolve(projectDir, ".env");
+
+      // Read existing VM auth from .env if present
+      if (fs.existsSync(envFile)) {
+        const envContent = fs.readFileSync(envFile, "utf8");
+        const userMatch = envContent.match(/^VM_AUTH_USERNAME=([^\r\n]+)/m);
+        const passMatch = envContent.match(/^VM_AUTH_PASSWORD=([^\r\n]+)/m);
+        if (userMatch) vmAuthUsername = stripMatchingQuotes(userMatch[1]);
+        if (passMatch) vmAuthPassword = stripMatchingQuotes(passMatch[1]);
+      }
+
+      if (!vmAuthUsername || !vmAuthPassword) {
+        console.log("Generating VictoriaMetrics auth credentials...");
+        vmAuthUsername = vmAuthUsername || "vmauth";
+        if (!vmAuthPassword) {
+          const { stdout: vmPass } = await execFilePromise("openssl", ["rand", "-base64", "12"]);
+          vmAuthPassword = vmPass.trim().replace(/\n/g, "");
+        }
+
+        // Update .env file with VM auth credentials
+        let envContent = "";
+        if (fs.existsSync(envFile)) {
+          envContent = fs.readFileSync(envFile, "utf8");
+        }
+        const envLines = envContent.split(/\r?\n/)
+          .filter((l) => !/^VM_AUTH_USERNAME=/.test(l) && !/^VM_AUTH_PASSWORD=/.test(l))
+          .filter((l, i, arr) => !(i === arr.length - 1 && l === ''));
+        envLines.push(`VM_AUTH_USERNAME=${vmAuthUsername}`);
+        envLines.push(`VM_AUTH_PASSWORD=${vmAuthPassword}`);
+        fs.writeFileSync(envFile, envLines.join("\n") + "\n", { encoding: "utf8", mode: 0o600 });
+      }
+
+      console.log("✓ VictoriaMetrics auth configured\n");
+    } catch (error) {
+      console.error("⚠ Could not generate VictoriaMetrics auth credentials automatically");
+      if (process.env.DEBUG) {
+        console.warn(`  ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+
     // Step 5: Start services
+    // Remove stopped containers left by "run --rm" dependencies (e.g. config-init)
+    // to avoid docker-compose v1 'ContainerConfig' error on recreation.
+    // Best-effort: ignore exit code — container may not exist, failure here is non-fatal.
+    await runCompose(["rm", "-f", "-s", "config-init"]);
     console.log("Step 5: Starting monitoring services...");
     const code2 = await runCompose(["up", "-d", "--force-recreate"], grafanaPassword);
     if (code2 !== 0) {
@@ -2442,6 +2707,15 @@ mon
     }
     console.log("✓ Services started\n");
 
+    // Register monitoring instance with API (non-blocking, only if API key is configured)
+    if (apiKey && !opts.demo) {
+      const projectName = opts.project || "postgres-ai-monitoring";
+      registerMonitoringInstance(apiKey, projectName, {
+        apiBaseUrl: globalOpts.apiBaseUrl,
+        debug: !!process.env.DEBUG,
+      });
+    }
+
     // Final summary
     console.log("=================================");
     console.log("  Local install completed!");
@@ -2474,6 +2748,9 @@ mon
     console.log("🚀 MAIN ACCESS POINT - Start here:");
     console.log("   Grafana Dashboard: http://localhost:3000");
     console.log(`   Login: monitor / ${grafanaPassword}`);
+    if (vmAuthUsername && vmAuthPassword) {
+      console.log(`   VictoriaMetrics Auth: ${vmAuthUsername} / ${vmAuthPassword}`);
+    }
     console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");
   });
 
@@ -2674,7 +2951,7 @@ mon
     console.log(`Project Directory: ${projectDir}`);
     console.log(`Docker Compose File: ${composeFile}`);
     console.log(`Instances File: ${instancesFile}`);
-    if (fs.existsSync(instancesFile)) {
+    if (fs.existsSync(instancesFile) && !fs.lstatSync(instancesFile).isDirectory()) {
       console.log("\nInstances configuration:\n");
       const text = fs.readFileSync(instancesFile, "utf8");
       process.stdout.write(text);
@@ -2705,16 +2982,16 @@ mon
 
       // Fetch latest changes
       console.log("Fetching latest changes...");
-      await execPromise("git fetch origin");
+      await execFilePromise("git", ["fetch", "origin"]);
 
       // Check current branch
-      const { stdout: branch } = await execPromise("git rev-parse --abbrev-ref HEAD");
+      const { stdout: branch } = await execFilePromise("git", ["rev-parse", "--abbrev-ref", "HEAD"]);
       const currentBranch = branch.trim();
       console.log(`Current branch: ${currentBranch}`);
 
       // Pull latest changes
       console.log("Pulling latest changes...");
-      const { stdout: pullOut } = await execPromise("git pull origin " + currentBranch);
+      const { stdout: pullOut } = await execFilePromise("git", ["pull", "origin", currentBranch]);
       console.log(pullOut);
 
       // Update Docker images
@@ -2811,7 +3088,7 @@ mon
       if (downCode === 0) {
         console.log("✓ Monitoring services stopped and removed");
       } else {
-        console.log("⚠ Could not stop services (may not be running)");
+        console.error("⚠ Could not stop services (may not be running)");
       }
 
       // Remove any orphaned containers that docker compose down missed
@@ -2890,7 +3167,7 @@ targets
   .description("list monitoring target databases")
   .action(async () => {
     const { instancesFile: instancesPath, projectDir } = await resolveOrInitPaths();
-    if (!fs.existsSync(instancesPath)) {
+    if (!fs.existsSync(instancesPath) || fs.lstatSync(instancesPath).isDirectory()) {
       console.error(`instances.yml not found in ${projectDir}`);
       process.exitCode = 1;
       return;
@@ -2956,7 +3233,7 @@ targets
 
     // Check if instance already exists
     try {
-      if (fs.existsSync(file)) {
+      if (fs.existsSync(file) && !fs.lstatSync(file).isDirectory()) {
         const content = fs.readFileSync(file, "utf8");
         const instances = yaml.load(content) as Instance[] | null || [];
         if (Array.isArray(instances)) {
@@ -2970,15 +3247,20 @@ targets
       }
     } catch (err) {
       // If YAML parsing fails, fall back to simple check
-      const content = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
-      if (new RegExp(`^- name: ${instanceName}$`, "m").test(content)) {
+      const isFile = fs.existsSync(file) && !fs.lstatSync(file).isDirectory();
+      const content = isFile ? fs.readFileSync(file, "utf8") : "";
+      const escapedName = instanceName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      if (new RegExp(`^- name: ${escapedName}$`, "m").test(content)) {
         console.error(`Monitoring target '${instanceName}' already exists`);
         process.exitCode = 1;
         return;
       }
     }
 
-    // Add new instance
+    // Add new instance — if instances.yml is a directory (Docker artifact), replace it with a file
+    if (fs.existsSync(file) && fs.lstatSync(file).isDirectory()) {
+      fs.rmSync(file, { recursive: true, force: true });
+    }
     const body = `- name: ${instanceName}\n  conn_str: ${connStr}\n  preset_metrics: full\n  custom_metrics:\n  is_enabled: true\n  group: default\n  custom_tags:\n    env: production\n    cluster: default\n    node_name: ${instanceName}\n    sink_type: ~sink_type~\n`;
     const content = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
     fs.appendFileSync(file, (content && !/\n$/.test(content) ? "\n" : "") + body, "utf8");
@@ -2989,7 +3271,7 @@ targets
   .description("remove monitoring target database")
   .action(async (name: string) => {
     const { instancesFile: file } = await resolveOrInitPaths();
-    if (!fs.existsSync(file)) {
+    if (!fs.existsSync(file) || fs.lstatSync(file).isDirectory()) {
       console.error("instances.yml not found");
       process.exitCode = 1;
       return;
@@ -3026,7 +3308,7 @@ targets
   .description("test monitoring target database connectivity")
   .action(async (name: string) => {
     const { instancesFile: instancesPath } = await resolveOrInitPaths();
-    if (!fs.existsSync(instancesPath)) {
+    if (!fs.existsSync(instancesPath) || fs.lstatSync(instancesPath).isDirectory()) {
       console.error("instances.yml not found");
       process.exitCode = 1;
       return;
@@ -3059,7 +3341,7 @@ targets
       console.log(`Testing connection to monitoring target '${name}'...`);
 
       // Use native pg client instead of requiring psql to be installed
-      const client = new Client({ connectionString: instance.conn_str });
+      const client = new Client({ connectionString: instance.conn_str, connectionTimeoutMillis: 10000 });
 
       try {
         await client.connect();
@@ -3124,8 +3406,8 @@ auth
     const { apiBaseUrl, uiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
 
     if (opts.debug) {
-      console.log(`Debug: Resolved API base URL: ${apiBaseUrl}`);
-      console.log(`Debug: Resolved UI base URL: ${uiBaseUrl}`);
+      console.error(`Debug: Resolved API base URL: ${apiBaseUrl}`);
+      console.error(`Debug: Resolved UI base URL: ${uiBaseUrl}`);
     }
 
     try {
@@ -3155,8 +3437,8 @@ auth
       const initUrl = new URL(`${apiBaseUrl}/rpc/oauth_init`);
 
       if (opts.debug) {
-        console.log(`Debug: Trying to POST to: ${initUrl.toString()}`);
-        console.log(`Debug: Request data: ${initData}`);
+        console.error(`Debug: Trying to POST to: ${initUrl.toString()}`);
+        console.error(`Debug: Request data: ${initData}`);
       }
 
       // Step 2: Initialize OAuth session on backend using fetch
@@ -3202,7 +3484,7 @@ auth
       const authUrl = `${uiBaseUrl}/cli/auth?state=${encodeURIComponent(params.state)}&code_challenge=${encodeURIComponent(params.codeChallenge)}&code_challenge_method=S256&redirect_uri=${encodeURIComponent(redirectUri)}&api_url=${encodeURIComponent(apiBaseUrl)}`;
 
       if (opts.debug) {
-        console.log(`Debug: Auth URL: ${authUrl}`);
+        console.error(`Debug: Auth URL: ${authUrl}`);
       }
 
       console.log(`\nOpening browser for authentication...`);
@@ -3412,10 +3694,10 @@ mon
 
     try {
       // Generate secure password using openssl
-      const { stdout: password } = await execPromise(
-        "openssl rand -base64 12 | tr -d '\n'"
+      const { stdout: password } = await execFilePromise(
+        "openssl", ["rand", "-base64", "12"]
       );
-      const newPassword = password.trim();
+      const newPassword = password.trim().replace(/\n/g, "");
 
       if (!newPassword) {
         console.error("Failed to generate password");
@@ -3493,6 +3775,19 @@ mon
     console.log("  URL:      http://localhost:3000");
     console.log("  Username: monitor");
     console.log(`  Password: ${password}`);
+
+    // Show VM auth credentials from .env
+    const envFile = path.resolve(projectDir, ".env");
+    if (fs.existsSync(envFile)) {
+      const envContent = fs.readFileSync(envFile, "utf8");
+      const vmUser = envContent.match(/^VM_AUTH_USERNAME=([^\r\n]+)/m);
+      const vmPass = envContent.match(/^VM_AUTH_PASSWORD=([^\r\n]+)/m);
+      if (vmUser && vmPass) {
+        console.log("\nVictoriaMetrics credentials:");
+        console.log(`  Username: ${stripMatchingQuotes(vmUser[1])}`);
+        console.log(`  Password: ${stripMatchingQuotes(vmPass[1])}`);
+      }
+    }
     console.log("");
   });
 
@@ -3626,12 +3921,12 @@ issues
     // Interpret escape sequences in content (e.g., \n -> newline)
     if (opts.debug) {
       // eslint-disable-next-line no-console
-      console.log(`Debug: Original content: ${JSON.stringify(content)}`);
+      console.error(`Debug: Original content: ${JSON.stringify(content)}`);
     }
     content = interpretEscapes(content);
     if (opts.debug) {
       // eslint-disable-next-line no-console
-      console.log(`Debug: Interpreted content: ${JSON.stringify(content)}`);
+      console.error(`Debug: Interpreted content: ${JSON.stringify(content)}`);
     }
 
     const spinner = createTtySpinner(process.stdout.isTTY ?? false, "Posting comment...");
@@ -3825,12 +4120,12 @@ issues
   .action(async (commentId: string, content: string, opts: { debug?: boolean; json?: boolean }) => {
     if (opts.debug) {
       // eslint-disable-next-line no-console
-      console.log(`Debug: Original content: ${JSON.stringify(content)}`);
+      console.error(`Debug: Original content: ${JSON.stringify(content)}`);
     }
     content = interpretEscapes(content);
     if (opts.debug) {
       // eslint-disable-next-line no-console
-      console.log(`Debug: Interpreted content: ${JSON.stringify(content)}`);
+      console.error(`Debug: Interpreted content: ${JSON.stringify(content)}`);
     }
 
     const rootOpts = program.opts<CliOptions>();
@@ -3863,6 +4158,93 @@ issues
     }
   });
 
+// File upload/download (subcommands of issues)
+const issueFiles = issues.command("files").description("upload and download files for issues");
+
+issueFiles
+  .command("upload <path>")
+  .description("upload a file to storage and get a markdown link")
+  .option("--debug", "enable debug output")
+  .option("--json", "output raw JSON")
+  .action(async (filePath: string, opts: { debug?: boolean; json?: boolean }) => {
+    const spinner = createTtySpinner(process.stdout.isTTY ?? false, "Uploading file...");
+    try {
+      const rootOpts = program.opts<CliOptions>();
+      const cfg = config.readConfig();
+      const { apiKey } = getConfig(rootOpts);
+      if (!apiKey) {
+        spinner.stop();
+        console.error("API key is required. Run 'pgai auth' first or set --api-key.");
+        process.exitCode = 1;
+        return;
+      }
+
+      const { storageBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+
+      const result = await uploadFile({
+        apiKey,
+        storageBaseUrl,
+        filePath,
+        debug: !!opts.debug,
+      });
+      spinner.stop();
+
+      if (opts.json) {
+        printResult(result, true);
+      } else {
+        const md = buildMarkdownLink(result.url, storageBaseUrl, result.metadata.originalName);
+        const displayUrl = result.url.startsWith("/") ? `${storageBaseUrl}${result.url}` : `${storageBaseUrl}/${result.url}`;
+        console.log(`URL: ${displayUrl}`);
+        console.log(`File: ${result.metadata.originalName}`);
+        console.log(`Size: ${result.metadata.size} bytes`);
+        console.log(`Type: ${result.metadata.mimeType}`);
+        console.log(`Markdown: ${md}`);
+      }
+    } catch (err) {
+      spinner.stop();
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(message);
+      process.exitCode = 1;
+    }
+  });
+
+issueFiles
+  .command("download <url>")
+  .description("download a file from storage")
+  .option("-o, --output <path>", "output file path (default: derive from URL)")
+  .option("--debug", "enable debug output")
+  .action(async (fileUrl: string, opts: { output?: string; debug?: boolean }) => {
+    const spinner = createTtySpinner(process.stdout.isTTY ?? false, "Downloading file...");
+    try {
+      const rootOpts = program.opts<CliOptions>();
+      const cfg = config.readConfig();
+      const { apiKey } = getConfig(rootOpts);
+      if (!apiKey) {
+        spinner.stop();
+        console.error("API key is required. Run 'pgai auth' first or set --api-key.");
+        process.exitCode = 1;
+        return;
+      }
+
+      const { storageBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+
+      const result = await downloadFile({
+        apiKey,
+        storageBaseUrl,
+        fileUrl,
+        outputPath: opts.output,
+        debug: !!opts.debug,
+      });
+      spinner.stop();
+      console.log(`Saved: ${result.savedTo}`);
+    } catch (err) {
+      spinner.stop();
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(message);
+      process.exitCode = 1;
+    }
+  });
+
 // Action Items management (subcommands of issues)
 issues
   .command("action-items <issueId>")
@@ -4087,6 +4469,228 @@ issues
     }
   });
 
+// Reports management
+const reports = program.command("reports").description("checkup reports management");
+
+reports
+  .command("list")
+  .description("list checkup reports")
+  .option("--project-id <id>", "filter by project id", (v: string) => parseInt(v, 10))
+  .addOption(new Option("--status <status>", "filter by status (e.g., completed)").hideHelp())
+  .option("--limit <n>", "max number of reports to return (default: 20, max: 100)", (v: string) => { const n = parseInt(v, 10); return Number.isNaN(n) ? 20 : Math.max(1, Math.min(n, 100)); })
+  .option("--before <date>", "show reports created before this date (YYYY-MM-DD, DD.MM.YYYY, etc.)")
+  .option("--all", "fetch all reports (paginated automatically)")
+  .addOption(new Option("--debug", "enable debug output").hideHelp())
+  .option("--json", "output raw JSON")
+  .action(async (opts: { projectId?: number; status?: string; limit?: number; before?: string; all?: boolean; debug?: boolean; json?: boolean }) => {
+    const spinner = createTtySpinner(process.stdout.isTTY ?? false, "Fetching reports...");
+    try {
+      const rootOpts = program.opts<CliOptions>();
+      const cfg = config.readConfig();
+      const { apiKey } = getConfig(rootOpts);
+      if (!apiKey) {
+        spinner.stop();
+        console.error("API key is required. Run 'pgai auth' first or set --api-key.");
+        process.exitCode = 1;
+        return;
+      }
+      if (opts.all && opts.before) {
+        spinner.stop();
+        console.error("--all and --before cannot be used together");
+        process.exitCode = 1;
+        return;
+      }
+      const { apiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+
+      let result;
+      if (opts.all) {
+        result = await fetchAllReports({
+          apiKey,
+          apiBaseUrl,
+          projectId: opts.projectId,
+          status: opts.status,
+          limit: opts.limit,
+          debug: !!opts.debug,
+        });
+      } else {
+        result = await fetchReports({
+          apiKey,
+          apiBaseUrl,
+          projectId: opts.projectId,
+          status: opts.status,
+          limit: opts.limit,
+          beforeDate: opts.before ? parseFlexibleDate(opts.before) : undefined,
+          debug: !!opts.debug,
+        });
+      }
+      spinner.stop();
+      printResult(result, opts.json);
+    } catch (err) {
+      spinner.stop();
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(message);
+      process.exitCode = 1;
+    }
+  });
+
+reports
+  .command("files [reportId]")
+  .description("list files of a checkup report (metadata only, no content)")
+  .option("--type <type>", "filter by file type: json, md")
+  .option("--check-id <id>", "filter by check ID (e.g., H002)")
+  .addOption(new Option("--debug", "enable debug output").hideHelp())
+  .option("--json", "output raw JSON")
+  .action(async (reportId: string | undefined, opts: { type?: "json" | "md"; checkId?: string; debug?: boolean; json?: boolean }) => {
+    const spinner = createTtySpinner(process.stdout.isTTY ?? false, "Fetching report files...");
+    try {
+      const rootOpts = program.opts<CliOptions>();
+      const cfg = config.readConfig();
+      const { apiKey } = getConfig(rootOpts);
+      if (!apiKey) {
+        spinner.stop();
+        console.error("API key is required. Run 'pgai auth' first or set --api-key.");
+        process.exitCode = 1;
+        return;
+      }
+      let numericId: number | undefined;
+      if (reportId !== undefined) {
+        numericId = parseInt(reportId, 10);
+        if (isNaN(numericId)) {
+          spinner.stop();
+          console.error("reportId must be a number");
+          process.exitCode = 1;
+          return;
+        }
+      }
+      if (numericId === undefined && !opts.checkId) {
+        spinner.stop();
+        console.error("Either reportId or --check-id is required");
+        process.exitCode = 1;
+        return;
+      }
+      const { apiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+
+      const result = await fetchReportFiles({
+        apiKey,
+        apiBaseUrl,
+        reportId: numericId,
+        type: opts.type,
+        checkId: opts.checkId,
+        debug: !!opts.debug,
+      });
+      spinner.stop();
+      printResult(result, opts.json);
+    } catch (err) {
+      spinner.stop();
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(message);
+      process.exitCode = 1;
+    }
+  });
+
+reports
+  .command("data [reportId]")
+  .description("get checkup report file data (includes content)")
+  .option("--type <type>", "filter by file type: json, md")
+  .option("--check-id <id>", "filter by check ID (e.g., H002)")
+  .option("--formatted", "render markdown with ANSI styling (experimental)")
+  .option("-o, --output <dir>", "save files to directory (uses original filenames)")
+  .addOption(new Option("--debug", "enable debug output").hideHelp())
+  .option("--json", "output raw JSON")
+  .action(async (reportId: string | undefined, opts: { type?: "json" | "md"; checkId?: string; formatted?: boolean; output?: string; debug?: boolean; json?: boolean }) => {
+    const spinner = createTtySpinner(process.stdout.isTTY ?? false, "Fetching report data...");
+    try {
+      const rootOpts = program.opts<CliOptions>();
+      const cfg = config.readConfig();
+      const { apiKey } = getConfig(rootOpts);
+      if (!apiKey) {
+        spinner.stop();
+        console.error("API key is required. Run 'pgai auth' first or set --api-key.");
+        process.exitCode = 1;
+        return;
+      }
+      let numericId: number | undefined;
+      if (reportId !== undefined) {
+        numericId = parseInt(reportId, 10);
+        if (isNaN(numericId)) {
+          spinner.stop();
+          console.error("reportId must be a number");
+          process.exitCode = 1;
+          return;
+        }
+      }
+      if (numericId === undefined && !opts.checkId) {
+        spinner.stop();
+        console.error("Either reportId or --check-id is required");
+        process.exitCode = 1;
+        return;
+      }
+      const { apiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+
+      // Default to "md" for terminal output (human-readable); --json and --output get all types
+      const effectiveType = opts.type ?? (!opts.json && !opts.output ? "md" as const : undefined);
+      const result = await fetchReportFileData({
+        apiKey,
+        apiBaseUrl,
+        reportId: numericId,
+        type: effectiveType,
+        checkId: opts.checkId,
+        debug: !!opts.debug,
+      });
+      spinner.stop();
+
+      if (opts.output) {
+        const dir = path.resolve(opts.output);
+        fs.mkdirSync(dir, { recursive: true });
+        for (const f of result) {
+          const safeName = path.basename(f.filename);
+          const filePath = path.join(dir, safeName);
+          const content = f.type === "json"
+            ? JSON.stringify(tryParseJson(f.data), null, 2)
+            : f.data;
+          fs.writeFileSync(filePath, content, "utf-8");
+          console.log(filePath);
+        }
+      } else if (opts.json) {
+        const processed = result.map((f) => ({
+          ...f,
+          data: f.type === "json" ? tryParseJson(f.data) : f.data,
+        }));
+        printResult(processed, true);
+      } else if (opts.formatted && process.stdout.isTTY) {
+        for (const f of result) {
+          if (result.length > 1) {
+            console.log(`\x1b[1m--- ${f.filename} (${f.check_id}, ${f.type}) ---\x1b[0m`);
+          }
+          if (f.type === "md") {
+            console.log(renderMarkdownForTerminal(f.data));
+          } else if (f.type === "json") {
+            const parsed = tryParseJson(f.data);
+            console.log(typeof parsed === "string" ? parsed : JSON.stringify(parsed, null, 2));
+          } else {
+            console.log(f.data);
+          }
+        }
+      } else {
+        for (const f of result) {
+          if (result.length > 1) {
+            console.log(`--- ${f.filename} (${f.check_id}, ${f.type}) ---`);
+          }
+          console.log(f.data);
+        }
+      }
+    } catch (err) {
+      spinner.stop();
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(message);
+      process.exitCode = 1;
+    }
+  });
+
+function tryParseJson(s: string): unknown {
+  try { return JSON.parse(s); } catch { return s; }
+}
+
 // MCP server
 const mcp = program.command("mcp").description("MCP server integration");
 
@@ -4144,7 +4748,7 @@ mcp
       // Get the path to the current pgai executable
       let pgaiPath: string;
       try {
-        const execPath = await execPromise("which pgai");
+        const execPath = await execFilePromise("which", ["pgai"]);
         pgaiPath = execPath.stdout.trim();
       } catch {
         // Fallback to just "pgai" if which fails
@@ -4156,8 +4760,8 @@ mcp
         console.log("Installing PostgresAI MCP server for Claude Code...");
 
         try {
-          const { stdout, stderr } = await execPromise(
-            `claude mcp add -s user postgresai ${pgaiPath} mcp start`
+          const { stdout, stderr } = await execFilePromise(
+            "claude", ["mcp", "add", "-s", "user", "postgresai", pgaiPath, "mcp", "start"]
           );
 
           if (stdout) console.log(stdout);