postgresai 0.14.0-dev.36 → 0.14.0-dev.38

package/README.md

@@ -50,26 +50,26 @@ If you want `npx pgai ...` as a shorthand for `npx postgresai ...`, install the
 npx pgai --help
 ```
 
-## init (create monitoring user in Postgres)
+## prepare-db (create monitoring user in Postgres)
 
 This command creates (or updates) the `postgres_ai_mon` user, creates the required view(s), and grants the permissions described in the root `README.md` (it is idempotent). Where supported, it also enables observability extensions described there.
 
 Run without installing (positional connection string):
 
 ```bash
-npx postgresai init postgresql://admin@host:5432/dbname
+npx postgresai prepare-db postgresql://admin@host:5432/dbname
 ```
 
-It also accepts libpq “conninfo” syntax:
+It also accepts libpq "conninfo" syntax:
 
 ```bash
-npx postgresai init "dbname=dbname host=host user=admin"
+npx postgresai prepare-db "dbname=dbname host=host user=admin"
 ```
 
 And psql-like options:
 
 ```bash
-npx postgresai init -h host -p 5432 -U admin -d dbname
+npx postgresai prepare-db -h host -p 5432 -U admin -d dbname
 ```
 
 Password input options (in priority order):
@@ -83,7 +83,7 @@ By default, the generated password is printed **only in interactive (TTY) mode**
 Optional permissions (RDS/self-managed extras from the root `README.md`) are enabled by default. To skip them:
 
 ```bash
-npx postgresai init postgresql://admin@host:5432/dbname --skip-optional-permissions
+npx postgresai prepare-db postgresql://admin@host:5432/dbname --skip-optional-permissions
 ```
 
 ### Print SQL / dry run
@@ -91,7 +91,7 @@ npx postgresai init postgresql://admin@host:5432/dbname --skip-optional-permissi
 To see what SQL would be executed (passwords redacted by default):
 
 ```bash
-npx postgresai init postgresql://admin@host:5432/dbname --print-sql
+npx postgresai prepare-db postgresql://admin@host:5432/dbname --print-sql
 ```
 
 ### Verify and password reset
@@ -99,13 +99,13 @@ npx postgresai init postgresql://admin@host:5432/dbname --print-sql
 Verify that everything is configured as expected (no changes):
 
 ```bash
-npx postgresai init postgresql://admin@host:5432/dbname --verify
+npx postgresai prepare-db postgresql://admin@host:5432/dbname --verify
 ```
 
 Reset monitoring user password only (no other changes):
 
 ```bash
-npx postgresai init postgresql://admin@host:5432/dbname --reset-password --password 'new_password'
+npx postgresai prepare-db postgresql://admin@host:5432/dbname --reset-password --password 'new_password'
 ```
 
 ## Quick start
@@ -126,17 +126,17 @@ This will:
 
 Start monitoring with demo database:
 ```bash
-postgres-ai mon quickstart --demo
+postgres-ai mon local-install --demo
 ```
 
 Start monitoring with your own database:
 ```bash
-postgres-ai mon quickstart --db-url postgresql://user:pass@host:5432/db
+postgres-ai mon local-install --db-url postgresql://user:pass@host:5432/db
 ```
 
 Complete automated setup with API key and database:
 ```bash
-postgres-ai mon quickstart --api-key your_key --db-url postgresql://user:pass@host:5432/db -y
+postgres-ai mon local-install --api-key your_key --db-url postgresql://user:pass@host:5432/db -y
 ```
 
 This will:
@@ -153,12 +153,12 @@ This will:
 #### Service lifecycle
 ```bash
 # Complete setup with various options
-postgres-ai mon quickstart                                  # Interactive setup for production
-postgres-ai mon quickstart --demo                           # Demo mode with sample database
-postgres-ai mon quickstart --api-key <key>                  # Setup with API key
-postgres-ai mon quickstart --db-url <url>                   # Setup with database URL
-postgres-ai mon quickstart --api-key <key> --db-url <url>   # Complete automated setup
-postgres-ai mon quickstart -y                               # Auto-accept all defaults
+postgres-ai mon local-install                                  # Interactive setup for production
+postgres-ai mon local-install --demo                           # Demo mode with sample database
+postgres-ai mon local-install --api-key <key>                  # Setup with API key
+postgres-ai mon local-install --db-url <url>                   # Setup with database URL
+postgres-ai mon local-install --api-key <key> --db-url <url>   # Complete automated setup
+postgres-ai mon local-install -y                               # Auto-accept all defaults
 
 # Service management
 postgres-ai mon start                  # Start monitoring services
@@ -168,7 +168,7 @@ postgres-ai mon status                 # Show monitoring services status
 postgres-ai mon health [--wait <sec>]  # Check monitoring services health
 ```
 
-##### Quickstart options
+##### local-install options
 - `--demo` - Demo mode with sample database (testing only, cannot use with --api-key)
 - `--api-key <key>` - Postgres AI API key for automated report uploads
 - `--db-url <url>` - PostgreSQL connection URL to monitor (format: `postgresql://user:pass@host:port/db`)
@@ -256,10 +256,10 @@ postgres-ai mon show-grafana-credentials       # Show Grafana credentials
 
 ### Authentication and API key management
 ```bash
-postgres-ai auth               # Authenticate via browser (recommended)
-postgres-ai add-key <key>      # Manually store API key
-postgres-ai show-key           # Show stored key (masked)
-postgres-ai remove-key         # Remove stored key
+postgres-ai auth                    # Authenticate via browser (OAuth)
+postgres-ai auth --set-key <key>    # Store API key directly
+postgres-ai show-key                # Show stored key (masked)
+postgres-ai remove-key              # Remove stored key
 ```
 
 ## Configuration

package/bin/postgres-ai.ts

@@ -17,10 +17,68 @@ import { startMcpServer } from "../lib/mcp-server";
 import { fetchIssues, fetchIssueComments, createIssueComment, fetchIssue } from "../lib/issues";
 import { resolveBaseUrls } from "../lib/util";
 import { applyInitPlan, buildInitPlan, connectWithSslFallback, DEFAULT_MONITORING_USER, redactPasswordsInSql, resolveAdminConnection, resolveMonitoringPassword, verifyInitSetup } from "../lib/init";
+import { REPORT_GENERATORS, CHECK_INFO, generateAllReports } from "../lib/checkup";
+import { createCheckupReport, uploadCheckupReportJson, RpcError, formatRpcErrorForDisplay } from "../lib/checkup-api";
 
 const execPromise = promisify(exec);
 const execFilePromise = promisify(execFile);
 
+function expandHomePath(p: string): string {
+  const s = (p || "").trim();
+  if (!s) return s;
+  if (s === "~") return os.homedir();
+  if (s.startsWith("~/") || s.startsWith("~\\")) {
+    return path.join(os.homedir(), s.slice(2));
+  }
+  return s;
+}
+
+function createTtySpinner(
+  enabled: boolean,
+  initialText: string
+): { update: (text: string) => void; stop: (finalText?: string) => void } {
+  if (!enabled) {
+    return {
+      update: () => {},
+      stop: () => {},
+    };
+  }
+
+  const frames = ["|", "/", "-", "\\"];
+  const startTs = Date.now();
+  let text = initialText;
+  let frameIdx = 0;
+  let stopped = false;
+
+  const render = (): void => {
+    if (stopped) return;
+    const elapsedSec = ((Date.now() - startTs) / 1000).toFixed(1);
+    const frame = frames[frameIdx % frames.length]!;
+    frameIdx += 1;
+    process.stdout.write(`\r\x1b[2K${frame} ${text} (${elapsedSec}s)`);
+  };
+
+  const timer = setInterval(render, 120);
+  render(); // immediate feedback
+
+  return {
+    update: (t: string) => {
+      text = t;
+      render();
+    },
+    stop: (finalText?: string) => {
+      if (stopped) return;
+      stopped = true;
+      clearInterval(timer);
+      process.stdout.write("\r\x1b[2K");
+      if (finalText && finalText.trim()) {
+        process.stdout.write(finalText);
+      }
+      process.stdout.write("\n");
+    },
+  };
+}
+
 /**
  * CLI configuration options
  */
@@ -203,8 +261,22 @@ program
   );
 
 program
-  .command("init [conn]")
-  .description("Create a monitoring user, required view(s), and grant required permissions (idempotent)")
+  .command("set-default-project <project>")
+  .description("store default project for checkup uploads")
+  .action(async (project: string) => {
+    const value = (project || "").trim();
+    if (!value) {
+      console.error("Error: project is required");
+      process.exitCode = 1;
+      return;
+    }
+    config.writeConfig({ defaultProject: value });
+    console.log(`Default project saved: ${value}`);
+  });
+
+program
+  .command("prepare-db [conn]")
+  .description("Prepare database for monitoring: create monitoring user, required view(s), and grant permissions (idempotent)")
   .option("--db-url <url>", "PostgreSQL connection URL (admin) to run the setup against (deprecated; pass it as positional arg)")
   .option("-h, --host <host>", "PostgreSQL host (psql-like)")
   .option("-p, --port <port>", "PostgreSQL port (psql-like)")
@@ -223,9 +295,9 @@ program
     [
       "",
       "Examples:",
-      "  postgresai init postgresql://admin@host:5432/dbname",
-      "  postgresai init \"dbname=dbname host=host user=admin\"",
-      "  postgresai init -h host -p 5432 -U admin -d dbname",
+      "  postgresai prepare-db postgresql://admin@host:5432/dbname",
+      "  postgresai prepare-db \"dbname=dbname host=host user=admin\"",
+      "  postgresai prepare-db -h host -p 5432 -U admin -d dbname",
       "",
       "Admin password:",
       "  --admin-password <password>   or  PGPASSWORD=... (libpq standard)",
@@ -247,16 +319,16 @@ program
       "  PGAI_MON_PASSWORD                   — monitoring password",
       "",
       "Inspect SQL without applying changes:",
-      "  postgresai init <conn> --print-sql",
+      "  postgresai prepare-db <conn> --print-sql",
       "",
       "Verify setup (no changes):",
-      "  postgresai init <conn> --verify",
+      "  postgresai prepare-db <conn> --verify",
       "",
       "Reset monitoring password only:",
-      "  postgresai init <conn> --reset-password --password '...'",
+      "  postgresai prepare-db <conn> --reset-password --password '...'",
       "",
       "Offline SQL plan (no DB connection):",
-      "  postgresai init --print-sql",
+      "  postgresai prepare-db --print-sql",
     ].join("\n")
   )
   .action(async (conn: string | undefined, opts: {
@@ -336,7 +408,7 @@ program
       });
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e);
-      console.error(`Error: init: ${msg}`);
+      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("");
@@ -372,14 +444,14 @@ program
           includeOptionalPermissions,
         });
         if (v.ok) {
-          console.log("✓ init verify: 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}`);
           }
           return;
         }
-        console.error("✗ init verify failed: missing required items");
+        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:");
@@ -455,7 +527,7 @@ program
 
       const { applied, skippedOptional } = await applyInitPlan({ client, plan: effectivePlan });
 
-      console.log(opts.resetPassword ? "✓ init password reset completed" : "✓ init completed");
+      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}`);
@@ -477,7 +549,7 @@ program
       if (!message || message === "[object Object]") {
         message = "Unknown error";
       }
-      console.error(`Error: init: ${message}`);
+      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;
@@ -529,6 +601,250 @@ program
     }
   });
 
+program
+  .command("checkup [conn]")
+  .description("generate health check reports directly from PostgreSQL (express mode)")
+  .option("--check-id <id>", `specific check to run: ${Object.keys(CHECK_INFO).join(", ")}, or ALL`, "ALL")
+  .option("--node-name <name>", "node name for reports", "node-01")
+  .option("--output <path>", "output directory for JSON files")
+  .option("--json", "output to stdout as JSON instead of files")
+  .option("--upload", "create a remote checkup report and upload JSON results (requires API key)", false)
+  .option("--project <project>", "project name or ID for remote upload (used with --upload; defaults to config defaultProject)")
+  .addHelpText(
+    "after",
+    [
+      "",
+      "Available checks:",
+      ...Object.entries(CHECK_INFO).map(([id, title]) => `  ${id}: ${title}`),
+      "",
+      "Examples:",
+      "  postgresai checkup postgresql://user:pass@host:5432/db",
+      "  postgresai checkup postgresql://user:pass@host:5432/db --check-id A003",
+      "  postgresai checkup postgresql://user:pass@host:5432/db --json",
+      "  postgresai checkup postgresql://user:pass@host:5432/db --output ./reports",
+      "  postgresai checkup postgresql://user:pass@host:5432/db --upload --project my_project",
+      "  postgresai set-default-project my_project",
+      "  postgresai checkup postgresql://user:pass@host:5432/db --upload",
+    ].join("\n")
+  )
+  .action(async (conn: string | undefined, opts: {
+    checkId: string;
+    nodeName: string;
+    output?: string;
+    json?: boolean;
+    upload?: boolean;
+    project?: string;
+  }, cmd: Command) => {
+    if (!conn) {
+      // No args — show help like other commands do (instead of a bare error).
+      cmd.outputHelp();
+      process.exitCode = 1;
+      return;
+    }
+
+    // Preflight: validate/create output directory BEFORE connecting / running checks.
+    // This avoids waiting on network/DB work only to fail at the very end.
+    let outputPath: string | undefined;
+    if (opts.output && !opts.json) {
+      const outputDir = expandHomePath(opts.output);
+      outputPath = path.isAbsolute(outputDir) ? outputDir : path.resolve(process.cwd(), outputDir);
+      if (!fs.existsSync(outputPath)) {
+        try {
+          fs.mkdirSync(outputPath, { recursive: true });
+        } catch (e) {
+          const errAny = e as any;
+          const code = typeof errAny?.code === "string" ? errAny.code : "";
+          const msg = errAny instanceof Error ? errAny.message : String(errAny);
+          if (code === "EACCES" || code === "EPERM" || code === "ENOENT") {
+            console.error(`Error: Failed to create output directory: ${outputPath}`);
+            console.error(`Reason: ${msg}`);
+            console.error("Tip: choose a writable path, e.g. --output ./reports or --output ~/reports");
+            process.exitCode = 1;
+            return;
+          }
+          throw e;
+        }
+      }
+    }
+
+    // Preflight: validate upload flags/credentials BEFORE connecting / running checks.
+    // This allows "fast-fail" for missing API key / project name.
+    let uploadCfg:
+      | { apiKey: string; apiBaseUrl: string; project: string; epoch: number }
+      | undefined;
+    if (opts.upload) {
+      const rootOpts = program.opts() as CliOptions;
+      const { apiKey } = getConfig(rootOpts);
+      if (!apiKey) {
+        console.error("Error: API key is required for --upload");
+        console.error("Tip: run 'postgresai auth' or pass --api-key / set PGAI_API_KEY");
+        process.exitCode = 1;
+        return;
+      }
+
+      const cfg = config.readConfig();
+      const { apiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+      const project = ((opts.project || cfg.defaultProject) || "").trim();
+      if (!project) {
+        console.error("Error: --project is required (or set a default via 'postgresai set-default-project <project>')");
+        process.exitCode = 1;
+        return;
+      }
+      const epoch = Math.floor(Date.now() / 1000);
+      uploadCfg = {
+        apiKey,
+        apiBaseUrl,
+        project,
+        epoch,
+      };
+    }
+
+    // Use the same SSL behavior as prepare-db:
+    // - Default: sslmode=prefer (try SSL first, fallback to non-SSL)
+    // - Respect PGSSLMODE env and ?sslmode=... in connection URI
+    const adminConn = resolveAdminConnection({
+      conn,
+      envPassword: process.env.PGPASSWORD,
+    });
+    let client: Client | undefined;
+    const spinnerEnabled = !!process.stdout.isTTY && !opts.json;
+    const spinner = createTtySpinner(spinnerEnabled, "Connecting to Postgres");
+
+    try {
+      spinner.update("Connecting to Postgres");
+      const connResult = await connectWithSslFallback(Client, adminConn);
+      client = connResult.client as Client;
+
+      let reports: Record<string, any>;
+      let uploadSummary:
+        | { project: string; reportId: number; uploaded: Array<{ checkId: string; filename: string; chunkId: number }> }
+        | undefined;
+
+      if (opts.checkId === "ALL") {
+        reports = await generateAllReports(client, opts.nodeName, (p) => {
+          spinner.update(`Running ${p.checkId}: ${p.checkTitle} (${p.index}/${p.total})`);
+        });
+      } else {
+        const checkId = opts.checkId.toUpperCase();
+        const generator = REPORT_GENERATORS[checkId];
+        if (!generator) {
+          spinner.stop();
+          console.error(`Unknown check ID: ${opts.checkId}`);
+          console.error(`Available: ${Object.keys(CHECK_INFO).join(", ")}, ALL`);
+          process.exitCode = 1;
+          return;
+        }
+        spinner.update(`Running ${checkId}: ${CHECK_INFO[checkId] || checkId}`);
+        reports = { [checkId]: await generator(client, opts.nodeName) };
+      }
+
+      // Optional: upload to PostgresAI API.
+      if (uploadCfg) {
+        spinner.update("Creating remote checkup report");
+        const created = await createCheckupReport({
+          apiKey: uploadCfg.apiKey,
+          apiBaseUrl: uploadCfg.apiBaseUrl,
+          project: uploadCfg.project,
+          epoch: uploadCfg.epoch,
+        });
+
+        const reportId = created.reportId;
+        // Keep upload progress out of stdout when --json is used.
+        const logUpload = (msg: string): void => {
+          if (opts.json) console.error(msg);
+        };
+        logUpload(`Created remote checkup report: ${reportId}`);
+
+        const uploaded: Array<{ checkId: string; filename: string; chunkId: number }> = [];
+        for (const [checkId, report] of Object.entries(reports)) {
+          spinner.update(`Uploading ${checkId}.json`);
+          const jsonText = JSON.stringify(report, null, 2);
+          const r = await uploadCheckupReportJson({
+            apiKey: uploadCfg.apiKey,
+            apiBaseUrl: uploadCfg.apiBaseUrl,
+            reportId,
+            filename: `${checkId}.json`,
+            checkId,
+            jsonText,
+          });
+          uploaded.push({ checkId, filename: `${checkId}.json`, chunkId: r.reportChunkId });
+        }
+        logUpload("Upload completed");
+        uploadSummary = { project: uploadCfg.project, reportId, uploaded };
+      }
+
+      spinner.stop();
+      // Output results
+      if (opts.json) {
+        console.log(JSON.stringify(reports, null, 2));
+      } else if (opts.output) {
+        // Write to files
+        // outputPath is preflight-validated above
+        const outDir = outputPath || path.resolve(process.cwd(), expandHomePath(opts.output));
+        for (const [checkId, report] of Object.entries(reports)) {
+          const filePath = path.join(outDir, `${checkId}.json`);
+          fs.writeFileSync(filePath, JSON.stringify(report, null, 2), "utf8");
+          console.log(`✓ ${checkId}: ${filePath}`);
+        }
+      } else if (uploadSummary) {
+        // Default with --upload: show upload result instead of local-only summary.
+        console.log("\nCheckup report uploaded");
+        console.log("======================\n");
+        console.log(`Project: ${uploadSummary.project}`);
+        console.log(`Report ID: ${uploadSummary.reportId}`);
+        console.log("View in Console: console.postgres.ai → Support → checkup reports");
+        console.log("");
+        console.log("Files:");
+        for (const item of uploadSummary.uploaded) {
+          console.log(`- ${item.checkId}: ${item.filename}`);
+        }
+      } else {
+        // Default: print summary
+        console.log("\nHealth Check Reports Generated:");
+        console.log("================================\n");
+        for (const [checkId, report] of Object.entries(reports)) {
+          const r = report as any;
+          console.log(`${checkId}: ${r.checkTitle}`);
+          if (r.results && r.results[opts.nodeName]) {
+            const nodeData = r.results[opts.nodeName];
+            if (nodeData.postgres_version) {
+              console.log(`  PostgreSQL: ${nodeData.postgres_version.version}`);
+            }
+            if (checkId === "A007" && nodeData.data) {
+              const count = Object.keys(nodeData.data).length;
+              console.log(`  Altered settings: ${count}`);
+            }
+            if (checkId === "A004" && nodeData.data) {
+              if (nodeData.data.database_sizes) {
+                const dbCount = Object.keys(nodeData.data.database_sizes).length;
+                console.log(`  Databases: ${dbCount}`);
+              }
+              if (nodeData.data.general_info?.cache_hit_ratio) {
+                console.log(`  Cache hit ratio: ${nodeData.data.general_info.cache_hit_ratio.value}%`);
+              }
+            }
+          }
+        }
+        console.log("\nUse --json for full output or --output <dir> to save files");
+      }
+    } catch (error) {
+      spinner.stop();
+      if (error instanceof RpcError) {
+        for (const line of formatRpcErrorForDisplay(error)) {
+          console.error(line);
+        }
+      } else {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Error: ${message}`);
+      }
+      process.exitCode = 1;
+    } finally {
+      if (client) {
+        await client.end();
+      }
+    }
+  });
+
 /**
  * Stub function for not implemented commands
  */
@@ -679,8 +995,8 @@ program.command("help", { isDefault: true }).description("show help").action(()
 const mon = program.command("mon").description("monitoring services management");
 
 mon
-  .command("quickstart")
-  .description("complete setup (generate config, start monitoring services)")
+  .command("local-install")
+  .description("install local monitoring stack (generate config, start services)")
   .option("--demo", "demo mode with sample database", false)
   .option("--api-key <key>", "Postgres AI API key for automated report uploads")
   .option("--db-url <url>", "PostgreSQL connection URL to monitor")
@@ -688,7 +1004,7 @@ mon
   .option("-y, --yes", "accept all defaults and skip interactive prompts", false)
   .action(async (opts: { demo: boolean; apiKey?: string; dbUrl?: string; tag?: string; yes: boolean }) => {
     console.log("\n=================================");
-    console.log("  PostgresAI Monitoring Quickstart");
+    console.log("  PostgresAI monitoring local install");
     console.log("=================================\n");
     console.log("This will install, configure, and start the monitoring system\n");
 
@@ -726,8 +1042,8 @@ mon
     if (opts.demo && opts.apiKey) {
       console.error("✗ Cannot use --api-key with --demo mode");
       console.error("✗ Demo mode is for testing only and does not support API key integration");
-      console.error("\nUse demo mode without API key: postgres-ai mon quickstart --demo");
-      console.error("Or use production mode with API key: postgres-ai mon quickstart --api-key=your_key");
+      console.error("\nUse demo mode without API key: postgres-ai mon local-install --demo");
+      console.error("Or use production mode with API key: postgres-ai mon local-install --api-key=your_key");
       process.exitCode = 1;
       return;
     }
@@ -989,7 +1305,7 @@ mon
 
     // Final summary
     console.log("=================================");
-    console.log("  🎉 Quickstart setup completed!");
+    console.log("  Local install completed!");
     console.log("=================================\n");
 
     console.log("What's running:");
@@ -1536,10 +1852,26 @@ targets
 // Authentication and API key management
 program
   .command("auth")
-  .description("authenticate via browser and obtain API key")
+  .description("authenticate via browser (OAuth) or store API key directly")
+  .option("--set-key <key>", "store API key directly without OAuth flow")
   .option("--port <port>", "local callback server port (default: random)", parseInt)
   .option("--debug", "enable debug output")
-  .action(async (opts: { port?: number; debug?: boolean }) => {
+  .action(async (opts: { setKey?: string; port?: number; debug?: boolean }) => {
+    // If --set-key is provided, store it directly without OAuth
+    if (opts.setKey) {
+      const trimmedKey = opts.setKey.trim();
+      if (!trimmedKey) {
+        console.error("Error: API key cannot be empty");
+        process.exitCode = 1;
+        return;
+      }
+      
+      config.writeConfig({ apiKey: trimmedKey });
+      console.log(`API key saved to ${config.getConfigPath()}`);
+      return;
+    }
+
+    // Otherwise, proceed with OAuth flow
     const pkce = require("../lib/pkce");
     const authServer = require("../lib/auth-server");
 
@@ -1765,8 +2097,9 @@ program
 
 program
   .command("add-key <apiKey>")
-  .description("store API key")
+  .description("store API key (deprecated: use 'auth --set-key' instead)")
   .action(async (apiKey: string) => {
+    console.warn("Warning: 'add-key' is deprecated. Use 'auth --set-key <key>' instead.\n");
     config.writeConfig({ apiKey });
     console.log(`API key saved to ${config.getConfigPath()}`);
   });
@@ -1893,7 +2226,7 @@ mon
     const { projectDir } = await resolveOrInitPaths();
     const cfgPath = path.resolve(projectDir, ".pgwatch-config");
     if (!fs.existsSync(cfgPath)) {
-      console.error("Configuration file not found. Run 'postgres-ai mon quickstart' first.");
+      console.error("Configuration file not found. Run 'postgres-ai mon local-install' first.");
       process.exitCode = 1;
       return;
     }