postgresai 0.15.0-dev.1 → 0.15.0-dev.11

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, uploadAttachments, appendAttachmentsToContent } 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";
@@ -23,6 +26,17 @@ import { REPORT_GENERATORS, CHECK_INFO, generateAllReports } from "../lib/checku
 import { getCheckupEntry } from "../lib/checkup-dictionary";
 import { createCheckupReport, uploadCheckupReportJson, convertCheckupReportJsonToMarkdown, RpcError, formatRpcErrorForDisplay, withRetry } from "../lib/checkup-api";
 import { generateCheckSummary } from "../lib/checkup-summary";
+import {
+  type Instance,
+  InstancesParseError,
+  loadInstances,
+  buildInstance,
+  addInstanceToFile,
+  removeInstanceFromFile,
+  buildClientConfig,
+  sslOptionFromConnString,
+  warnIfLaxSslmode,
+} from "../lib/instances";
 
 // Node.js version check - require Node 18+
 // Node 14 reached EOL in April 2023, Node 16 in September 2023.
@@ -51,21 +65,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) => {
@@ -342,7 +351,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}`);
   }
 }
 
@@ -410,6 +420,7 @@ interface CliOptions {
   apiKey?: string;
   apiBaseUrl?: string;
   uiBaseUrl?: string;
+  storageBaseUrl?: string;
 }
 
 /**
@@ -419,19 +430,6 @@ interface ConfigResult {
   apiKey: string;
 }
 
-/**
- * Instance configuration
- */
-interface Instance {
-  name: string;
-  conn_str?: string;
-  preset_metrics?: string;
-  custom_metrics?: any;
-  is_enabled?: boolean;
-  group?: string;
-  custom_tags?: Record<string, any>;
-}
-
 /**
  * Path resolution result
  */
@@ -499,7 +497,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" +
@@ -578,6 +580,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
@@ -594,6 +600,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)")
@@ -839,8 +866,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;
@@ -971,8 +998,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`);
@@ -1153,8 +1180,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;
@@ -1281,8 +1308,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) {
@@ -1598,11 +1625,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;
         }
@@ -1797,6 +1824,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") {
@@ -1924,8 +1969,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));
       }
 
@@ -2042,13 +2087,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;
 }
 
@@ -2087,9 +2135,9 @@ function registerMonitoringInstance(
   const debug = opts?.debug;
 
   if (debug) {
-    console.log(`\nDebug: Registering monitoring instance...`);
-    console.log(`Debug: POST ${url}`);
-    console.log(`Debug: project_name=${projectName}`);
+    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
@@ -2107,18 +2155,18 @@ function registerMonitoringInstance(
       const body = await res.text().catch(() => "");
       if (!res.ok) {
         if (debug) {
-          console.log(`Debug: Monitoring registration failed: HTTP ${res.status}`);
-          console.log(`Debug: Response: ${body}`);
+          console.error(`Debug: Monitoring registration failed: HTTP ${res.status}`);
+          console.error(`Debug: Response: ${body}`);
         }
         return;
       }
       if (debug) {
-        console.log(`Debug: Monitoring registration response: ${body}`);
+        console.error(`Debug: Monitoring registration response: ${body}`);
       }
     })
     .catch((err) => {
       if (debug) {
-        console.log(`Debug: Monitoring registration error: ${err.message}`);
+        console.error(`Debug: Monitoring registration error: ${err.message}`);
       }
     });
 }
@@ -2206,6 +2254,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")) {
@@ -2232,6 +2300,18 @@ const mon = program.command("mon").description("monitoring services management")
 mon
   .command("local-install")
   .description("install local monitoring stack (generate config, start services)")
+  .addHelpText(
+    "after",
+    [
+      "",
+      "Networking:",
+      "  Compose enables IPv6 on the project's default network so containers can",
+      "  reach IPv6-only databases (e.g. Supabase free-tier db.<ref>.supabase.co).",
+      "  Override on hosts whose Docker daemon cannot create an IPv6 network:",
+      "      PGAI_ENABLE_IPV6=false   (accepted: true|false|yes|no, lowercase)",
+      "",
+    ].join("\n"),
+  )
   .option("--demo", "demo mode with sample database", false)
   .option("--api-key <key>", "Postgres AI API key for automated report uploads")
   .option("--db-url <url>", "PostgreSQL connection URL to monitor")
@@ -2250,7 +2330,7 @@ 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)
@@ -2263,10 +2343,13 @@ mon
     // 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");
@@ -2275,6 +2358,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
@@ -2290,6 +2379,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) {
@@ -2298,8 +2392,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;
     }
 
@@ -2315,7 +2409,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;
     }
@@ -2334,7 +2428,7 @@ mon
       } 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): ");
@@ -2354,16 +2448,16 @@ mon
               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");
         }
       }
@@ -2403,27 +2497,31 @@ mon
         const db = m[5];
         const instanceName = `${host}-${db}`.replace(/[^a-zA-Z0-9-]/g, "-");
 
-        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`;
-        fs.appendFileSync(instancesPath, body, "utf8");
+        addInstanceToFile(instancesPath, buildInstance(instanceName, connStr));
         console.log(`✓ Monitoring target '${instanceName}' added\n`);
 
         // 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 {
+            warnIfLaxSslmode(connStr);
+            testClient = new Client(buildClientConfig(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");
@@ -2441,39 +2539,74 @@ 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];
               const instanceName = `${host}-${db}`.replace(/[^a-zA-Z0-9-]/g, "-");
 
-              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`;
-              fs.appendFileSync(instancesPath, body, "utf8");
+              addInstanceToFile(instancesPath, buildInstance(instanceName, connStr));
               console.log(`✓ Monitoring target '${instanceName}' added\n`);
 
               // 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 {
+                  warnIfLaxSslmode(connStr);
+            testClient = new Client(buildClientConfig(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
@@ -2489,6 +2622,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)) {
@@ -2504,8 +2639,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)) {
@@ -2522,12 +2657,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) {
@@ -2577,6 +2758,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");
   });
 
@@ -2777,7 +2961,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);
@@ -2808,16 +2992,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
@@ -2914,7 +3098,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
@@ -2993,48 +3177,38 @@ 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;
     }
 
+    let instances: Instance[];
     try {
-      const content = fs.readFileSync(instancesPath, "utf8");
-      const instances = yaml.load(content) as Instance[] | null;
-
-      if (!instances || !Array.isArray(instances) || instances.length === 0) {
-        console.log("No monitoring targets configured");
-        console.log("");
-        console.log("To add a monitoring target:");
-        console.log("  postgres-ai mon targets add <connection-string> <name>");
-        console.log("");
-        console.log("Example:");
-        console.log("  postgres-ai mon targets add 'postgresql://user:pass@host:5432/db' my-db");
-        return;
-      }
-
-      // Filter out disabled instances (e.g., demo placeholders)
-      const filtered = instances.filter((inst) => inst.name && inst.is_enabled !== false);
-
-      if (filtered.length === 0) {
-        console.log("No monitoring targets configured");
-        console.log("");
-        console.log("To add a monitoring target:");
-        console.log("  postgres-ai mon targets add <connection-string> <name>");
-        console.log("");
-        console.log("Example:");
-        console.log("  postgres-ai mon targets add 'postgresql://user:pass@host:5432/db' my-db");
-        return;
-      }
-
-      for (const inst of filtered) {
-        console.log(`Target: ${inst.name}`);
-      }
+      instances = loadInstances(instancesPath);
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       console.error(`Error parsing instances.yml: ${message}`);
       process.exitCode = 1;
+      return;
+    }
+
+    // Filter out disabled instances (e.g., demo placeholders)
+    const filtered = instances.filter((inst) => inst.name && inst.is_enabled !== false);
+
+    if (filtered.length === 0) {
+      console.log("No monitoring targets configured");
+      console.log("");
+      console.log("To add a monitoring target:");
+      console.log("  postgres-ai mon targets add <connection-string> <name>");
+      console.log("");
+      console.log("Example:");
+      console.log("  postgres-ai mon targets add 'postgresql://user:pass@host:5432/db' my-db");
+      return;
+    }
+
+    for (const inst of filtered) {
+      console.log(`Target: ${inst.name}`);
     }
   });
 targets
@@ -3057,66 +3231,36 @@ targets
     const db = m[5];
     const instanceName = name && name.trim() ? name.trim() : `${host}-${db}`.replace(/[^a-zA-Z0-9-]/g, "-");
 
-    // Check if instance already exists
     try {
-      if (fs.existsSync(file)) {
-        const content = fs.readFileSync(file, "utf8");
-        const instances = yaml.load(content) as Instance[] | null || [];
-        if (Array.isArray(instances)) {
-          const exists = instances.some((inst) => inst.name === instanceName);
-          if (exists) {
-            console.error(`Monitoring target '${instanceName}' already exists`);
-            process.exitCode = 1;
-            return;
-          }
-        }
-      }
+      addInstanceToFile(file, buildInstance(instanceName, connStr));
+      console.log(`Monitoring target '${instanceName}' added`);
     } 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)) {
-        console.error(`Monitoring target '${instanceName}' already exists`);
-        process.exitCode = 1;
-        return;
-      }
+      // Surface InstancesParseError as-is so we don't silently overwrite a
+      // corrupted file (which could discard several targets, including the
+      // credentials in their conn_str values).
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(message);
+      process.exitCode = 1;
     }
-
-    // Add new instance
-    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");
-    console.log(`Monitoring target '${instanceName}' added`);
   });
 targets
   .command("remove <name>")
   .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;
     }
 
     try {
-      const content = fs.readFileSync(file, "utf8");
-      const instances = yaml.load(content) as Instance[] | null;
-
-      if (!instances || !Array.isArray(instances)) {
-        console.error("Invalid instances.yml format");
-        process.exitCode = 1;
-        return;
-      }
-
-      const filtered = instances.filter((inst) => inst.name !== name);
-
-      if (filtered.length === instances.length) {
+      const removed = removeInstanceFromFile(file, name);
+      if (!removed) {
         console.error(`Monitoring target '${name}' not found`);
         process.exitCode = 1;
         return;
       }
-
-      fs.writeFileSync(file, yaml.dump(filtered), "utf8");
       console.log(`Monitoring target '${name}' removed`);
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
@@ -3129,41 +3273,41 @@ 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;
     }
 
+    let instances: Instance[];
     try {
-      const content = fs.readFileSync(instancesPath, "utf8");
-      const instances = yaml.load(content) as Instance[] | null;
-
-      if (!instances || !Array.isArray(instances)) {
-        console.error("Invalid instances.yml format");
-        process.exitCode = 1;
-        return;
-      }
-
-      const instance = instances.find((inst) => inst.name === name);
+      instances = loadInstances(instancesPath);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(`Error parsing instances.yml: ${message}`);
+      process.exitCode = 1;
+      return;
+    }
+    const instance = instances.find((inst) => inst.name === name);
 
-      if (!instance) {
-        console.error(`Monitoring target '${name}' not found`);
-        process.exitCode = 1;
-        return;
-      }
+    if (!instance) {
+      console.error(`Monitoring target '${name}' not found`);
+      process.exitCode = 1;
+      return;
+    }
 
-      if (!instance.conn_str) {
-        console.error(`Connection string not found for monitoring target '${name}'`);
-        process.exitCode = 1;
-        return;
-      }
+    if (!instance.conn_str) {
+      console.error(`Connection string not found for monitoring target '${name}'`);
+      process.exitCode = 1;
+      return;
+    }
 
-      console.log(`Testing connection to monitoring target '${name}'...`);
+    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 });
+    warnIfLaxSslmode(instance.conn_str);
+    const client = new Client(buildClientConfig(instance.conn_str, { connectionTimeoutMillis: 10000 }));
 
+    try {
       try {
         await client.connect();
         const result = await client.query('select version();');
@@ -3197,17 +3341,17 @@ auth
         process.exitCode = 1;
         return;
       }
-      
+
       // Read existing config to check for defaultProject before updating
       const existingConfig = config.readConfig();
       const existingProject = existingConfig.defaultProject;
-      
+
       config.writeConfig({ apiKey: trimmedKey });
       // When API key is set directly, only clear orgId (org selection may differ).
       // Preserve defaultProject to avoid orphaning historical reports.
       // If the new key lacks access to the project, upload will fail with a clear error.
       config.deleteConfigKeys(["orgId"]);
-      
+
       console.log(`API key saved to ${config.getConfigPath()}`);
       if (existingProject) {
         console.log(`Note: Your default project "${existingProject}" has been preserved.`);
@@ -3227,8 +3371,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 {
@@ -3258,8 +3402,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
@@ -3305,7 +3449,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...`);
@@ -3391,13 +3535,13 @@ auth
           const existingOrgId = existingConfig.orgId;
           const existingProject = existingConfig.defaultProject;
           const orgChanged = existingOrgId && existingOrgId !== orgId;
-          
+
           config.writeConfig({
             apiKey: apiToken,
             baseUrl: apiBaseUrl,
             orgId: orgId,
           });
-          
+
           // Only clear defaultProject if org actually changed
           if (orgChanged && existingProject) {
             config.deleteConfigKeys(["defaultProject"]);
@@ -3515,10 +3659,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");
@@ -3596,6 +3740,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("");
   });
 
@@ -3723,21 +3880,34 @@ issues
   .command("post-comment <issueId> <content>")
   .description("post a new comment to an issue")
   .option("--parent <uuid>", "parent comment id")
+  .option(
+    "--attach <path>",
+    "attach a file (uploads to storage and appends a markdown link; repeatable)",
+    (value: string, previous: string[]) => {
+      previous.push(value);
+      return previous;
+    },
+    [] as string[]
+  )
   .option("--debug", "enable debug output")
   .option("--json", "output raw JSON")
-  .action(async (issueId: string, content: string, opts: { parent?: string; debug?: boolean; json?: boolean }) => {
+  .action(async (issueId: string, content: string, opts: { parent?: string; attach?: string[]; debug?: boolean; json?: boolean }) => {
     // 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...");
+    const attachPaths = Array.isArray(opts.attach) ? opts.attach : [];
+    const spinner = createTtySpinner(
+      process.stdout.isTTY ?? false,
+      attachPaths.length > 0 ? "Uploading attachments..." : "Posting comment..."
+    );
     try {
       const rootOpts = program.opts<CliOptions>();
       const cfg = config.readConfig();
@@ -3749,13 +3919,25 @@ issues
         return;
       }
 
-      const { apiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+      const { apiBaseUrl, storageBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+
+      let augmentedContent = content;
+      if (attachPaths.length > 0) {
+        const uploaded = await uploadAttachments({
+          apiKey,
+          storageBaseUrl,
+          attachmentPaths: attachPaths,
+          debug: !!opts.debug,
+        });
+        augmentedContent = appendAttachmentsToContent(content, uploaded);
+        spinner.update("Posting comment...");
+      }
 
       const result = await createIssueComment({
         apiKey,
         apiBaseUrl,
         issueId,
-        content,
+        content: augmentedContent,
         parentCommentId: opts.parent,
         debug: !!opts.debug,
       });
@@ -3784,9 +3966,18 @@ issues
     },
     [] as string[]
   )
+  .option(
+    "--attach <path>",
+    "attach a file (uploads to storage and appends a markdown link to the description; repeatable)",
+    (value: string, previous: string[]) => {
+      previous.push(value);
+      return previous;
+    },
+    [] as string[]
+  )
   .option("--debug", "enable debug output")
   .option("--json", "output raw JSON")
-  .action(async (rawTitle: string, opts: { orgId?: number; projectId?: number; description?: string; label?: string[]; debug?: boolean; json?: boolean }) => {
+  .action(async (rawTitle: string, opts: { orgId?: number; projectId?: number; description?: string; label?: string[]; attach?: string[]; debug?: boolean; json?: boolean }) => {
     const rootOpts = program.opts<CliOptions>();
     const cfg = config.readConfig();
     const { apiKey } = getConfig(rootOpts);
@@ -3813,16 +4004,33 @@ issues
     const description = opts.description !== undefined ? interpretEscapes(String(opts.description)) : undefined;
     const labels = Array.isArray(opts.label) && opts.label.length > 0 ? opts.label.map(String) : undefined;
     const projectId = typeof opts.projectId === "number" && !Number.isNaN(opts.projectId) ? opts.projectId : undefined;
+    const attachPaths = Array.isArray(opts.attach) ? opts.attach : [];
 
-    const spinner = createTtySpinner(process.stdout.isTTY ?? false, "Creating issue...");
+    const spinner = createTtySpinner(
+      process.stdout.isTTY ?? false,
+      attachPaths.length > 0 ? "Uploading attachments..." : "Creating issue..."
+    );
     try {
-      const { apiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+      const { apiBaseUrl, storageBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+
+      let augmentedDescription = description;
+      if (attachPaths.length > 0) {
+        const uploaded = await uploadAttachments({
+          apiKey,
+          storageBaseUrl,
+          attachmentPaths: attachPaths,
+          debug: !!opts.debug,
+        });
+        augmentedDescription = appendAttachmentsToContent(description ?? "", uploaded);
+        spinner.update("Creating issue...");
+      }
+
       const result = await createIssue({
         apiKey,
         apiBaseUrl,
         title,
         orgId,
-        description,
+        description: augmentedDescription,
         projectId,
         labels,
         debug: !!opts.debug,
@@ -3853,9 +4061,18 @@ issues
     [] as string[]
   )
   .option("--clear-labels", "set labels to an empty list")
+  .option(
+    "--attach <path>",
+    "attach a file (uploads and appends a markdown link to --description; if --description is omitted the existing description is fetched and appended to; repeatable)",
+    (value: string, previous: string[]) => {
+      previous.push(value);
+      return previous;
+    },
+    [] as string[]
+  )
   .option("--debug", "enable debug output")
   .option("--json", "output raw JSON")
-  .action(async (issueId: string, opts: { title?: string; description?: string; status?: string; label?: string[]; clearLabels?: boolean; debug?: boolean; json?: boolean }) => {
+  .action(async (issueId: string, opts: { title?: string; description?: string; status?: string; label?: string[]; clearLabels?: boolean; attach?: string[]; debug?: boolean; json?: boolean }) => {
     const rootOpts = program.opts<CliOptions>();
     const cfg = config.readConfig();
     const { apiKey } = getConfig(rootOpts);
@@ -3865,10 +4082,10 @@ issues
       return;
     }
 
-    const { apiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+    const { apiBaseUrl, storageBaseUrl } = resolveBaseUrls(rootOpts, cfg);
 
     const title = opts.title !== undefined ? interpretEscapes(String(opts.title)) : undefined;
-    const description = opts.description !== undefined ? interpretEscapes(String(opts.description)) : undefined;
+    let description = opts.description !== undefined ? interpretEscapes(String(opts.description)) : undefined;
 
     let status: number | undefined = undefined;
     if (opts.status !== undefined) {
@@ -3898,8 +4115,38 @@ issues
       labels = opts.label.map(String);
     }
 
-    const spinner = createTtySpinner(process.stdout.isTTY ?? false, "Updating issue...");
+    const attachPaths = Array.isArray(opts.attach) ? opts.attach : [];
+    const spinner = createTtySpinner(
+      process.stdout.isTTY ?? false,
+      attachPaths.length > 0 ? "Uploading attachments..." : "Updating issue..."
+    );
     try {
+      if (attachPaths.length > 0) {
+        // If the caller did not supply a new description, fetch the existing one
+        // and append to it. This makes "add a screenshot to issue X" a one-step
+        // operation rather than forcing the caller to copy-paste the existing
+        // description first. Small race window if someone else updates
+        // concurrently, which is acceptable for an interactive CLI / agent.
+        if (description === undefined) {
+          const existing = await fetchIssue({ apiKey, apiBaseUrl, issueId, debug: !!opts.debug });
+          if (!existing) {
+            spinner.stop();
+            console.error(`Issue not found: ${issueId}`);
+            process.exitCode = 1;
+            return;
+          }
+          description = (existing as { description?: string | null }).description ?? "";
+        }
+        const uploaded = await uploadAttachments({
+          apiKey,
+          storageBaseUrl,
+          attachmentPaths: attachPaths,
+          debug: !!opts.debug,
+        });
+        description = appendAttachmentsToContent(description ?? "", uploaded);
+        spinner.update("Updating issue...");
+      }
+
       const result = await updateIssue({
         apiKey,
         apiBaseUrl,
@@ -3923,17 +4170,26 @@ issues
 issues
   .command("update-comment <commentId> <content>")
   .description("update an existing issue comment")
+  .option(
+    "--attach <path>",
+    "attach a file (uploads and appends a markdown link to <content>; repeatable)",
+    (value: string, previous: string[]) => {
+      previous.push(value);
+      return previous;
+    },
+    [] as string[]
+  )
   .option("--debug", "enable debug output")
   .option("--json", "output raw JSON")
-  .action(async (commentId: string, content: string, opts: { debug?: boolean; json?: boolean }) => {
+  .action(async (commentId: string, content: string, opts: { attach?: string[]; 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>();
@@ -3945,15 +4201,31 @@ issues
       return;
     }
 
-    const spinner = createTtySpinner(process.stdout.isTTY ?? false, "Updating comment...");
+    const attachPaths = Array.isArray(opts.attach) ? opts.attach : [];
+    const spinner = createTtySpinner(
+      process.stdout.isTTY ?? false,
+      attachPaths.length > 0 ? "Uploading attachments..." : "Updating comment..."
+    );
     try {
-      const { apiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+      const { apiBaseUrl, storageBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+
+      let augmentedContent = content;
+      if (attachPaths.length > 0) {
+        const uploaded = await uploadAttachments({
+          apiKey,
+          storageBaseUrl,
+          attachmentPaths: attachPaths,
+          debug: !!opts.debug,
+        });
+        augmentedContent = appendAttachmentsToContent(content, uploaded);
+        spinner.update("Updating comment...");
+      }
 
       const result = await updateIssueComment({
         apiKey,
         apiBaseUrl,
         commentId,
-        content,
+        content: augmentedContent,
         debug: !!opts.debug,
       });
       spinner.stop();
@@ -3966,6 +4238,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>")
@@ -4190,6 +4549,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");
 
@@ -4247,7 +4828,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
@@ -4259,8 +4840,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);
@@ -4355,4 +4936,3 @@ mcp
 program.parseAsync(process.argv).finally(() => {
   closeReadline();
 });
-