Merge branch '66-cli-command-renames-and-api-key-authentication' into 'main'

refactor: improve CLI commands and authentication flow

Closes #66

See merge request postgres-ai/postgres_ai!113

Author: bogdan-ts

README.md

@@ -79,49 +79,49 @@ Use the CLI to create/update the monitoring role and grant all required permissi
 # Monitoring password:
 # - by default, postgresai generates a strong password automatically
 # - it is printed only in interactive (TTY) mode, or if you opt in via --print-password
-PGPASSWORD='...' npx postgresai init postgresql://admin@host:5432/dbname
+PGPASSWORD='...' npx postgresai prepare-db postgresql://admin@host:5432/dbname
 ```
 
 Optional permissions (RDS/self-managed extras) are enabled by default. To skip them:
 
 ```bash
-PGPASSWORD='...' npx postgresai init postgresql://admin@host:5432/dbname --skip-optional-permissions
+PGPASSWORD='...' npx postgresai prepare-db postgresql://admin@host:5432/dbname --skip-optional-permissions
 ```
 
 Verify everything is in place (no changes):
 
 ```bash
-PGPASSWORD='...' npx postgresai init postgresql://admin@host:5432/dbname --verify
+PGPASSWORD='...' npx postgresai prepare-db postgresql://admin@host:5432/dbname --verify
 ```
 
 If you want to reset the monitoring password only (no other changes), you can rely on auto-generation:
 
 ```bash
-PGPASSWORD='...' npx postgresai init postgresql://admin@host:5432/dbname --reset-password
+PGPASSWORD='...' npx postgresai prepare-db postgresql://admin@host:5432/dbname --reset-password
 ```
 
-By default, `postgresai init` auto-generates a strong password (see above).
+By default, `postgresai prepare-db` auto-generates a strong password (see above).
 
 If you want to set a specific password instead:
 
 ```bash
-PGPASSWORD='...' npx postgresai init postgresql://admin@host:5432/dbname --reset-password --password 'new_password'
+PGPASSWORD='...' npx postgresai prepare-db postgresql://admin@host:5432/dbname --reset-password --password 'new_password'
 ```
 
 If you want to see what will be executed first, use `--print-sql` (prints the SQL plan and exits; passwords redacted by default). This can be done without a DB connection:
 
 ```bash
-npx postgresai init --print-sql
+npx postgresai prepare-db --print-sql
 ```
 
 Optionally, to render the plan for a specific database:
 
 ```bash
 # Pick database (default is PGDATABASE or "postgres"):
-npx postgresai init --print-sql -d dbname
+npx postgresai prepare-db --print-sql -d dbname
 
 # Provide an explicit monitoring password (still redacted in output):
-npx postgresai init --print-sql -d dbname --password '...'
+npx postgresai prepare-db --print-sql -d dbname --password '...'
 ```
 
 ### Troubleshooting
@@ -140,7 +140,7 @@ If you see errors like `permission denied` / `insufficient_privilege` / code `42
 - **Review SQL before running** (audit-friendly):
 
     ```bash
-    npx postgresai init --print-sql -d mydb
+    npx postgresai prepare-db --print-sql -d mydb
     ```
 
 **One command setup:**

cli/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,29 +83,29 @@ 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
 
 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
 
 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

cli/bin/postgres-ai.ts

@@ -203,8 +203,8 @@ program
   );
 
 program
-  .command("init [conn]")
-  .description("Create a monitoring user, required view(s), and grant required permissions (idempotent)")
+  .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 +223,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 +247,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 +336,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 +372,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 +455,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 +477,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;
@@ -679,16 +679,16 @@ 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")
   .option("--tag <tag>", "Docker image tag to use (e.g., 0.14.0, 0.14.0-dev.33)")
   .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 +726,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 +989,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 +1536,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 +1781,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 +1910,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;
     }