postgresai 0.14.0-beta.12 → 0.14.0-beta.14

package/bin/postgres-ai.ts

@@ -10,9 +10,10 @@ import * as os from "os";
 import * as crypto from "node:crypto";
 import { Client } from "pg";
 import { startMcpServer } from "../lib/mcp-server";
-import { fetchIssues, fetchIssueComments, createIssueComment, fetchIssue, createIssue, updateIssue, updateIssueComment } from "../lib/issues";
+import { fetchIssues, fetchIssueComments, createIssueComment, fetchIssue, createIssue, updateIssue, updateIssueComment, fetchActionItem, fetchActionItems, createActionItem, updateActionItem, type ConfigChange } from "../lib/issues";
 import { resolveBaseUrls } from "../lib/util";
-import { applyInitPlan, buildInitPlan, connectWithSslFallback, DEFAULT_MONITORING_USER, redactPasswordsInSql, resolveAdminConnection, resolveMonitoringPassword, verifyInitSetup } from "../lib/init";
+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";
 import * as authServer from "../lib/auth-server";
 import { maskSecret } from "../lib/util";
@@ -564,10 +565,15 @@ program
   .option("--monitoring-user <name>", "Monitoring role name to create/update", DEFAULT_MONITORING_USER)
   .option("--password <password>", "Monitoring role password (overrides PGAI_MON_PASSWORD)")
   .option("--skip-optional-permissions", "Skip optional permissions (RDS/self-managed extras)", false)
+  .option("--provider <provider>", "Database provider (e.g., supabase). Affects which steps are executed.")
   .option("--verify", "Verify that monitoring role/permissions are in place (no changes)", false)
   .option("--reset-password", "Reset monitoring role password only (no other changes)", false)
   .option("--print-sql", "Print SQL plan and exit (no changes applied)", false)
   .option("--print-password", "Print generated monitoring password (DANGEROUS in CI logs)", false)
+  .option("--supabase", "Use Supabase Management API instead of direct PostgreSQL connection", false)
+  .option("--supabase-access-token <token>", "Supabase Management API access token (or SUPABASE_ACCESS_TOKEN env)")
+  .option("--supabase-project-ref <ref>", "Supabase project reference (or SUPABASE_PROJECT_REF env)")
+  .option("--json", "Output result as JSON (machine-readable)", false)
   .addHelpText(
     "after",
     [
@@ -607,6 +613,17 @@ program
       "",
       "Offline SQL plan (no DB connection):",
       "  postgresai prepare-db --print-sql",
+      "",
+      "Supabase mode (use Management API instead of direct connection):",
+      "  postgresai prepare-db --supabase --supabase-project-ref <ref>",
+      "  SUPABASE_ACCESS_TOKEN=... postgresai prepare-db --supabase --supabase-project-ref <ref>",
+      "",
+      "  Generate a token at: https://supabase.com/dashboard/account/tokens",
+      "  Find your project ref in: https://supabase.com/dashboard/project/<ref>",
+      "",
+      "Provider-specific behavior (for direct connections):",
+      "  --provider supabase    Skip role creation (create user in Supabase dashboard)",
+      "                         Skip ALTER USER (restricted by Supabase)",
     ].join("\n")
   )
   .action(async (conn: string | undefined, opts: {
@@ -619,25 +636,63 @@ program
     monitoringUser: string;
     password?: string;
     skipOptionalPermissions?: boolean;
+    provider?: string;
     verify?: boolean;
     resetPassword?: boolean;
     printSql?: boolean;
     printPassword?: boolean;
+    supabase?: boolean;
+    supabaseAccessToken?: string;
+    supabaseProjectRef?: string;
+    json?: boolean;
   }, cmd: Command) => {
-    if (opts.verify && opts.resetPassword) {
-      console.error("✗ Provide only one of --verify or --reset-password");
+    // JSON output helper
+    const jsonOutput = opts.json;
+    const outputJson = (data: Record<string, unknown>) => {
+      console.log(JSON.stringify(data, null, 2));
+    };
+    const outputError = (error: {
+      message: string;
+      step?: string;
+      code?: string;
+      detail?: string;
+      hint?: string;
+      httpStatus?: number;
+    }) => {
+      if (jsonOutput) {
+        outputJson({
+          success: false,
+          mode: opts.supabase ? "supabase" : "direct",
+          error,
+        });
+      } else {
+        console.error(`Error: prepare-db${opts.supabase ? " (Supabase)" : ""}: ${error.message}`);
+        if (error.step) console.error(`  Step: ${error.step}`);
+        if (error.code) console.error(`  Code: ${error.code}`);
+        if (error.detail) console.error(`  Detail: ${error.detail}`);
+        if (error.hint) console.error(`  Hint: ${error.hint}`);
+        if (error.httpStatus) console.error(`  HTTP Status: ${error.httpStatus}`);
+      }
       process.exitCode = 1;
+    };
+    if (opts.verify && opts.resetPassword) {
+      outputError({ message: "Provide only one of --verify or --reset-password" });
       return;
     }
     if (opts.verify && opts.printSql) {
-      console.error("✗ --verify cannot be combined with --print-sql");
-      process.exitCode = 1;
+      outputError({ message: "--verify cannot be combined with --print-sql" });
       return;
     }
 
     const shouldPrintSql = !!opts.printSql;
     const redactPasswords = (sql: string): string => redactPasswordsInSql(sql);
 
+    // Validate provider and warn if unknown
+    const providerWarning = validateProvider(opts.provider);
+    if (providerWarning) {
+      console.warn(`⚠ ${providerWarning}`);
+    }
+
     // Offline mode: allow printing SQL without providing/using an admin connection.
     // Useful for audits/reviews; caller can provide -d/PGDATABASE.
     if (!conn && !opts.dbUrl && !opts.host && !opts.port && !opts.username && !opts.adminPassword) {
@@ -655,11 +710,13 @@ program
           monitoringUser: opts.monitoringUser,
           monitoringPassword: monPassword,
           includeOptionalPermissions,
+          provider: opts.provider,
         });
 
         console.log("\n--- SQL plan (offline; not connected) ---");
         console.log(`-- database: ${database}`);
         console.log(`-- monitoring user: ${opts.monitoringUser}`);
+        console.log(`-- provider: ${opts.provider ?? "self-managed"}`);
         console.log(`-- optional permissions: ${includeOptionalPermissions ? "enabled" : "skipped"}`);
         for (const step of plan.steps) {
           console.log(`\n-- ${step.name}${step.optional ? " (optional)" : ""}`);
@@ -671,6 +728,318 @@ program
       }
     }
 
+    // Supabase mode: use Supabase Management API instead of direct PG connection
+    if (opts.supabase) {
+      let supabaseConfig;
+      try {
+        // Try to extract project ref from connection URL if provided
+        let projectRef = opts.supabaseProjectRef;
+        if (!projectRef && conn) {
+          projectRef = extractProjectRefFromUrl(conn);
+        }
+        supabaseConfig = resolveSupabaseConfig({
+          accessToken: opts.supabaseAccessToken,
+          projectRef,
+        });
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        outputError({ message: msg });
+        return;
+      }
+
+      const includeOptionalPermissions = !opts.skipOptionalPermissions;
+
+      if (!jsonOutput) {
+        console.log(`Supabase mode: project ref ${supabaseConfig.projectRef}`);
+        console.log(`Monitoring user: ${opts.monitoringUser}`);
+        console.log(`Optional permissions: ${includeOptionalPermissions ? "enabled" : "skipped"}`);
+      }
+
+      const supabaseClient = new SupabaseClient(supabaseConfig);
+
+      // Fetch database URL for JSON output (non-blocking, best-effort)
+      let databaseUrl: string | null = null;
+      if (jsonOutput) {
+        databaseUrl = await fetchPoolerDatabaseUrl(supabaseConfig, opts.monitoringUser);
+      }
+
+      try {
+        // Get current database name
+        const database = await supabaseClient.getCurrentDatabase();
+        if (!database) {
+          throw new Error("Failed to resolve current database name");
+        }
+        if (!jsonOutput) {
+          console.log(`Database: ${database}`);
+        }
+
+        if (opts.verify) {
+          const v = await verifyInitSetupViaSupabase({
+            client: supabaseClient,
+            database,
+            monitoringUser: opts.monitoringUser,
+            includeOptionalPermissions,
+          });
+          if (v.ok) {
+            if (jsonOutput) {
+              const result: Record<string, unknown> = {
+                success: true,
+                mode: "supabase",
+                action: "verify",
+                database,
+                monitoringUser: opts.monitoringUser,
+                verified: true,
+                missingOptional: v.missingOptional,
+              };
+              if (databaseUrl) {
+                result.databaseUrl = databaseUrl;
+              }
+              outputJson(result);
+            } 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}`);
+              }
+            }
+            return;
+          }
+          if (jsonOutput) {
+            const result: Record<string, unknown> = {
+              success: false,
+              mode: "supabase",
+              action: "verify",
+              database,
+              monitoringUser: opts.monitoringUser,
+              verified: false,
+              missingRequired: v.missingRequired,
+              missingOptional: v.missingOptional,
+            };
+            if (databaseUrl) {
+              result.databaseUrl = databaseUrl;
+            }
+            outputJson(result);
+          } else {
+            console.error("✗ prepare-db verify failed: missing required items");
+            for (const m of v.missingRequired) console.error(`- ${m}`);
+            if (v.missingOptional.length > 0) {
+              console.error("Optional items missing:");
+              for (const m of v.missingOptional) console.error(`- ${m}`);
+            }
+          }
+          process.exitCode = 1;
+          return;
+        }
+
+        let monPassword: string;
+        let passwordGenerated = false;
+        try {
+          const resolved = await resolveMonitoringPassword({
+            passwordFlag: opts.password,
+            passwordEnv: process.env.PGAI_MON_PASSWORD,
+            monitoringUser: opts.monitoringUser,
+          });
+          monPassword = resolved.password;
+          passwordGenerated = resolved.generated;
+          if (resolved.generated) {
+            const canPrint = process.stdout.isTTY || !!opts.printPassword || jsonOutput;
+            if (canPrint) {
+              if (!jsonOutput) {
+                const shellSafe = monPassword.replace(/'/g, "'\\''");
+                console.error("");
+                console.error(`Generated monitoring password for ${opts.monitoringUser} (copy/paste):`);
+                console.error(`PGAI_MON_PASSWORD='${shellSafe}'`);
+                console.error("");
+                console.log("Store it securely (or rerun with --password / PGAI_MON_PASSWORD to set your own).");
+              }
+              // For JSON mode, password will be included in the success output below
+            } else {
+              console.error(
+                [
+                  `✗ Monitoring password was auto-generated for ${opts.monitoringUser} but not printed in non-interactive mode.`,
+                  "",
+                  "Provide it explicitly:",
+                  "  --password <password>   or   PGAI_MON_PASSWORD=...",
+                  "",
+                  "Or (NOT recommended) print the generated password:",
+                  "  --print-password",
+                ].join("\n")
+              );
+              process.exitCode = 1;
+              return;
+            }
+          }
+        } catch (e) {
+          const msg = e instanceof Error ? e.message : String(e);
+          outputError({ message: msg });
+          return;
+        }
+
+        const plan = await buildInitPlan({
+          database,
+          monitoringUser: opts.monitoringUser,
+          monitoringPassword: monPassword,
+          includeOptionalPermissions,
+        });
+
+        // For Supabase mode, skip RDS and self-managed steps (they don't apply)
+        const supabaseApplicableSteps = plan.steps.filter(
+          (s) => s.name !== "03.optional_rds" && s.name !== "04.optional_self_managed"
+        );
+
+        const effectivePlan = opts.resetPassword
+          ? { ...plan, steps: supabaseApplicableSteps.filter((s) => s.name === "01.role") }
+          : { ...plan, steps: supabaseApplicableSteps };
+
+        if (shouldPrintSql) {
+          console.log("\n--- SQL plan ---");
+          for (const step of effectivePlan.steps) {
+            console.log(`\n-- ${step.name}${step.optional ? " (optional)" : ""}`);
+            console.log(redactPasswords(step.sql));
+          }
+          console.log("\n--- end SQL plan ---\n");
+          console.log("Note: passwords are redacted in the printed SQL output.");
+          return;
+        }
+
+        const { applied, skippedOptional } = await applyInitPlanViaSupabase({
+          client: supabaseClient,
+          plan: effectivePlan,
+        });
+
+        if (jsonOutput) {
+          const result: Record<string, unknown> = {
+            success: true,
+            mode: "supabase",
+            action: opts.resetPassword ? "reset-password" : "apply",
+            database,
+            monitoringUser: opts.monitoringUser,
+            applied,
+            skippedOptional,
+            warnings: skippedOptional.length > 0
+              ? ["Some optional steps were skipped (not supported or insufficient privileges)"]
+              : [],
+          };
+          if (passwordGenerated) {
+            result.generatedPassword = monPassword;
+          }
+          if (databaseUrl) {
+            result.databaseUrl = databaseUrl;
+          }
+          outputJson(result);
+        } 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}`);
+          }
+          if (process.stdout.isTTY) {
+            console.log(`Applied ${applied.length} steps`);
+          }
+        }
+      } catch (error) {
+        const errAny = error as PgCompatibleError;
+        let message = "";
+        if (error instanceof Error && error.message) {
+          message = error.message;
+        } else if (errAny && typeof errAny === "object" && typeof errAny.message === "string" && errAny.message) {
+          message = errAny.message;
+        } else {
+          message = String(error);
+        }
+        if (!message || message === "[object Object]") {
+          message = "Unknown error";
+        }
+
+        // Surface step name if this was a plan step failure
+        const stepMatch = typeof message === "string" ? message.match(/Failed at step "([^"]+)":/i) : null;
+        const failedStep = stepMatch?.[1];
+
+        // Build error object for JSON output
+        const errorObj: {
+          message: string;
+          step?: string;
+          code?: string;
+          detail?: string;
+          hint?: string;
+          httpStatus?: number;
+        } = { message };
+
+        if (failedStep) errorObj.step = failedStep;
+        if (errAny && typeof errAny === "object") {
+          if (typeof errAny.code === "string" && errAny.code) errorObj.code = errAny.code;
+          if (typeof errAny.detail === "string" && errAny.detail) errorObj.detail = errAny.detail;
+          if (typeof errAny.hint === "string" && errAny.hint) errorObj.hint = errAny.hint;
+          if (typeof errAny.httpStatus === "number") errorObj.httpStatus = errAny.httpStatus;
+        }
+
+        if (jsonOutput) {
+          outputJson({
+            success: false,
+            mode: "supabase",
+            error: errorObj,
+          });
+          process.exitCode = 1;
+        } else {
+          console.error(`Error: prepare-db (Supabase): ${message}`);
+
+          if (failedStep) {
+            console.error(`  Step: ${failedStep}`);
+          }
+
+          // Surface PostgreSQL-compatible error details
+          if (errAny && typeof errAny === "object") {
+            if (typeof errAny.code === "string" && errAny.code) {
+              console.error(`  Code: ${errAny.code}`);
+            }
+            if (typeof errAny.detail === "string" && errAny.detail) {
+              console.error(`  Detail: ${errAny.detail}`);
+            }
+            if (typeof errAny.hint === "string" && errAny.hint) {
+              console.error(`  Hint: ${errAny.hint}`);
+            }
+            if (typeof errAny.httpStatus === "number") {
+              console.error(`  HTTP Status: ${errAny.httpStatus}`);
+            }
+          }
+
+          // Provide context hints for common errors
+          if (errAny && typeof errAny === "object" && typeof errAny.code === "string") {
+            if (errAny.code === "42501") {
+              if (failedStep === "01.role") {
+                console.error("  Context: role creation/update requires CREATEROLE or superuser");
+              } else if (failedStep === "03.permissions") {
+                console.error("  Context: grants/view/search_path require sufficient GRANT/DDL privileges");
+              }
+              console.error("  Fix: ensure your Supabase access token has sufficient permissions");
+              console.error("  Tip: run with --print-sql to review the exact SQL plan");
+            }
+            // Schema already exists (42P06) or other duplicate object errors
+            if (errAny.code === "42P06" || (message.includes("already exists") && failedStep === "03.permissions")) {
+              console.error("  Hint: postgres_ai schema or objects already exist from a previous setup.");
+              console.error("  Fix: run 'postgresai unprepare-db <connection>' first to clean up, then retry prepare-db.");
+            }
+          }
+          if (errAny && typeof errAny === "object" && typeof errAny.httpStatus === "number") {
+            if (errAny.httpStatus === 401) {
+              console.error("  Hint: invalid or expired access token; generate a new one at https://supabase.com/dashboard/account/tokens");
+            }
+            if (errAny.httpStatus === 403) {
+              console.error("  Hint: access denied; check your token permissions and project access");
+            }
+            if (errAny.httpStatus === 404) {
+              console.error("  Hint: project not found; verify the project reference is correct");
+            }
+            if (errAny.httpStatus === 429) {
+              console.error("  Hint: rate limited; wait a moment and try again");
+            }
+          }
+          process.exitCode = 1;
+        }
+      }
+      return;
+    }
+
     let adminConn;
     try {
       adminConn = resolveAdminConnection({
@@ -686,21 +1055,27 @@ program
       });
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e);
-      console.error(`Error: prepare-db: ${msg}`);
-      // When connection details are missing, show full init help (options + examples).
-      if (typeof msg === "string" && msg.startsWith("Connection is required.")) {
-        console.error("");
-        cmd.outputHelp({ error: true });
+      if (jsonOutput) {
+        outputError({ message: msg });
+      } else {
+        console.error(`Error: prepare-db: ${msg}`);
+        // When connection details are missing, show full init help (options + examples).
+        if (typeof msg === "string" && msg.startsWith("Connection is required.")) {
+          console.error("");
+          cmd.outputHelp({ error: true });
+        }
+        process.exitCode = 1;
       }
-      process.exitCode = 1;
       return;
     }
 
     const includeOptionalPermissions = !opts.skipOptionalPermissions;
 
-    console.log(`Connecting to: ${adminConn.display}`);
-    console.log(`Monitoring user: ${opts.monitoringUser}`);
-    console.log(`Optional permissions: ${includeOptionalPermissions ? "enabled" : "skipped"}`);
+    if (!jsonOutput) {
+      console.log(`Connecting to: ${adminConn.display}`);
+      console.log(`Monitoring user: ${opts.monitoringUser}`);
+      console.log(`Optional permissions: ${includeOptionalPermissions ? "enabled" : "skipped"}`);
+    }
 
     // Use native pg client instead of requiring psql to be installed
     let client: Client | undefined;
@@ -720,26 +1095,54 @@ program
           database,
           monitoringUser: opts.monitoringUser,
           includeOptionalPermissions,
+          provider: opts.provider,
         });
         if (v.ok) {
-          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}`);
+          if (jsonOutput) {
+            outputJson({
+              success: true,
+              mode: "direct",
+              action: "verify",
+              database,
+              monitoringUser: opts.monitoringUser,
+              provider: opts.provider,
+              verified: true,
+              missingOptional: v.missingOptional,
+            });
+          } 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}`);
+            }
           }
           return;
         }
-        console.error("✗ prepare-db verify failed: missing required items");
-        for (const m of v.missingRequired) console.error(`- ${m}`);
-        if (v.missingOptional.length > 0) {
-          console.error("Optional items missing:");
-          for (const m of v.missingOptional) console.error(`- ${m}`);
+        if (jsonOutput) {
+          outputJson({
+            success: false,
+            mode: "direct",
+            action: "verify",
+            database,
+            monitoringUser: opts.monitoringUser,
+            verified: false,
+            missingRequired: v.missingRequired,
+            missingOptional: v.missingOptional,
+          });
+        } else {
+          console.error("✗ prepare-db verify failed: missing required items");
+          for (const m of v.missingRequired) console.error(`- ${m}`);
+          if (v.missingOptional.length > 0) {
+            console.error("Optional items missing:");
+            for (const m of v.missingOptional) console.error(`- ${m}`);
+          }
         }
         process.exitCode = 1;
         return;
       }
 
       let monPassword: string;
+      let passwordGenerated = false;
       try {
         const resolved = await resolveMonitoringPassword({
           passwordFlag: opts.password,
@@ -747,17 +1150,21 @@ program
           monitoringUser: opts.monitoringUser,
         });
         monPassword = resolved.password;
+        passwordGenerated = resolved.generated;
         if (resolved.generated) {
-          const canPrint = process.stdout.isTTY || !!opts.printPassword;
+          const canPrint = process.stdout.isTTY || !!opts.printPassword || jsonOutput;
           if (canPrint) {
-            // Print secrets to stderr to reduce the chance they end up in piped stdout logs.
-            const shellSafe = monPassword.replace(/'/g, "'\\''");
-            console.error("");
-            console.error(`Generated monitoring password for ${opts.monitoringUser} (copy/paste):`);
-            // Quote for shell copy/paste safety.
-            console.error(`PGAI_MON_PASSWORD='${shellSafe}'`);
-            console.error("");
-            console.log("Store it securely (or rerun with --password / PGAI_MON_PASSWORD to set your own).");
+            if (!jsonOutput) {
+              // Print secrets to stderr to reduce the chance they end up in piped stdout logs.
+              const shellSafe = monPassword.replace(/'/g, "'\\''");
+              console.error("");
+              console.error(`Generated monitoring password for ${opts.monitoringUser} (copy/paste):`);
+              // Quote for shell copy/paste safety.
+              console.error(`PGAI_MON_PASSWORD='${shellSafe}'`);
+              console.error("");
+              console.log("Store it securely (or rerun with --password / PGAI_MON_PASSWORD to set your own).");
+            }
+            // For JSON mode, password will be included in the success output below
           } else {
             console.error(
               [
@@ -776,8 +1183,7 @@ program
         }
       } catch (e) {
         const msg = e instanceof Error ? e.message : String(e);
-        console.error(`✗ ${msg}`);
-        process.exitCode = 1;
+        outputError({ message: msg });
         return;
       }
 
@@ -786,12 +1192,21 @@ program
         monitoringUser: opts.monitoringUser,
         monitoringPassword: monPassword,
         includeOptionalPermissions,
+        provider: opts.provider,
       });
 
+      // For reset-password, we only want the role step. But if provider skips role creation,
+      // reset-password doesn't make sense - warn the user.
       const effectivePlan = opts.resetPassword
         ? { ...plan, steps: plan.steps.filter((s) => s.name === "01.role") }
         : plan;
 
+      if (opts.resetPassword && effectivePlan.steps.length === 0) {
+        console.error(`✗ --reset-password not supported for provider "${opts.provider}" (role creation is skipped)`);
+        process.exitCode = 1;
+        return;
+      }
+
       if (shouldPrintSql) {
         console.log("\n--- SQL plan ---");
         for (const step of effectivePlan.steps) {
@@ -805,14 +1220,33 @@ program
 
       const { applied, skippedOptional } = await applyInitPlan({ client, plan: effectivePlan });
 
-      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}`);
-      }
-      // Keep output compact but still useful
-      if (process.stdout.isTTY) {
-        console.log(`Applied ${applied.length} steps`);
+      if (jsonOutput) {
+        const result: Record<string, unknown> = {
+          success: true,
+          mode: "direct",
+          action: opts.resetPassword ? "reset-password" : "apply",
+          database,
+          monitoringUser: opts.monitoringUser,
+          applied,
+          skippedOptional,
+          warnings: skippedOptional.length > 0
+            ? ["Some optional steps were skipped (not supported or insufficient privileges)"]
+            : [],
+        };
+        if (passwordGenerated) {
+          result.generatedPassword = monPassword;
+        }
+        outputJson(result);
+      } 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}`);
+        }
+        // Keep output compact but still useful
+        if (process.stdout.isTTY) {
+          console.log(`Applied ${applied.length} steps`);
+        }
       }
     } catch (error) {
       const errAny = error as any;
@@ -827,47 +1261,374 @@ program
       if (!message || message === "[object Object]") {
         message = "Unknown error";
       }
-      console.error(`Error: prepare-db: ${message}`);
+
       // If this was a plan step failure, surface the step name explicitly to help users diagnose quickly.
       const stepMatch =
         typeof message === "string" ? message.match(/Failed at step "([^"]+)":/i) : null;
       const failedStep = stepMatch?.[1];
-      if (failedStep) {
-        console.error(`  Step: ${failedStep}`);
-      }
+
+      // Build error object for JSON output
+      const errorObj: {
+        message: string;
+        step?: string;
+        code?: string;
+        detail?: string;
+        hint?: string;
+      } = { message };
+
+      if (failedStep) errorObj.step = failedStep;
       if (errAny && typeof errAny === "object") {
-        if (typeof errAny.code === "string" && errAny.code) {
-          console.error(`  Code: ${errAny.code}`);
+        if (typeof errAny.code === "string" && errAny.code) errorObj.code = errAny.code;
+        if (typeof errAny.detail === "string" && errAny.detail) errorObj.detail = errAny.detail;
+        if (typeof errAny.hint === "string" && errAny.hint) errorObj.hint = errAny.hint;
+      }
+
+      if (jsonOutput) {
+        outputJson({
+          success: false,
+          mode: "direct",
+          error: errorObj,
+        });
+        process.exitCode = 1;
+      } else {
+        console.error(`Error: prepare-db: ${message}`);
+        if (failedStep) {
+          console.error(`  Step: ${failedStep}`);
+        }
+        if (errAny && typeof errAny === "object") {
+          if (typeof errAny.code === "string" && errAny.code) {
+            console.error(`  Code: ${errAny.code}`);
+          }
+          if (typeof errAny.detail === "string" && errAny.detail) {
+            console.error(`  Detail: ${errAny.detail}`);
+          }
+          if (typeof errAny.hint === "string" && errAny.hint) {
+            console.error(`  Hint: ${errAny.hint}`);
+          }
+        }
+        if (errAny && typeof errAny === "object" && typeof errAny.code === "string") {
+          if (errAny.code === "42501") {
+            if (failedStep === "01.role") {
+              console.error("  Context: role creation/update requires CREATEROLE or superuser");
+            } else if (failedStep === "03.permissions") {
+              console.error("  Context: grants/view/search_path require sufficient GRANT/DDL privileges");
+            }
+            console.error("  Fix: connect as a superuser (or a role with CREATEROLE and sufficient GRANT privileges)");
+            console.error("  Fix: on managed Postgres, use the provider's admin/master user");
+            console.error("  Tip: run with --print-sql to review the exact SQL plan");
+          }
+          // Schema already exists (42P06) or other duplicate object errors
+          if (errAny.code === "42P06" || (message.includes("already exists") && failedStep === "03.permissions")) {
+            console.error("  Hint: postgres_ai schema or objects already exist from a previous setup.");
+            console.error("  Fix: run 'postgresai unprepare-db <connection>' first to clean up, then retry prepare-db.");
+          }
+          if (errAny.code === "ECONNREFUSED") {
+            console.error("  Hint: check host/port and ensure Postgres is reachable from this machine");
+          }
+          if (errAny.code === "ENOTFOUND") {
+            console.error("  Hint: DNS resolution failed; double-check the host name");
+          }
+          if (errAny.code === "ETIMEDOUT") {
+            console.error("  Hint: connection timed out; check network/firewall rules");
+          }
+        }
+        process.exitCode = 1;
+      }
+    } finally {
+      if (client) {
+        try {
+          await client.end();
+        } catch {
+          // ignore
+        }
+      }
+    }
+  });
+
+program
+  .command("unprepare-db [conn]")
+  .description("remove monitoring setup: drop monitoring user, views, schema, and revoke permissions")
+  .option("--db-url <url>", "PostgreSQL connection URL (admin) (deprecated; pass it as positional arg)")
+  .option("-h, --host <host>", "PostgreSQL host (psql-like)")
+  .option("-p, --port <port>", "PostgreSQL port (psql-like)")
+  .option("-U, --username <username>", "PostgreSQL user (psql-like)")
+  .option("-d, --dbname <dbname>", "PostgreSQL database name (psql-like)")
+  .option("--admin-password <password>", "Admin connection password (otherwise uses PGPASSWORD if set)")
+  .option("--monitoring-user <name>", "Monitoring role name to remove", DEFAULT_MONITORING_USER)
+  .option("--keep-role", "Keep the monitoring role (only revoke permissions and drop objects)", false)
+  .option("--provider <provider>", "Database provider (e.g., supabase). Affects which steps are executed.")
+  .option("--print-sql", "Print SQL plan and exit (no changes applied)", false)
+  .option("--force", "Skip confirmation prompt", false)
+  .option("--json", "Output result as JSON (machine-readable)", false)
+  .addHelpText(
+    "after",
+    [
+      "",
+      "Examples:",
+      "  postgresai unprepare-db postgresql://admin@host:5432/dbname",
+      "  postgresai unprepare-db \"dbname=dbname host=host user=admin\"",
+      "  postgresai unprepare-db -h host -p 5432 -U admin -d dbname",
+      "",
+      "Admin password:",
+      "  --admin-password <password>   or  PGPASSWORD=... (libpq standard)",
+      "",
+      "Keep role but remove objects/permissions:",
+      "  postgresai unprepare-db <conn> --keep-role",
+      "",
+      "Inspect SQL without applying changes:",
+      "  postgresai unprepare-db <conn> --print-sql",
+      "",
+      "Offline SQL plan (no DB connection):",
+      "  postgresai unprepare-db --print-sql",
+      "",
+      "Skip confirmation prompt:",
+      "  postgresai unprepare-db <conn> --force",
+    ].join("\n")
+  )
+  .action(async (conn: string | undefined, opts: {
+    dbUrl?: string;
+    host?: string;
+    port?: string;
+    username?: string;
+    dbname?: string;
+    adminPassword?: string;
+    monitoringUser: string;
+    keepRole?: boolean;
+    provider?: string;
+    printSql?: boolean;
+    force?: boolean;
+    json?: boolean;
+  }, cmd: Command) => {
+    // JSON output helper
+    const jsonOutput = opts.json;
+    const outputJson = (data: Record<string, unknown>) => {
+      console.log(JSON.stringify(data, null, 2));
+    };
+    const outputError = (error: {
+      message: string;
+      step?: string;
+      code?: string;
+      detail?: string;
+      hint?: string;
+    }) => {
+      if (jsonOutput) {
+        outputJson({
+          success: false,
+          error,
+        });
+      } else {
+        console.error(`Error: unprepare-db: ${error.message}`);
+        if (error.step) console.error(`  Step: ${error.step}`);
+        if (error.code) console.error(`  Code: ${error.code}`);
+        if (error.detail) console.error(`  Detail: ${error.detail}`);
+        if (error.hint) console.error(`  Hint: ${error.hint}`);
+      }
+      process.exitCode = 1;
+    };
+
+    const shouldPrintSql = !!opts.printSql;
+    const dropRole = !opts.keepRole;
+
+    // Validate provider and warn if unknown
+    const providerWarning = validateProvider(opts.provider);
+    if (providerWarning) {
+      console.warn(`⚠ ${providerWarning}`);
+    }
+
+    // Offline mode: allow printing SQL without providing/using an admin connection.
+    if (!conn && !opts.dbUrl && !opts.host && !opts.port && !opts.username && !opts.adminPassword) {
+      if (shouldPrintSql) {
+        const database = (opts.dbname ?? process.env.PGDATABASE ?? "postgres").trim();
+
+        const plan = await buildUninitPlan({
+          database,
+          monitoringUser: opts.monitoringUser,
+          dropRole,
+          provider: opts.provider,
+        });
+
+        console.log("\n--- SQL plan (offline; not connected) ---");
+        console.log(`-- database: ${database}`);
+        console.log(`-- monitoring user: ${opts.monitoringUser}`);
+        console.log(`-- provider: ${opts.provider ?? "self-managed"}`);
+        console.log(`-- drop role: ${dropRole}`);
+        for (const step of plan.steps) {
+          console.log(`\n-- ${step.name}`);
+          console.log(step.sql);
+        }
+        console.log("\n--- end SQL plan ---\n");
+        return;
+      }
+    }
+
+    let adminConn;
+    try {
+      adminConn = resolveAdminConnection({
+        conn,
+        dbUrlFlag: opts.dbUrl,
+        host: opts.host ?? process.env.PGHOST,
+        port: opts.port ?? process.env.PGPORT,
+        username: opts.username ?? process.env.PGUSER,
+        dbname: opts.dbname ?? process.env.PGDATABASE,
+        adminPassword: opts.adminPassword,
+        envPassword: process.env.PGPASSWORD,
+      });
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      if (jsonOutput) {
+        outputError({ message: msg });
+      } else {
+        console.error(`Error: unprepare-db: ${msg}`);
+        if (typeof msg === "string" && msg.startsWith("Connection is required.")) {
+          console.error("");
+          cmd.outputHelp({ error: true });
         }
-        if (typeof errAny.detail === "string" && errAny.detail) {
-          console.error(`  Detail: ${errAny.detail}`);
+        process.exitCode = 1;
+      }
+      return;
+    }
+
+    if (!jsonOutput) {
+      console.log(`Connecting to: ${adminConn.display}`);
+      console.log(`Monitoring user: ${opts.monitoringUser}`);
+      console.log(`Drop role: ${dropRole}`);
+    }
+
+    // Confirmation prompt (unless --force or --json)
+    if (!opts.force && !jsonOutput && !shouldPrintSql) {
+      const answer = await new Promise<string>((resolve) => {
+        const readline = getReadline();
+        readline.question(
+          `This will remove the monitoring setup for user "${opts.monitoringUser}"${dropRole ? " and drop the role" : ""}. Continue? [y/N] `,
+          (ans) => resolve(ans.trim().toLowerCase())
+        );
+      });
+      if (answer !== "y" && answer !== "yes") {
+        console.log("Aborted.");
+        return;
+      }
+    }
+
+    let client: Client | undefined;
+    try {
+      const connResult = await connectWithSslFallback(Client, adminConn);
+      client = connResult.client;
+
+      const dbRes = await client.query("select current_database() as db");
+      const database = dbRes.rows?.[0]?.db;
+      if (typeof database !== "string" || !database) {
+        throw new Error("Failed to resolve current database name");
+      }
+
+      const plan = await buildUninitPlan({
+        database,
+        monitoringUser: opts.monitoringUser,
+        dropRole,
+        provider: opts.provider,
+      });
+
+      if (shouldPrintSql) {
+        console.log("\n--- SQL plan ---");
+        for (const step of plan.steps) {
+          console.log(`\n-- ${step.name}`);
+          console.log(step.sql);
+        }
+        console.log("\n--- end SQL plan ---\n");
+        return;
+      }
+
+      const { applied, errors } = await applyUninitPlan({ client, plan });
+
+      if (jsonOutput) {
+        outputJson({
+          success: errors.length === 0,
+          action: "unprepare",
+          database,
+          monitoringUser: opts.monitoringUser,
+          dropRole,
+          applied,
+          errors,
+        });
+        if (errors.length > 0) {
+          process.exitCode = 1;
         }
-        if (typeof errAny.hint === "string" && errAny.hint) {
-          console.error(`  Hint: ${errAny.hint}`);
+      } else {
+        if (errors.length === 0) {
+          console.log("✓ unprepare-db completed");
+          console.log(`Applied ${applied.length} steps`);
+        } else {
+          console.log("⚠ unprepare-db completed with errors");
+          console.log(`Applied ${applied.length} steps`);
+          console.log("Errors:");
+          for (const err of errors) {
+            console.log(`  - ${err}`);
+          }
+          process.exitCode = 1;
         }
       }
-      if (errAny && typeof errAny === "object" && typeof errAny.code === "string") {
-        if (errAny.code === "42501") {
-          if (failedStep === "01.role") {
-            console.error("  Context: role creation/update requires CREATEROLE or superuser");
-          } else if (failedStep === "02.permissions") {
-            console.error("  Context: grants/view/search_path require sufficient GRANT/DDL privileges");
+    } catch (error) {
+      const errAny = error as any;
+      let message = "";
+      if (error instanceof Error && error.message) {
+        message = error.message;
+      } else if (errAny && typeof errAny === "object" && typeof errAny.message === "string" && errAny.message) {
+        message = errAny.message;
+      } else {
+        message = String(error);
+      }
+      if (!message || message === "[object Object]") {
+        message = "Unknown error";
+      }
+
+      const errorObj: {
+        message: string;
+        code?: string;
+        detail?: string;
+        hint?: string;
+      } = { message };
+
+      if (errAny && typeof errAny === "object") {
+        if (typeof errAny.code === "string" && errAny.code) errorObj.code = errAny.code;
+        if (typeof errAny.detail === "string" && errAny.detail) errorObj.detail = errAny.detail;
+        if (typeof errAny.hint === "string" && errAny.hint) errorObj.hint = errAny.hint;
+      }
+
+      if (jsonOutput) {
+        outputJson({
+          success: false,
+          error: errorObj,
+        });
+        process.exitCode = 1;
+      } else {
+        console.error(`Error: unprepare-db: ${message}`);
+        if (errAny && typeof errAny === "object") {
+          if (typeof errAny.code === "string" && errAny.code) {
+            console.error(`  Code: ${errAny.code}`);
+          }
+          if (typeof errAny.detail === "string" && errAny.detail) {
+            console.error(`  Detail: ${errAny.detail}`);
+          }
+          if (typeof errAny.hint === "string" && errAny.hint) {
+            console.error(`  Hint: ${errAny.hint}`);
           }
-          console.error("  Fix: connect as a superuser (or a role with CREATEROLE and sufficient GRANT privileges)");
-          console.error("  Fix: on managed Postgres, use the provider's admin/master user");
-          console.error("  Tip: run with --print-sql to review the exact SQL plan");
-        }
-        if (errAny.code === "ECONNREFUSED") {
-          console.error("  Hint: check host/port and ensure Postgres is reachable from this machine");
-        }
-        if (errAny.code === "ENOTFOUND") {
-          console.error("  Hint: DNS resolution failed; double-check the host name");
         }
-        if (errAny.code === "ETIMEDOUT") {
-          console.error("  Hint: connection timed out; check network/firewall rules");
+        if (errAny && typeof errAny === "object" && typeof errAny.code === "string") {
+          if (errAny.code === "42501") {
+            console.error("  Context: dropping roles/objects requires sufficient privileges");
+            console.error("  Fix: connect as a superuser (or a role with appropriate DROP privileges)");
+          }
+          if (errAny.code === "ECONNREFUSED") {
+            console.error("  Hint: check host/port and ensure Postgres is reachable from this machine");
+          }
+          if (errAny.code === "ENOTFOUND") {
+            console.error("  Hint: DNS resolution failed; double-check the host name");
+          }
+          if (errAny.code === "ETIMEDOUT") {
+            console.error("  Hint: connection timed out; check network/firewall rules");
+          }
         }
+        process.exitCode = 1;
       }
-      process.exitCode = 1;
     } finally {
       if (client) {
         try {
@@ -876,6 +1637,7 @@ program
           // ignore
         }
       }
+      closeReadline();
     }
   });
 
@@ -1062,7 +1824,7 @@ async function resolveOrInitPaths(): Promise<PathResolution> {
  */
 function isDockerRunning(): boolean {
   try {
-    const result = spawnSync("docker", ["info"], { stdio: "pipe" });
+    const result = spawnSync("docker", ["info"], { stdio: "pipe", timeout: 5000 });
     return result.status === 0;
   } catch {
     return false;
@@ -1074,7 +1836,7 @@ function isDockerRunning(): boolean {
  */
 function getComposeCmd(): string[] | null {
   const tryCmd = (cmd: string, args: string[]): boolean =>
-    spawnSync(cmd, args, { stdio: "ignore" }).status === 0;
+    spawnSync(cmd, args, { stdio: "ignore", timeout: 5000 }).status === 0;
   if (tryCmd("docker-compose", ["version"])) return ["docker-compose"];
   if (tryCmd("docker", ["compose", "version"])) return ["docker", "compose"];
   return null;
@@ -1088,7 +1850,7 @@ function checkRunningContainers(): { running: boolean; containers: string[] } {
     const result = spawnSync(
       "docker",
       ["ps", "--filter", "name=grafana-with-datasources", "--filter", "name=pgwatch", "--format", "{{.Names}}"],
-      { stdio: "pipe", encoding: "utf8" }
+      { stdio: "pipe", encoding: "utf8", timeout: 5000 }
     );
 
     if (result.status === 0 && result.stdout) {
@@ -1204,25 +1966,25 @@ mon
     // Update .env with custom tag if provided
     const envFile = path.resolve(projectDir, ".env");
 
-    // Build .env content, preserving important existing values
-    // Read existing .env first to preserve CI/custom settings
-    let existingTag: string | null = null;
+    // Build .env content, preserving important existing values (registry, password)
+    // 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;
 
     if (fs.existsSync(envFile)) {
       const existingEnv = fs.readFileSync(envFile, "utf8");
-      // Extract existing values
-      const tagMatch = existingEnv.match(/^PGAI_TAG=(.+)$/m);
-      if (tagMatch) existingTag = tagMatch[1].trim();
+      // Extract existing values (except tag - always use CLI version)
       const registryMatch = existingEnv.match(/^PGAI_REGISTRY=(.+)$/m);
       if (registryMatch) existingRegistry = registryMatch[1].trim();
       const pwdMatch = existingEnv.match(/^GF_SECURITY_ADMIN_PASSWORD=(.+)$/m);
       if (pwdMatch) existingPassword = pwdMatch[1].trim();
     }
 
-    // Priority: CLI --tag flag > PGAI_TAG env var > existing .env > package version
-    const imageTag = opts.tag || process.env.PGAI_TAG || existingTag || pkg.version;
+    // Priority: CLI --tag flag > package version
+    // Note: We intentionally do NOT use process.env.PGAI_TAG here because Bun auto-loads .env files,
+    // which would cause stale .env values to override the CLI version. The CLI version should always
+    // match the Docker images. Users can override with --tag if needed.
+    const imageTag = opts.tag || pkg.version;
 
     const envLines: string[] = [`PGAI_TAG=${imageTag}`];
     if (existingRegistry) {
@@ -1550,6 +2312,16 @@ const MONITORING_CONTAINERS = [
   "postgres-reports",
 ];
 
+/**
+ * Network cleanup constants.
+ * Docker Compose creates a default network named "{project}_default".
+ * In CI environments, network cleanup can fail if containers are slow to disconnect.
+ */
+const COMPOSE_PROJECT_NAME = "postgres_ai";
+const DOCKER_NETWORK_NAME = `${COMPOSE_PROJECT_NAME}_default`;
+/** Delay before retrying network cleanup (allows container network disconnections to complete) */
+const NETWORK_CLEANUP_DELAY_MS = 2000;
+
 /** Remove orphaned containers that docker compose down might miss */
 async function removeOrphanedContainers(): Promise<void> {
   for (const container of MONITORING_CONTAINERS) {
@@ -1565,7 +2337,33 @@ mon
   .command("stop")
   .description("stop monitoring services")
   .action(async () => {
-    const code = await runCompose(["down"]);
+    // Multi-stage cleanup strategy for reliable shutdown in CI environments:
+    // Stage 1: Standard compose down with orphan removal
+    // Stage 2: Force remove any orphaned containers, then retry compose down
+    // Stage 3: Force remove the Docker network directly
+    // This handles edge cases where containers are slow to disconnect from networks.
+    let code = await runCompose(["down", "--remove-orphans"]);
+
+    // Stage 2: If initial cleanup fails, try removing orphaned containers first
+    if (code !== 0) {
+      await removeOrphanedContainers();
+      // Wait a moment for container network disconnections to complete
+      await new Promise(resolve => setTimeout(resolve, NETWORK_CLEANUP_DELAY_MS));
+      // Retry compose down
+      code = await runCompose(["down", "--remove-orphans"]);
+    }
+
+    // Final cleanup: force remove the network if it still exists
+    if (code !== 0) {
+      try {
+        await execFilePromise("docker", ["network", "rm", DOCKER_NETWORK_NAME]);
+        // Network removal succeeded - cleanup is complete
+        code = 0;
+      } catch {
+        // Network doesn't exist or couldn't be removed, ignore
+      }
+    }
+
     if (code !== 0) process.exitCode = code;
   });
 
@@ -2524,22 +3322,44 @@ const issues = program.command("issues").description("issues management");
 issues
   .command("list")
   .description("list issues")
+  .option("--status <status>", "filter by status: open, closed, or all (default: all)")
+  .option("--limit <n>", "max number of issues to return (default: 20)", parseInt)
+  .option("--offset <n>", "number of issues to skip (default: 0)", parseInt)
   .option("--debug", "enable debug output")
   .option("--json", "output raw JSON")
-  .action(async (opts: { debug?: boolean; json?: boolean }) => {
+  .action(async (opts: { status?: string; limit?: number; offset?: number; debug?: boolean; json?: boolean }) => {
+    const spinner = createTtySpinner(process.stdout.isTTY ?? false, "Fetching issues...");
     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 orgId = cfg.orgId ?? undefined;
 
       const { apiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
 
-      const result = await fetchIssues({ apiKey, apiBaseUrl, debug: !!opts.debug });
+      let statusFilter: "open" | "closed" | undefined;
+      if (opts.status === "open") {
+        statusFilter = "open";
+      } else if (opts.status === "closed") {
+        statusFilter = "closed";
+      }
+
+      const result = await fetchIssues({
+        apiKey,
+        apiBaseUrl,
+        orgId,
+        status: statusFilter,
+        limit: opts.limit,
+        offset: opts.offset,
+        debug: !!opts.debug,
+      });
+      spinner.stop();
       const trimmed = Array.isArray(result)
         ? (result as any[]).map((r) => ({
             id: (r as any).id,
@@ -2550,6 +3370,7 @@ issues
         : result;
       printResult(trimmed, opts.json);
     } catch (err) {
+      spinner.stop();
       const message = err instanceof Error ? err.message : String(err);
       console.error(message);
       process.exitCode = 1;
@@ -2562,11 +3383,13 @@ issues
   .option("--debug", "enable debug output")
   .option("--json", "output raw JSON")
   .action(async (issueId: string, opts: { debug?: boolean; json?: boolean }) => {
+    const spinner = createTtySpinner(process.stdout.isTTY ?? false, "Fetching issue...");
     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;
@@ -2576,15 +3399,19 @@ issues
 
       const issue = await fetchIssue({ apiKey, apiBaseUrl, issueId, debug: !!opts.debug });
       if (!issue) {
+        spinner.stop();
         console.error("Issue not found");
         process.exitCode = 1;
         return;
       }
 
+      spinner.update("Fetching comments...");
       const comments = await fetchIssueComments({ apiKey, apiBaseUrl, issueId, debug: !!opts.debug });
+      spinner.stop();
       const combined = { issue, comments };
       printResult(combined, opts.json);
     } catch (err) {
+      spinner.stop();
       const message = err instanceof Error ? err.message : String(err);
       console.error(message);
       process.exitCode = 1;
@@ -2598,22 +3425,24 @@ issues
   .option("--debug", "enable debug output")
   .option("--json", "output raw JSON")
   .action(async (issueId: string, content: string, opts: { parent?: string; debug?: boolean; json?: boolean }) => {
-    try {
-      // 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)}`);
-      }
-      content = interpretEscapes(content);
-      if (opts.debug) {
-        // eslint-disable-next-line no-console
-        console.log(`Debug: Interpreted content: ${JSON.stringify(content)}`);
-      }
+    // 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)}`);
+    }
+    content = interpretEscapes(content);
+    if (opts.debug) {
+      // eslint-disable-next-line no-console
+      console.log(`Debug: Interpreted content: ${JSON.stringify(content)}`);
+    }
 
+    const spinner = createTtySpinner(process.stdout.isTTY ?? false, "Posting comment...");
+    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;
@@ -2629,8 +3458,10 @@ issues
         parentCommentId: opts.parent,
         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;
@@ -2642,7 +3473,7 @@ issues
   .description("create a new issue")
   .option("--org-id <id>", "organization id (defaults to config orgId)", (v) => parseInt(v, 10))
   .option("--project-id <id>", "project id", (v) => parseInt(v, 10))
-  .option("--description <text>", "issue description (supports \\\\n)")
+  .option("--description <text>", "issue description (use \\n for newlines)")
   .option(
     "--label <label>",
     "issue label (repeatable)",
@@ -2655,34 +3486,35 @@ issues
   .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 }) => {
-    try {
-      const rootOpts = program.opts<CliOptions>();
-      const cfg = config.readConfig();
-      const { apiKey } = getConfig(rootOpts);
-      if (!apiKey) {
-        console.error("API key is required. Run 'pgai auth' first or set --api-key.");
-        process.exitCode = 1;
-        return;
-      }
+    const rootOpts = program.opts<CliOptions>();
+    const cfg = config.readConfig();
+    const { apiKey } = getConfig(rootOpts);
+    if (!apiKey) {
+      console.error("API key is required. Run 'pgai auth' first or set --api-key.");
+      process.exitCode = 1;
+      return;
+    }
 
-      const title = interpretEscapes(String(rawTitle || "").trim());
-      if (!title) {
-        console.error("title is required");
-        process.exitCode = 1;
-        return;
-      }
+    const title = interpretEscapes(String(rawTitle || "").trim());
+    if (!title) {
+      console.error("title is required");
+      process.exitCode = 1;
+      return;
+    }
 
-      const orgId = typeof opts.orgId === "number" && !Number.isNaN(opts.orgId) ? opts.orgId : cfg.orgId;
-      if (typeof orgId !== "number") {
-        console.error("org_id is required. Either pass --org-id or run 'pgai auth' to store it in config.");
-        process.exitCode = 1;
-        return;
-      }
+    const orgId = typeof opts.orgId === "number" && !Number.isNaN(opts.orgId) ? opts.orgId : cfg.orgId;
+    if (typeof orgId !== "number") {
+      console.error("org_id is required. Either pass --org-id or run 'pgai auth' to store it in config.");
+      process.exitCode = 1;
+      return;
+    }
 
-      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 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 spinner = createTtySpinner(process.stdout.isTTY ?? false, "Creating issue...");
+    try {
       const { apiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
       const result = await createIssue({
         apiKey,
@@ -2694,8 +3526,10 @@ issues
         labels,
         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;
@@ -2705,8 +3539,8 @@ issues
 issues
   .command("update <issueId>")
   .description("update an existing issue (title/description/status/labels)")
-  .option("--title <text>", "new title (supports \\\\n)")
-  .option("--description <text>", "new description (supports \\\\n)")
+  .option("--title <text>", "new title (use \\n for newlines)")
+  .option("--description <text>", "new description (use \\n for newlines)")
   .option("--status <value>", "status: open|closed|0|1")
   .option(
     "--label <label>",
@@ -2721,49 +3555,50 @@ issues
   .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 }) => {
-    try {
-      const rootOpts = program.opts<CliOptions>();
-      const cfg = config.readConfig();
-      const { apiKey } = getConfig(rootOpts);
-      if (!apiKey) {
-        console.error("API key is required. Run 'pgai auth' first or set --api-key.");
-        process.exitCode = 1;
-        return;
-      }
+    const rootOpts = program.opts<CliOptions>();
+    const cfg = config.readConfig();
+    const { apiKey } = getConfig(rootOpts);
+    if (!apiKey) {
+      console.error("API key is required. Run 'pgai auth' first or set --api-key.");
+      process.exitCode = 1;
+      return;
+    }
 
-      const { apiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+    const { apiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
 
-      const title = opts.title !== undefined ? interpretEscapes(String(opts.title)) : undefined;
-      const description = opts.description !== undefined ? interpretEscapes(String(opts.description)) : undefined;
-
-      let status: number | undefined = undefined;
-      if (opts.status !== undefined) {
-        const raw = String(opts.status).trim().toLowerCase();
-        if (raw === "open") status = 0;
-        else if (raw === "closed") status = 1;
-        else {
-          const n = Number(raw);
-          if (!Number.isFinite(n)) {
-            console.error("status must be open|closed|0|1");
-            process.exitCode = 1;
-            return;
-          }
-          status = n;
-        }
-        if (status !== 0 && status !== 1) {
-          console.error("status must be 0 (open) or 1 (closed)");
+    const title = opts.title !== undefined ? interpretEscapes(String(opts.title)) : undefined;
+    const description = opts.description !== undefined ? interpretEscapes(String(opts.description)) : undefined;
+
+    let status: number | undefined = undefined;
+    if (opts.status !== undefined) {
+      const raw = String(opts.status).trim().toLowerCase();
+      if (raw === "open") status = 0;
+      else if (raw === "closed") status = 1;
+      else {
+        const n = Number(raw);
+        if (!Number.isFinite(n)) {
+          console.error("status must be open|closed|0|1");
           process.exitCode = 1;
           return;
         }
+        status = n;
       }
-
-      let labels: string[] | undefined = undefined;
-      if (opts.clearLabels) {
-        labels = [];
-      } else if (Array.isArray(opts.label) && opts.label.length > 0) {
-        labels = opts.label.map(String);
+      if (status !== 0 && status !== 1) {
+        console.error("status must be 0 (open) or 1 (closed)");
+        process.exitCode = 1;
+        return;
       }
+    }
+
+    let labels: string[] | undefined = undefined;
+    if (opts.clearLabels) {
+      labels = [];
+    } else if (Array.isArray(opts.label) && opts.label.length > 0) {
+      labels = opts.label.map(String);
+    }
 
+    const spinner = createTtySpinner(process.stdout.isTTY ?? false, "Updating issue...");
+    try {
       const result = await updateIssue({
         apiKey,
         apiBaseUrl,
@@ -2774,8 +3609,10 @@ issues
         labels,
         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;
@@ -2788,21 +3625,91 @@ issues
   .option("--debug", "enable debug output")
   .option("--json", "output raw JSON")
   .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)}`);
+    }
+    content = interpretEscapes(content);
+    if (opts.debug) {
+      // eslint-disable-next-line no-console
+      console.log(`Debug: Interpreted content: ${JSON.stringify(content)}`);
+    }
+
+    const rootOpts = program.opts<CliOptions>();
+    const cfg = config.readConfig();
+    const { apiKey } = getConfig(rootOpts);
+    if (!apiKey) {
+      console.error("API key is required. Run 'pgai auth' first or set --api-key.");
+      process.exitCode = 1;
+      return;
+    }
+
+    const spinner = createTtySpinner(process.stdout.isTTY ?? false, "Updating comment...");
     try {
-      if (opts.debug) {
-        // eslint-disable-next-line no-console
-        console.log(`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)}`);
+      const { apiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+
+      const result = await updateIssueComment({
+        apiKey,
+        apiBaseUrl,
+        commentId,
+        content,
+        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;
+    }
+  });
+
+// Action Items management (subcommands of issues)
+issues
+  .command("action-items <issueId>")
+  .description("list action items for an issue")
+  .option("--debug", "enable debug output")
+  .option("--json", "output raw JSON")
+  .action(async (issueId: string, opts: { debug?: boolean; json?: boolean }) => {
+    const spinner = createTtySpinner(process.stdout.isTTY ?? false, "Fetching action items...");
+    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 { apiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+
+      const result = await fetchActionItems({ apiKey, apiBaseUrl, issueId, 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;
+    }
+  });
+
+issues
+  .command("view-action-item <actionItemIds...>")
+  .description("view action item(s) with all details (supports multiple IDs)")
+  .option("--debug", "enable debug output")
+  .option("--json", "output raw JSON")
+  .action(async (actionItemIds: string[], opts: { debug?: boolean; json?: boolean }) => {
+    const spinner = createTtySpinner(process.stdout.isTTY ?? false, "Fetching action item(s)...");
+    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;
@@ -2810,15 +3717,172 @@ issues
 
       const { apiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
 
-      const result = await updateIssueComment({
+      const result = await fetchActionItem({ apiKey, apiBaseUrl, actionItemIds, debug: !!opts.debug });
+      if (result.length === 0) {
+        spinner.stop();
+        console.error("Action item(s) not found");
+        process.exitCode = 1;
+        return;
+      }
+      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;
+    }
+  });
+
+issues
+  .command("create-action-item <issueId> <title>")
+  .description("create a new action item for an issue")
+  .option("--description <text>", "detailed description (use \\n for newlines)")
+  .option("--sql-action <sql>", "SQL command to execute")
+  .option("--config <json>", "config change as JSON: {\"parameter\":\"...\",\"value\":\"...\"} (repeatable)", (value: string, previous: ConfigChange[]) => {
+    try {
+      previous.push(JSON.parse(value) as ConfigChange);
+    } catch {
+      console.error(`Invalid JSON for --config: ${value}`);
+      process.exit(1);
+    }
+    return previous;
+  }, [] as ConfigChange[])
+  .option("--debug", "enable debug output")
+  .option("--json", "output raw JSON")
+  .action(async (issueId: string, rawTitle: string, opts: { description?: string; sqlAction?: string; config?: ConfigChange[]; debug?: boolean; json?: boolean }) => {
+    const rootOpts = program.opts<CliOptions>();
+    const cfg = config.readConfig();
+    const { apiKey } = getConfig(rootOpts);
+    if (!apiKey) {
+      console.error("API key is required. Run 'pgai auth' first or set --api-key.");
+      process.exitCode = 1;
+      return;
+    }
+
+    const title = interpretEscapes(String(rawTitle || "").trim());
+    if (!title) {
+      console.error("title is required");
+      process.exitCode = 1;
+      return;
+    }
+
+    const description = opts.description !== undefined ? interpretEscapes(String(opts.description)) : undefined;
+    const sqlAction = opts.sqlAction;
+    const configs = Array.isArray(opts.config) && opts.config.length > 0 ? opts.config : undefined;
+
+    const spinner = createTtySpinner(process.stdout.isTTY ?? false, "Creating action item...");
+    try {
+      const { apiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+      const result = await createActionItem({
         apiKey,
         apiBaseUrl,
-        commentId,
-        content,
+        issueId,
+        title,
+        description,
+        sqlAction,
+        configs,
         debug: !!opts.debug,
       });
-      printResult(result, opts.json);
+      spinner.stop();
+      printResult({ id: result }, opts.json);
+    } catch (err) {
+      spinner.stop();
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(message);
+      process.exitCode = 1;
+    }
+  });
+
+issues
+  .command("update-action-item <actionItemId>")
+  .description("update an action item (title, description, status, sql_action, configs)")
+  .option("--title <text>", "new title (use \\n for newlines)")
+  .option("--description <text>", "new description (use \\n for newlines)")
+  .option("--done", "mark as done")
+  .option("--not-done", "mark as not done")
+  .option("--status <value>", "status: waiting_for_approval|approved|rejected")
+  .option("--status-reason <text>", "reason for status change")
+  .option("--sql-action <sql>", "SQL command (use empty string to clear)")
+  .option("--config <json>", "config change as JSON (repeatable, replaces all configs)", (value: string, previous: ConfigChange[]) => {
+    try {
+      previous.push(JSON.parse(value) as ConfigChange);
+    } catch {
+      console.error(`Invalid JSON for --config: ${value}`);
+      process.exit(1);
+    }
+    return previous;
+  }, [] as ConfigChange[])
+  .option("--clear-configs", "clear all config changes")
+  .option("--debug", "enable debug output")
+  .option("--json", "output raw JSON")
+  .action(async (actionItemId: string, opts: { title?: string; description?: string; done?: boolean; notDone?: boolean; status?: string; statusReason?: string; sqlAction?: string; config?: ConfigChange[]; clearConfigs?: boolean; debug?: boolean; json?: boolean }) => {
+    const rootOpts = program.opts<CliOptions>();
+    const cfg = config.readConfig();
+    const { apiKey } = getConfig(rootOpts);
+    if (!apiKey) {
+      console.error("API key is required. Run 'pgai auth' first or set --api-key.");
+      process.exitCode = 1;
+      return;
+    }
+
+    const title = opts.title !== undefined ? interpretEscapes(String(opts.title)) : undefined;
+    const description = opts.description !== undefined ? interpretEscapes(String(opts.description)) : undefined;
+
+    let isDone: boolean | undefined = undefined;
+    if (opts.done) isDone = true;
+    else if (opts.notDone) isDone = false;
+
+    let status: string | undefined = undefined;
+    if (opts.status !== undefined) {
+      const validStatuses = ["waiting_for_approval", "approved", "rejected"];
+      if (!validStatuses.includes(opts.status)) {
+        console.error(`status must be one of: ${validStatuses.join(", ")}`);
+        process.exitCode = 1;
+        return;
+      }
+      status = opts.status;
+    }
+
+    const statusReason = opts.statusReason;
+    const sqlAction = opts.sqlAction;
+
+    let configs: ConfigChange[] | undefined = undefined;
+    if (opts.clearConfigs) {
+      configs = [];
+    } else if (Array.isArray(opts.config) && opts.config.length > 0) {
+      configs = opts.config;
+    }
+
+    // Check that at least one update field is provided
+    if (title === undefined && description === undefined &&
+        isDone === undefined && status === undefined && statusReason === undefined &&
+        sqlAction === undefined && configs === undefined) {
+      console.error("At least one update option is required");
+      process.exitCode = 1;
+      return;
+    }
+
+    const spinner = createTtySpinner(process.stdout.isTTY ?? false, "Updating action item...");
+    try {
+      const { apiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+      await updateActionItem({
+        apiKey,
+        apiBaseUrl,
+        actionItemId,
+        title,
+        description,
+        isDone,
+        status,
+        statusReason,
+        sqlAction,
+        configs,
+        debug: !!opts.debug,
+      });
+      spinner.stop();
+      printResult({ success: true }, opts.json);
     } catch (err) {
+      spinner.stop();
       const message = err instanceof Error ? err.message : String(err);
       console.error(message);
       process.exitCode = 1;