postgresai 0.12.0-beta.6 → 0.14.0-beta.1

package/README.md

@@ -10,9 +10,9 @@ Command-line interface for PostgresAI monitoring and database management.
 npm install -g postgresai
 ```
 
-Or install the latest alpha release explicitly:
+Or install the latest beta release explicitly:
 ```bash
-npm install -g postgresai@alpha
+npm install -g postgresai@beta
 ```
 
 ### From Homebrew (macOS)
@@ -34,6 +34,64 @@ postgresai --help
 pgai --help  # short alias
 ```
 
+## init (create monitoring user in Postgres)
+
+This command creates (or updates) the `postgres_ai_mon` user and grants the permissions described in the root `README.md` (it is idempotent).
+
+Run without installing (positional connection string):
+
+```bash
+npx postgresai init postgresql://admin@host:5432/dbname
+```
+
+It also accepts libpq “conninfo” syntax:
+
+```bash
+npx postgresai init "dbname=dbname host=host user=admin"
+```
+
+And psql-like options:
+
+```bash
+npx postgresai init -h host -p 5432 -U admin -d dbname
+```
+
+Password input options (in priority order):
+- `--password <password>`
+- `PGAI_MON_PASSWORD` environment variable
+- if not provided: a strong password is generated automatically
+
+By default, the generated password is printed **only in interactive (TTY) mode**. In non-interactive mode, you must either provide the password explicitly, or opt-in to printing it:
+- `--print-password` (dangerous in CI logs)
+
+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
+```
+
+### 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
+```
+
+### Verify and password reset
+
+Verify that everything is configured as expected (no changes):
+
+```bash
+npx postgresai init 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'
+```
+
 ## Quick start
 
 ### Authentication
@@ -55,7 +113,19 @@ Start monitoring with demo database:
 postgres-ai mon quickstart --demo
 ```
 
+Start monitoring with your own database:
+```bash
+postgres-ai mon quickstart --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
+```
+
 This will:
+- Configure API key for automated report uploads (if provided)
+- Add PostgreSQL instance to monitor (if provided)
 - Generate secure Grafana password
 - Start all monitoring services
 - Open Grafana at http://localhost:3000
@@ -66,7 +136,15 @@ This will:
 
 #### Service lifecycle
 ```bash
-postgres-ai mon quickstart [--demo]    # Complete setup (generate config, start services)
+# 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
+
+# Service management
 postgres-ai mon start                  # Start monitoring services
 postgres-ai mon stop                   # Stop monitoring services
 postgres-ai mon restart [service]      # Restart all or specific monitoring service
@@ -74,6 +152,12 @@ postgres-ai mon status                 # Show monitoring services status
 postgres-ai mon health [--wait <sec>]  # Check monitoring services health
 ```
 
+##### Quickstart 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`)
+- `-y, --yes` - Accept all defaults and skip interactive prompts
+
 #### Monitoring target databases (`mon targets` subgroup)
 ```bash
 postgres-ai mon targets list                       # List databases to monitor
@@ -96,7 +180,7 @@ postgres-ai mon shell <service>                # Open shell to monitoring servic
 ### MCP server (`mcp` group)
 
 ```bash
-pgai mcp start                 # Start MCP stdio server exposing list_issues tool
+pgai mcp start                 # Start MCP stdio server exposing tools
 ```
 
 Cursor configuration example (Settings → MCP):
@@ -117,6 +201,36 @@ Cursor configuration example (Settings → MCP):
 
 Tools exposed:
 - list_issues: returns the same JSON as `pgai issues list`.
+- view_issue: view a single issue with its comments (args: { issue_id, debug? })
+- post_issue_comment: post a comment (args: { issue_id, content, parent_comment_id?, debug? })
+
+### Issues management (`issues` group)
+
+```bash
+pgai issues list                                  # List issues (shows: id, title, status, created_at)
+pgai issues view <issueId>                        # View issue details and comments
+pgai issues post_comment <issueId> <content>      # Post a comment to an issue
+# Options:
+#   --parent <uuid>  Parent comment ID (for replies)
+#   --debug          Enable debug output
+#   --json           Output raw JSON (overrides default YAML)
+```
+
+#### Output format for issues commands
+
+By default, issues commands print human-friendly YAML when writing to a terminal. For scripting, you can:
+
+- Use `--json` to force JSON output:
+
+```bash
+pgai issues list --json | jq '.[] | {id, title}'
+```
+
+- Rely on auto-detection: when stdout is not a TTY (e.g., piped or redirected), output is JSON automatically:
+
+```bash
+pgai issues view <issueId> > issue.json
+```
 
 #### Grafana management
 ```bash