postgresai 0.15.0-dev.3 → 0.15.0-dev.5

package/bin/postgres-ai.ts

@@ -13,6 +13,7 @@ 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 { uploadFile, downloadFile, buildMarkdownLink } from "../lib/storage";
 import { applyInitPlan, applyUninitPlan, buildInitPlan, buildUninitPlan, connectWithSslFallback, DEFAULT_MONITORING_USER, 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";
@@ -412,6 +413,7 @@ interface CliOptions {
   apiKey?: string;
   apiBaseUrl?: string;
   uiBaseUrl?: string;
+  storageBaseUrl?: string;
 }
 
 /**
@@ -475,14 +477,14 @@ async function ensureDefaultMonitoringProject(): Promise<PathResolution> {
     fs.mkdirSync(projectDir, { recursive: true, mode: 0o700 });
   }
 
-  if (!fs.existsSync(composeFile)) {
-    const refs = [
-      process.env.PGAI_PROJECT_REF,
-      pkg.version,
-      `v${pkg.version}`,
-      "main",
-    ].filter((v): v is string => Boolean(v && v.trim()));
+  const refs = [
+    process.env.PGAI_PROJECT_REF,
+    pkg.version,
+    `v${pkg.version}`,
+    "main",
+  ].filter((v): v is string => Boolean(v && v.trim()));
 
+  if (!fs.existsSync(composeFile)) {
     let lastErr: unknown;
     for (const ref of refs) {
       const url = `https://gitlab.com/postgres-ai/postgres_ai/-/raw/${encodeURIComponent(ref)}/docker-compose.yml`;
@@ -501,6 +503,21 @@ async function ensureDefaultMonitoringProject(): Promise<PathResolution> {
     }
   }
 
+  // Download instances.demo.yml (demo target template) if not present
+  const demoFile = path.resolve(projectDir, "instances.demo.yml");
+  if (!fs.existsSync(demoFile)) {
+    for (const ref of refs) {
+      const url = `https://gitlab.com/postgres-ai/postgres_ai/-/raw/${encodeURIComponent(ref)}/instances.demo.yml`;
+      try {
+        const text = await downloadText(url);
+        fs.writeFileSync(demoFile, text, { encoding: "utf8", mode: 0o600 });
+        break;
+      } catch {
+        // non-fatal — demo file is optional
+      }
+    }
+  }
+
   // Ensure instances.yml exists as a FILE (avoid Docker creating a directory)
   if (!fs.existsSync(instancesFile)) {
     const header =
@@ -580,6 +597,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
@@ -596,6 +617,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)")
@@ -841,8 +883,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;
@@ -973,8 +1015,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`);
@@ -1155,8 +1197,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;
@@ -1283,8 +1325,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) {
@@ -1600,11 +1642,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;
         }
@@ -2044,13 +2086,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;
 }
 
@@ -2089,9 +2134,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
@@ -2109,18 +2154,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}`);
       }
     });
 }
@@ -2208,6 +2253,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 = m[1].trim().replace(/^["']|["']$/g, '');
+      }
+      if (!env.VM_AUTH_PASSWORD) {
+        const m = envContent.match(/^VM_AUTH_PASSWORD=([^\r\n]+)/m);
+        if (m) env.VM_AUTH_PASSWORD = m[1].trim().replace(/^["']|["']$/g, '');
+      }
+    } 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")) {
@@ -2300,8 +2365,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;
     }
 
@@ -2317,7 +2382,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;
     }
@@ -2336,7 +2401,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): ");
@@ -2356,16 +2421,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");
         }
       }
@@ -2425,7 +2490,7 @@ mon
       } 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");
@@ -2443,7 +2508,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];
@@ -2468,14 +2533,23 @@ mon
               }
             }
           } 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: copy instances.demo.yml → instances.yml so the demo target is active
+      console.log("Step 2: Demo mode enabled - using included demo PostgreSQL database");
+      const { instancesFile: instancesPath, projectDir } = await resolveOrInitPaths();
+      const demoSrc = path.resolve(projectDir, "instances.demo.yml");
+      if (fs.existsSync(demoSrc)) {
+        fs.copyFileSync(demoSrc, instancesPath);
+        console.log("✓ Demo monitoring target configured\n");
+      } else {
+        console.error("⚠ instances.demo.yml not found — demo target not configured\n");
+      }
     }
 
     // Step 3: Update configuration
@@ -2491,6 +2565,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)) {
@@ -2524,12 +2600,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 = userMatch[1].trim().replace(/^["']|["']$/g, '');
+        if (passMatch) vmAuthPassword = passMatch[1].trim().replace(/^["']|["']$/g, '');
+      }
+
+      if (!vmAuthUsername || !vmAuthPassword) {
+        console.log("Generating VictoriaMetrics auth credentials...");
+        vmAuthUsername = vmAuthUsername || "vmauth";
+        if (!vmAuthPassword) {
+          const { stdout: vmPass } = await execPromise("openssl rand -base64 12 | tr -d '\n'");
+          vmAuthPassword = vmPass.trim();
+        }
+
+        // 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) {
@@ -2579,6 +2701,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");
   });
 
@@ -2916,7 +3041,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
@@ -3229,8 +3354,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 {
@@ -3260,8 +3385,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
@@ -3307,7 +3432,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...`);
@@ -3598,6 +3723,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: ${vmUser[1].trim().replace(/^["']|["']$/g, '')}`);
+        console.log(`  Password: ${vmPass[1].trim().replace(/^["']|["']$/g, '')}`);
+      }
+    }
     console.log("");
   });
 
@@ -3731,12 +3869,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...");
@@ -3930,12 +4068,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>();
@@ -3968,6 +4106,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>")