postgresai 0.11.0-alpha.8 → 0.12.0-alpha.13

package/README.md

@@ -4,10 +4,22 @@ Command-line interface for PostgresAI monitoring and database management.
 
 ## Installation
 
+### From npm
+
 ```bash
 npm install -g postgresai@alpha
 ```
 
+### From Homebrew (macOS)
+
+```bash
+# Add the PostgresAI tap
+brew tap postgres-ai/tap https://gitlab.com/postgres-ai/homebrew-tap.git
+
+# Install postgresai
+brew install postgresai
+```
+
 ## Usage
 
 The CLI provides three command aliases:
@@ -19,9 +31,23 @@ pgai --help  # short alias
 
 ## Quick start
 
+### Authentication
+
+Authenticate via browser to obtain API key:
+```bash
+pgai auth
+```
+
+This will:
+- Open your browser for authentication
+- Prompt you to select an organization
+- Automatically save your API key to `~/.config/postgresai/config.json`
+
+### Start monitoring
+
 Start monitoring with demo database:
 ```bash
-postgres-ai quickstart --demo
+postgres-ai mon quickstart --demo
 ```
 
 This will:
@@ -31,40 +57,144 @@ This will:
 
 ## Commands
 
-### Monitoring services
+### Monitoring services management (`mon` group)
+
+#### Service lifecycle
 ```bash
-postgres-ai start              # Start all services
-postgres-ai stop               # Stop all services
-postgres-ai restart            # Restart all services
-postgres-ai status             # Show service status
-postgres-ai logs [service]     # Show logs
+postgres-ai mon quickstart [--demo]    # Complete setup (generate config, start services)
+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
+postgres-ai mon status                 # Show monitoring services status
+postgres-ai mon health [--wait <sec>]  # Check monitoring services health
 ```
 
-### Instance management
+#### Monitoring target databases (`mon targets` subgroup)
 ```bash
-postgres-ai list-instances                          # List configured instances
-postgres-ai add-instance <conn-string> <name>       # Add new instance
-postgres-ai remove-instance <name>                  # Remove instance
-postgres-ai update-config                           # Regenerate config files
+postgres-ai mon targets list                       # List databases to monitor
+postgres-ai mon targets add <conn-string> <name>   # Add database to monitor
+postgres-ai mon targets remove <name>              # Remove monitoring target
+postgres-ai mon targets test <name>                # Test target connectivity
 ```
 
-### Configuration
+#### Configuration and maintenance
 ```bash
-postgres-ai config             # Show current configuration
-postgres-ai check              # Verify prerequisites
+postgres-ai mon config                         # Show monitoring configuration
+postgres-ai mon update-config                  # Apply configuration changes
+postgres-ai mon update                         # Update monitoring stack
+postgres-ai mon reset [service]                # Reset service data
+postgres-ai mon clean                          # Cleanup artifacts
+postgres-ai mon check                          # System readiness check
+postgres-ai mon shell <service>                # Open shell to monitoring service
 ```
 
-### API key management
+### MCP server (`mcp` group)
+
 ```bash
-postgres-ai add-key <key>      # Store API key
+pgai mcp start                 # Start MCP stdio server exposing list_issues tool
+```
+
+Cursor configuration example (Settings → MCP):
+
+```json
+{
+  "mcpServers": {
+    "PostgresAI": {
+      "command": "pgai",
+      "args": ["mcp", "start"],
+      "env": {
+        "PGAI_API_BASE_URL": "https://postgres.ai/api/general/"
+      }
+    }
+  }
+}
+```
+
+Tools exposed:
+- list_issues: returns the same JSON as `pgai issues list`.
+
+#### Grafana management
+```bash
+postgres-ai mon generate-grafana-password      # Generate new Grafana password
+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
 ```
 
-## Environment variables
+## Configuration
+
+The CLI stores configuration in `~/.config/postgresai/config.json` including:
+- API key
+- Base URL
+- Organization ID
+
+### Configuration priority
+
+API key resolution order:
+1. Command line option (`--api-key`)
+2. Environment variable (`PGAI_API_KEY`)
+3. User config file (`~/.config/postgresai/config.json`)
+4. Legacy project config (`.pgwatch-config`)
+
+Base URL resolution order:
+- API base URL (`apiBaseUrl`):
+  1. Command line option (`--api-base-url`)
+  2. Environment variable (`PGAI_API_BASE_URL`)
+  3. User config file `baseUrl` (`~/.config/postgresai/config.json`)
+  4. Default: `https://postgres.ai/api/general/`
+- UI base URL (`uiBaseUrl`):
+  1. Command line option (`--ui-base-url`)
+  2. Environment variable (`PGAI_UI_BASE_URL`)
+  3. Default: `https://console.postgres.ai`
+
+Normalization:
+- A single trailing `/` is removed to ensure consistent path joining.
+
+### Environment variables
 
 - `PGAI_API_KEY` - API key for PostgresAI services
-- `PGAI_BASE_URL` - API endpoint (default: `https://postgres.ai/api/general/`)
+- `PGAI_API_BASE_URL` - API endpoint for backend RPC (default: `https://postgres.ai/api/general/`)
+- `PGAI_UI_BASE_URL` - UI endpoint for browser routes (default: `https://console.postgres.ai`)
+
+### CLI options
+
+- `--api-base-url <url>` - overrides `PGAI_API_BASE_URL`
+- `--ui-base-url <url>` - overrides `PGAI_UI_BASE_URL`
+
+### Examples
+
+Linux/macOS (bash/zsh):
+
+```bash
+export PGAI_API_BASE_URL=https://v2.postgres.ai/api/general/
+export PGAI_UI_BASE_URL=https://console.postgres.ai
+pgai auth --debug
+```
+
+Windows PowerShell:
+
+```powershell
+$env:PGAI_API_BASE_URL = "https://v2.postgres.ai/api/general/"
+$env:PGAI_UI_BASE_URL = "https://console.postgres.ai"
+pgai auth --debug
+```
+
+Via CLI options (overrides env):
+
+```bash
+pgai auth --debug \
+  --api-base-url https://v2.postgres.ai/api/general/ \
+  --ui-base-url https://console.postgres.ai
+```
+
+Notes:
+- If `PGAI_UI_BASE_URL` is not set, the default is `https://console.postgres.ai`.
 
 ## Requirements