From afbef457d58c9acf029cddabdeec17053acf0bc0 Mon Sep 17 00:00:00 2001 From: Nik Samokhvalov Date: Wed, 6 May 2026 16:58:06 -0700 Subject: [PATCH] docs(cli): align CLI reference with current implementation Rewrite the PostgresAI CLI reference to match the actual command tree in cli/bin/postgres-ai.ts: rename mon quickstart -> mon local-install, move show-key/remove-key under auth (drop top-level add-key in favour of `auth --set-key`), use hyphens for issues subcommands, and add the previously undocumented commands (prepare-db, unprepare-db, checkup, reports, set-default-project, set-storage-url, mcp install, issues create/update/update-comment/files/action-items, mon targets test, mon shell, mon clean, mon check, mon health, mon update, etc.). --- .../postgresai-cli-reference.md | 768 +++++++++++++----- 1 file changed, 545 insertions(+), 223 deletions(-) diff --git a/docs/reference-guides/postgresai-cli-reference.md b/docs/reference-guides/postgresai-cli-reference.md index 4982a36d..9282d8d7 100644 --- a/docs/reference-guides/postgresai-cli-reference.md +++ b/docs/reference-guides/postgresai-cli-reference.md @@ -3,10 +3,13 @@ title: PostgresAI CLI reference sidebar_label: PostgresAI CLI keywords: - "postgresai cli" + - "pgai cli" - "postgres_ai cli" - "postgres_ai monitoring cli" - "mcp" - "issues" + - "checkup" + - "prepare-db" --- import Tabs from '@theme/Tabs'; @@ -14,11 +17,20 @@ import TabItem from '@theme/TabItem'; ## Description -PostgresAI Command Line Interface (`postgresai`) is a tool for working with postgres_ai monitoring, including authentication, MCP integration, and issue management. +PostgresAI Command Line Interface is a tool for working with PostgresAI: +preparing databases for monitoring, running local monitoring stacks, +generating health-check reports, browsing and managing issues in the +PostgresAI Console, and exposing PostgresAI tools to AI coding clients +over MCP. + +The CLI is published as the `postgresai` npm package and ships two +equivalent binaries: `postgresai` (canonical) and `pgai` (short alias). +Both names accept exactly the same commands and options; this page uses +`postgresai` throughout. ## Getting started -To install and authenticate, see [PostgresAI CLI](/docs/postgresai-howtos/postgresai-cli). +To install and authenticate, see the [PostgresAI CLI how-to](/docs/postgresai-howtos/postgresai-cli). ## Synopsis @@ -27,6 +39,8 @@ To install and authenticate, see [PostgresAI CLI](/docs/postgresai-howtos/postgr ```bash postgresai [global options] [command options] [arguments...] +# or, equivalently: +pgai [global options] [command options] [arguments...] ``` @@ -46,25 +60,43 @@ bunx postgresai [global options] [command options] [arguments...] -Run `postgresai --help` to list available commands and global options. For command-specific help, run `postgresai --help`. +Run `postgresai --help` to list available commands and global options. +For command-specific help, run `postgresai --help` (works for +nested subcommands too, e.g. `postgresai mon targets --help`). + +## Global options + +These options apply to every command and override the corresponding +environment variables and configuration file values: + +- `--api-key ` — API key (overrides `PGAI_API_KEY`). +- `--api-base-url ` — API base URL for backend RPC (overrides `PGAI_API_BASE_URL`; default `https://postgres.ai/api/general/`). +- `--ui-base-url ` — UI base URL for browser routes (overrides `PGAI_UI_BASE_URL`; default `https://console.postgres.ai`). +- `--storage-base-url ` — Storage base URL for file uploads (overrides `PGAI_STORAGE_BASE_URL`). + +Configuration is stored in `~/.config/postgresai/config.json`. ## Command overview ``` COMMANDS: - auth authenticate via browser and store API key locally - init create a monitoring role, required view(s), and grant permissions - mon manage monitoring services - issues manage issue reports in PostgresAI Console - mcp MCP server integration for AI coding tools - add-key store API key locally - show-key show the current API key (masked) - remove-key remove the stored API key + prepare-db prepare a database for monitoring (idempotent) + unprepare-db remove monitoring setup from a database + checkup generate health-check reports directly from PostgreSQL + mon manage the local monitoring stack + auth authenticate and manage the local API key + issues manage issues, comments, and action items in PostgresAI Console + reports list and download checkup reports stored in PostgresAI Console + mcp MCP server integration for AI coding tools + set-default-project store the default project for checkup uploads + set-storage-url store the storage base URL for file uploads + help show help ``` -## Command: `auth` +## Command: `prepare-db` -Authenticate via browser and store the API key locally. +Prepare a database for monitoring: create the monitoring user, the +required view(s), and grant permissions. The command is idempotent. **Usage** @@ -72,405 +104,695 @@ Authenticate via browser and store the API key locally. ```bash -postgresai auth +postgresai prepare-db [conn] [options] ``` ```bash -npx postgresai auth +npx postgresai prepare-db [conn] [options] ``` ```bash -bunx postgresai auth +bunx postgresai prepare-db [conn] [options] ``` -**Notes** +`[conn]` is an optional positional admin connection string. Both URL +form (`postgresql://admin@host:5432/dbname`) and libpq key/value form +(`"dbname=dbname host=host user=admin"`) are accepted; psql-like +options (`-h`, `-p`, `-U`, `-d`) are also supported. -- Configuration is stored in `~/.config/postgresai/config.json`. +**Examples** -## Command: `init` +```bash +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 -Create or update the monitoring role, required view(s), and grant required permissions (idempotent). +# Verify only (no changes) +postgresai prepare-db postgresql://admin@host:5432/dbname --verify -**Usage** +# Dry run: print SQL plan +postgresai prepare-db postgresql://admin@host:5432/dbname --print-sql - - +# Reset only the monitoring role password +postgresai prepare-db postgresql://admin@host:5432/dbname \ + --reset-password --password 'new_password' -```bash -postgresai init +# Supabase mode (uses Management API instead of direct connection) +SUPABASE_ACCESS_TOKEN=... SUPABASE_PROJECT_REF=... \ + postgresai prepare-db --supabase ``` - - +**Connection options** -```bash -npx postgresai init -``` +- `-h, --host ` — PostgreSQL host (psql-like). +- `-p, --port ` — PostgreSQL port (psql-like). +- `-U, --username ` — PostgreSQL admin user (psql-like). +- `-d, --dbname ` — PostgreSQL database name (psql-like). +- `--admin-password ` — admin password (otherwise uses `PGPASSWORD` if set). +- `--db-url ` — admin connection URL (deprecated; pass it as the positional `[conn]` argument). - - +**Monitoring role options** -```bash -bunx postgresai init -``` +- `--monitoring-user ` — monitoring role name to create or update (default: `postgres_ai_monitoring`). +- `--password ` — monitoring role password (overrides `PGAI_MON_PASSWORD`). If neither is provided, a strong password is generated. +- `--print-password` — print the generated monitoring password (dangerous in CI logs). +- `--skip-optional-permissions` — skip optional permissions (RDS / self-managed extras). +- `--provider ` — database provider (e.g. `supabase`); affects which steps run. - - +**Modes** -**Examples** +- `--verify` — verify that the monitoring role and permissions are in place; make no changes. +- `--reset-password` — reset only the monitoring role password. +- `--print-sql` — print the SQL plan and exit; apply no changes. +- `--json` — output the result as machine-readable JSON. - - +**Supabase mode** -```bash -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 -``` +- `--supabase` — use the Supabase Management API instead of a direct PostgreSQL connection. +- `--supabase-access-token ` — Supabase Management API token (or `SUPABASE_ACCESS_TOKEN` env var). Tokens can be created at . +- `--supabase-project-ref ` — Supabase project reference (or `SUPABASE_PROJECT_REF` env var). Auto-detected from a Supabase database URL when one is supplied as `[conn]`. - - +## Command: `unprepare-db` + +Reverse `prepare-db`: drop the monitoring user, views, schema, and +revoke permissions. + +**Usage** ```bash -npx postgresai init postgresql://admin@host:5432/dbname -npx postgresai init "dbname=dbname host=host user=admin" -npx postgresai init -h host -p 5432 -U admin -d dbname +postgresai unprepare-db [conn] [options] ``` - - +**Options** + +- `-h, --host`, `-p, --port`, `-U, --username`, `-d, --dbname`, + `--admin-password`, `--db-url ` (deprecated) — admin connection + parameters, same as `prepare-db`. +- `--monitoring-user ` — monitoring role to remove (default: `postgres_ai_monitoring`). +- `--keep-role` — keep the monitoring role; only revoke permissions and drop objects. +- `--provider ` — database provider (affects which steps run). +- `--print-sql` — print the SQL plan and exit; apply no changes. +- `--force` — skip the confirmation prompt. +- `--json` — output the result as machine-readable JSON. + +## Command: `checkup` + +Generate health-check reports directly from PostgreSQL ("express mode") +and optionally upload them to the PostgresAI Console. + +**Usage** ```bash -bunx postgresai init postgresql://admin@host:5432/dbname -bunx postgresai init "dbname=dbname host=host user=admin" -bunx postgresai init -h host -p 5432 -U admin -d dbname +# Run all checks +postgresai checkup + +# Run a specific check (CHECK_ID matches /^[A-Z]\d{3}$/, e.g. H002) +postgresai checkup ``` - - +`` accepts the same URL / libpq / psql-like forms as +`prepare-db`. -**Common options** +**Options** -- `--verify`: verify that monitoring role/permissions are in place (no changes). -- `--reset-password`: reset monitoring role password only. -- `--print-sql`: print SQL plan and exit (no changes applied). -- `--skip-optional-permissions`: skip optional permissions (managed and self-managed extras). +- `--check-id ` — specific check to run (or `ALL`). Equivalent to passing the check ID as the first positional argument. +- `--node-name ` — node name embedded in reports (default: `node-01`). +- `--output ` — write JSON results to this directory. +- `--upload` / `--no-upload` — upload JSON results to PostgresAI Console (requires API key). Default depends on whether an API key is configured. +- `--project ` — project name or ID for the upload (used with `--upload`). Defaults to the value stored by [`set-default-project`](#command-set-default-project); a project is auto-generated on first run if needed. +- `--json` — print JSON to stdout. +- `--markdown` — print Markdown to stdout. + +Run `postgresai checkup --help` to see the list of available check IDs +and titles bundled with your CLI version. ## Command: `mon` -Manage monitoring services. +Manage the local monitoring stack (Docker Compose-based: collectors, +VictoriaMetrics, Grafana, …). **Usage** - - - ```bash postgresai mon [options] ``` - - +**Subcommands** -```bash -npx postgresai mon [options] -``` +- `local-install` — install the local monitoring stack: generate `.env`, configure services, and start them. +- `start` — start monitoring services. +- `stop` — stop monitoring services. +- `restart [service]` — restart all services or a specific one. +- `status` — show services status. +- `health` — check that services are up and healthy. +- `logs [service]` — show logs for all services or a specific one. +- `config` — show monitoring configuration. +- `update-config` — apply configuration changes (regenerate datasources, …). +- `update` — update the monitoring stack. +- `reset [service]` — reset all services or a specific one (removes data). +- `clean` — clean up monitoring artifacts (stops services and removes volumes). +- `check` — system readiness check. +- `shell ` — open an interactive shell in a monitoring service container. +- `targets` — manage databases to monitor (see below). +- `generate-grafana-password` — generate a new Grafana password. +- `show-grafana-credentials` — show Grafana credentials. - - +### Subcommand: `mon local-install` + +Install (or re-install) the local monitoring stack. Replaces the older +`mon quickstart` name. ```bash -bunx postgresai mon [options] +postgresai mon local-install [options] ``` - - - -**Subcommands** +**Options** -- `quickstart`: complete setup (generate config and start services). -- `start`: start monitoring services. -- `stop`: stop monitoring services. -- `restart [service]`: restart all services or a specific service. -- `status`: show services status. -- `health`: check that services are up and healthy. -- `targets`: manage databases to monitor. -- `logs [service]`: show logs for all or a specific service. -- `config`: show monitoring configuration. -- `update-config`: apply configuration changes (generate sources). -- `update`: update monitoring stack. -- `reset [service]`: reset all or a specific service data. -- `clean`: cleanup artifacts. -- `check`: system readiness check. -- `shell `: open a shell in a monitoring service container. -- `generate-grafana-password`: generate a new Grafana password. -- `show-grafana-credentials`: show Grafana credentials. - -### Subcommand: `quickstart` - -Complete setup (generate config and start monitoring services). +- `--demo` — demo mode with a sample database (for testing; cannot be combined with `--api-key`). +- `--api-key ` — PostgresAI API key for automated report uploads. +- `--db-url ` — PostgreSQL connection URL to monitor (form: `postgresql://user:pass@host:port/db`). +- `--tag ` — Docker image tag to use (e.g. `0.14.0`, `0.14.0-dev.33`). +- `--project ` — Docker Compose project name (default: `postgres_ai`). +- `-y, --yes` — accept all defaults and skip interactive prompts. -**Usage** +`local-install` writes `.env` in the monitoring directory, preserving +existing `REPLICATOR_PASSWORD` and `VM_AUTH_*` values or generating new +random ones when missing. `VM_AUTH_USERNAME` defaults to `vmauth` when +absent. The replication password is used by the demo PostgreSQL standby, +and the VM auth credentials are required before Docker Compose can +provision Grafana datasources. To rotate VM auth credentials manually, +run `VM_AUTH_PASSWORD="$(openssl rand -base64 18)" ./scripts/rotate-vm-auth.sh` +from the monitoring directory. - - +### Subcommand: `mon health` ```bash -postgresai mon quickstart [--demo] [--api-key ] [--db-url ] [-y] +postgresai mon health [--wait ] ``` - - +- `--wait ` — wait up to `` for services to become healthy (default: `0`, i.e. check once and return). + +### Subcommand: `mon logs` ```bash -npx postgresai mon quickstart [--demo] [--api-key ] [--db-url ] [-y] +postgresai mon logs [service] [options] ``` - - +- `-f, --follow` — follow logs. +- `--tail ` — number of trailing lines (default: `all`). + +### Subcommand: `mon clean` ```bash -bunx postgresai mon quickstart [--demo] [--api-key ] [--db-url ] [-y] +postgresai mon clean [--keep-volumes] ``` - - - -### Subcommand group: `targets` +- `--keep-volumes` — keep data volumes (only stop and remove containers). -Manage databases to monitor. +### Subcommand group: `mon targets` -**Usage** - - - +Manage databases monitored by the local stack. ```bash postgresai mon targets [args] ``` - - +**Subcommands** + +- `list` — list configured monitoring targets. +- `add [conn-string] [name]` — add a Postgres instance to monitor. Both arguments are optional; missing values are prompted for interactively. +- `remove ` — remove a monitoring target. +- `test ` — test connectivity to a configured target. + +## Command: `auth` + +Authentication and API-key management. `auth` is a command group; the +default subcommand is `login`, so plain `postgresai auth` triggers an +OAuth flow. + +**Usage** ```bash -npx postgresai mon targets [args] +postgresai auth [subcommand] [options] ``` - - +**Subcommands** + +- `login` (default) — authenticate via browser (OAuth) or store an API key directly. +- `show-key` — show the current API key, masked. +- `remove-key` — remove the stored API key. + +### Subcommand: `auth login` ```bash -bunx postgresai mon targets [args] +postgresai auth # OAuth via browser +postgresai auth --set-key # store an API key directly +postgresai auth login --port 7777 --debug # explicit form ``` - - +**Options** -**Subcommands** +- `--set-key ` — store an API key directly without going through the OAuth flow. +- `--port ` — local callback server port (default: random). +- `--debug` — enable debug output. -- `list`: list configured monitoring targets. -- `add [name]`: add a Postgres instance to monitor. -- `remove `: remove a monitoring target. -- `test `: test connectivity to a configured target. +The browser flow opens your default browser, prompts for organization +selection, and writes the resulting API key to +`~/.config/postgresai/config.json`. ## Command: `issues` -Manage issue reports in PostgresAI Console. +Manage issues, comments, and action items in the PostgresAI Console. **Usage** - - - ```bash postgresai issues [options] ``` - - +All `issues` subcommands accept `--debug` (enable debug output) and +`--json` (force raw JSON output instead of the default human-friendly +YAML). When stdout is not a TTY (e.g. piped or redirected), JSON is +selected automatically. + +**Subcommands** + +- `list` — list issues. +- `view ` — view issue details and comments. +- `create [options]` — create a new issue. +- `update <issueId> [options]` — update an existing issue. +- `post-comment <issueId> <content> [options]` — post a comment. +- `update-comment <commentId> <content> [options]` — update an existing comment. +- `files upload <path>` — upload a file to storage and print a markdown link. +- `files download <url> [-o <path>]` — download a file from storage. +- `action-items <issueId>` — list action items for an issue. +- `view-action-item <id> [<id> ...]` — view one or more action items in detail. +- `create-action-item <issueId> <title> [options]` — create an action item. +- `update-action-item <actionItemId> [options]` — update an action item. + +### `issues list` ```bash -npx postgresai issues <subcommand> [options] +postgresai issues list [--status <status>] [--limit <n>] [--offset <n>] ``` -</TabItem> -<TabItem value="bunx" label="bunx"> +- `--status <status>` — filter by status: `open`, `closed`, or `all` (default: `all`). +- `--limit <n>` — maximum number of issues to return (default: `20`). +- `--offset <n>` — number of issues to skip (default: `0`). + +### `issues view` ```bash -bunx postgresai issues <subcommand> [options] +postgresai issues view <issueId> ``` -</TabItem> -</Tabs> +### `issues create` -**Subcommands** +```bash +postgresai issues create <title> [options] +``` -- `list`: list issues. -- `view <issue_id>`: view issue details (and comments). -- `post_comment <issue_id> <content>`: post a comment to an issue. +- `--org-id <id>` — organization ID (defaults to the configured `orgId`). +- `--project-id <id>` — project ID. +- `--description <text>` — issue description (use `\n` for newlines). +- `--label <label>` — issue label; repeat to add multiple. +- `--attach <path>` — attach a local file (uploads to storage and appends a markdown link to the description); repeatable. -**Examples** +### `issues update` -<Tabs groupId="cli-runner" queryString> -<TabItem value="cli" label="Installed CLI" default> +```bash +postgresai issues update <issueId> [options] +``` + +- `--title <text>` — new title (use `\n` for newlines). +- `--description <text>` — new description (use `\n` for newlines). +- `--status <value>` — `open`, `closed`, `0`, or `1`. +- `--label <label>` — set labels; repeatable. If provided, replaces existing labels. +- `--clear-labels` — set labels to an empty list. +- `--attach <path>` — attach a file; appends a markdown link to `--description`. If `--description` is omitted, the existing description is fetched and the link appended to it. + +### `issues post-comment` ```bash -postgresai issues list -postgresai issues view <issue_id> -postgresai issues post_comment <issue_id> "comment" +postgresai issues post-comment <issueId> <content> [options] ``` -</TabItem> -<TabItem value="npx" label="npx"> +- `--parent <uuid>` — parent comment ID (for threaded replies). +- `--attach <path>` — attach a file; appends a markdown link to the comment body. Repeatable. + +### `issues update-comment` ```bash -npx postgresai issues list -npx postgresai issues view <issue_id> -npx postgresai issues post_comment <issue_id> "comment" +postgresai issues update-comment <commentId> <content> [options] ``` -</TabItem> -<TabItem value="bunx" label="bunx"> +- `--attach <path>` — attach a file; appends a markdown link to `<content>`. Repeatable. + +### `issues files` ```bash -bunx postgresai issues list -bunx postgresai issues view <issue_id> -bunx postgresai issues post_comment <issue_id> "comment" +# Upload a local file; prints the storage URL and a ready-to-paste markdown link. +postgresai issues files upload <path> + +# Download a file from storage; without -o, derives the filename from the URL. +postgresai issues files download <url> [-o <output_path>] ``` -</TabItem> -</Tabs> +#### Attaching files to issues and comments (`--attach`) -## Command: `mcp` +`create`, `update`, `post-comment`, and `update-comment` accept a +repeatable `--attach <path>` flag. Each file is uploaded to PostgresAI +storage and a markdown link is appended to the comment body or issue +description. Image extensions (`.png`, `.jpg`, `.jpeg`, `.gif`, +`.webp`, `.svg`, `.bmp`, `.ico`) render inline as `![](url)`; other +files render as `[](url)`. Multiple `--attach` flags preserve order; +each link goes on its own line. -MCP server integration for AI coding tools. +```bash +# Attach a screenshot to a new comment +postgresai issues post-comment <issueId> "Saw this in prod" --attach screenshot.png -**Usage** +# Attach multiple files to a new issue +postgresai issues create "Slow query" --org-id 4 \ + --description "Plan attached" --attach plan.txt --attach flame.svg -<Tabs groupId="cli-runner" queryString> -<TabItem value="cli" label="Installed CLI" default> +# Attach a file to an existing issue without changing the description +postgresai issues update <issueId> --attach trace.log +``` + +### `issues action-items` ```bash -postgresai mcp <subcommand> [options] +postgresai issues action-items <issueId> +postgresai issues view-action-item <actionItemId> [<actionItemId> ...] ``` -</TabItem> -<TabItem value="npx" label="npx"> +### `issues create-action-item` ```bash -npx postgresai mcp <subcommand> [options] +postgresai issues create-action-item <issueId> <title> [options] ``` -</TabItem> -<TabItem value="bunx" label="bunx"> +- `--description <text>` — detailed description (use `\n` for newlines). +- `--sql-action <sql>` — SQL command to execute. +- `--config <json>` — config change as JSON, e.g. `'{"parameter":"work_mem","value":"64MB"}'`. Repeatable. + +### `issues update-action-item` ```bash -bunx postgresai mcp <subcommand> [options] +postgresai issues update-action-item <actionItemId> [options] ``` -</TabItem> -</Tabs> +- `--title <text>`, `--description <text>` — update title or description. +- `--done` / `--not-done` — mark as done or not done. +- `--status <value>` — `waiting_for_approval`, `approved`, or `rejected`. +- `--status-reason <text>` — reason for the status change. +- `--sql-action <sql>` — update the SQL command (use `""` to clear). +- `--config <json>` — replace config changes; repeatable. +- `--clear-configs` — remove all config changes. -**Subcommands** +### Output format for `issues` commands + +By default, `issues` commands print human-friendly YAML to a terminal. +For scripting: + +- Pass `--json` to force JSON output: -- `start`: start the MCP server in stdio mode. -- `install [client]`: install MCP client configuration for a supported tool. + ```bash + postgresai issues list --json | jq '.[] | {id, title}' + ``` -## Command: `add-key` +- Or rely on auto-detection: when stdout is not a TTY, output is JSON + automatically: -Store an API key locally. + ```bash + postgresai issues view <issueId> > issue.json + ``` + +## Command: `reports` + +List and download checkup reports stored in the PostgresAI Console. **Usage** -<Tabs groupId="cli-runner" queryString> -<TabItem value="cli" label="Installed CLI" default> +```bash +postgresai reports <subcommand> [options] +``` + +**Subcommands** + +- `list [options]` — list checkup reports. +- `files [reportId] [options]` — list files (metadata only) of a checkup report. +- `data [reportId] [options]` — fetch report file contents (markdown / JSON). + +### `reports list` ```bash -postgresai add-key <key> +postgresai reports list [options] ``` -</TabItem> -<TabItem value="npx" label="npx"> +- `--project-id <id>` — filter by project ID. +- `--limit <n>` — maximum number of reports to return (default: `20`, max: `100`). +- `--before <date>` — show reports created before this date (`YYYY-MM-DD`, `DD.MM.YYYY`, etc.). +- `--all` — fetch all reports (paginated automatically). Mutually exclusive with `--before`. +- `--json` — output raw JSON. + +### `reports files` ```bash -npx postgresai add-key <key> +postgresai reports files [reportId] [options] ``` -</TabItem> -<TabItem value="bunx" label="bunx"> +Either `reportId` or `--check-id` is required. + +- `--type <type>` — filter by file type: `json` or `md`. +- `--check-id <id>` — filter by check ID (e.g. `H002`). +- `--json` — output raw JSON. + +### `reports data` ```bash -bunx postgresai add-key <key> +postgresai reports data [reportId] [options] ``` -</TabItem> -</Tabs> +- `--type <type>` — filter by file type: `json` or `md`. +- `--check-id <id>` — filter by check ID (e.g. `H002`). +- `--formatted` — render markdown with ANSI styling (experimental). +- `-o, --output <dir>` — save files to a directory (using their original filenames). +- `--json` — output raw JSON. -## Command: `show-key` +## Command: `mcp` -Show the currently configured API key (masked). +MCP (Model Context Protocol) server integration for AI coding tools. **Usage** -<Tabs groupId="cli-runner" queryString> -<TabItem value="cli" label="Installed CLI" default> - ```bash -postgresai show-key +postgresai mcp <subcommand> [options] ``` -</TabItem> -<TabItem value="npx" label="npx"> +**Subcommands** + +- `start` — start the MCP stdio server, exposing PostgresAI tools. +- `install [client]` — install MCP client configuration for a supported AI coding tool. + +### `mcp start` ```bash -npx postgresai show-key +postgresai mcp start [--debug] ``` -</TabItem> -<TabItem value="bunx" label="bunx"> +Starts an MCP server over stdio. Intended to be launched by an MCP +client (e.g. Cursor, Claude Code) rather than invoked directly. + +### `mcp install` ```bash -bunx postgresai show-key +postgresai mcp install [client] ``` -</TabItem> -</Tabs> +Installs an `mcpServers.postgresai` entry pointing at the current +`postgresai` binary, with `mcp start` as its arguments. -## Command: `remove-key` +`client` may be one of: -Remove the stored API key. +- `cursor` — writes to `~/.cursor/mcp.json`. +- `claude-code` — runs `claude mcp add -s user postgresai <pgai> mcp start`. +- `windsurf` — writes to `~/.windsurf/mcp.json`. +- `codex` — writes to `~/.codex/mcp.json`. -**Usage** +If `client` is omitted, you are prompted to choose interactively +(1=Cursor, 2=Claude Code, 3=Windsurf, 4=Codex). -<Tabs groupId="cli-runner" queryString> -<TabItem value="cli" label="Installed CLI" default> +A typical Cursor entry looks like: + +```json +{ + "mcpServers": { + "postgresai": { + "command": "postgresai", + "args": ["mcp", "start"], + "env": { + "PGAI_API_BASE_URL": "https://postgres.ai/api/general/" + } + } + } +} +``` + +**MCP tools exposed** + +- `list_issues` — same JSON as `postgresai issues list`. +- `view_issue` — view a single issue with its comments. +- `create_issue` — create a new issue. +- `update_issue` — update title / description / status / labels. +- `post_issue_comment` — post a comment. +- `update_issue_comment` — update an existing comment. +- `upload_file` — upload a local file and return the storage URL plus a ready-to-paste markdown link. +- `download_file` — download a file from storage. + +The issue / comment tools accept an optional `attachments: string[]` of +local file paths. Each file is uploaded to PostgresAI storage and the +resulting markdown link is appended to the comment body or issue +description, using the same image-extension rules as the `--attach` +CLI flag. + +For `post_issue_comment` and `update_issue_comment`, either `content` or +`attachments` must be non-empty (attachments alone are allowed). For +`update_issue` with `attachments` but no `description`, the existing +description is fetched first and the new links are appended to it. + +#### MCP threat model + +The MCP server runs in your local user account with your PostgresAI API +key. It treats the connected MCP client (the LLM agent) as **trusted** — +the same way the CLI treats you when you type a command. In particular: + +- `upload_file` and the `attachments: string[]` parameter on the issue / + comment tools read **any local file the CLI process can read**, + including secrets like `~/.ssh/id_rsa`, `~/.aws/credentials`, or + `~/.config/postgresai/config.json` (which contains your own API + key). The file's bytes are uploaded to PostgresAI storage and the + resulting URL becomes visible to anyone with read access to the + issue or comment it ends up in. +- `download_file` writes to **any path the CLI process can write to** + when `output_path` is supplied (`~/.ssh/authorized_keys`, + `~/.bashrc`, etc. are all fair game). When `output_path` is omitted, + downloads are restricted to the current working directory. + +This is fine when the agent and the upstream context the agent is +reading are trusted. It is **not** safe to run this MCP server against +an agent that is processing untrusted text (issue bodies, comments, web +pages, third-party docs) without additional sandboxing — a +prompt-injection in any input the agent reads could be used to +exfiltrate local secrets or write arbitrary files. If you need to +expose this MCP server to such an agent, run the agent (and this +server) in a container or restricted user account that has no access +to anything sensitive. + +## Command: `set-default-project` + +Store the default project used for `checkup` uploads and other +project-scoped operations. ```bash -postgresai remove-key +postgresai set-default-project <project> ``` -</TabItem> -<TabItem value="npx" label="npx"> +## Command: `set-storage-url` + +Store the storage base URL used for file uploads. Equivalent to setting +`PGAI_STORAGE_BASE_URL` permanently in the configuration file. ```bash -npx postgresai remove-key +postgresai set-storage-url <url> ``` -</TabItem> -<TabItem value="bunx" label="bunx"> +## Configuration + +The CLI stores configuration in `~/.config/postgresai/config.json`, +including: + +- API key +- API / UI / storage base URLs +- Organization ID +- Default project + +### 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` in `~/.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`. +- Storage base URL (`storageBaseUrl`): + 1. Command-line option (`--storage-base-url`). + 2. Environment variable (`PGAI_STORAGE_BASE_URL`). + 3. Value stored by `postgresai set-storage-url`. + +A single trailing `/` is stripped from URL values to ensure consistent +path joining. + +### Environment variables + +- `PGAI_API_KEY` — API key for PostgresAI services. +- `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`). +- `PGAI_STORAGE_BASE_URL` — storage endpoint for file uploads. +- `PGAI_MON_PASSWORD` — default password for the monitoring role created by `prepare-db`. +- `PGPASSWORD` — admin password used by `prepare-db` / `unprepare-db` when `--admin-password` is not given. +- `SUPABASE_ACCESS_TOKEN`, `SUPABASE_PROJECT_REF` — credentials for `prepare-db --supabase`. + +### Examples + +For production (uses default URLs): ```bash -bunx postgresai remove-key +postgresai auth --debug ``` -</TabItem> -</Tabs> +For staging / development environments: + +```bash +# Linux / macOS (bash, zsh) +export PGAI_API_BASE_URL=https://v2.postgres.ai/api/general/ +export PGAI_UI_BASE_URL=https://console-dev.postgres.ai +postgresai auth --debug +``` + +```powershell +# Windows PowerShell +$env:PGAI_API_BASE_URL = "https://v2.postgres.ai/api/general/" +$env:PGAI_UI_BASE_URL = "https://console-dev.postgres.ai" +postgresai auth --debug +``` + +Via CLI options (overrides environment variables): + +```bash +postgresai auth --debug \ + --api-base-url https://v2.postgres.ai/api/general/ \ + --ui-base-url https://console-dev.postgres.ai +```