Merge pull request #1280 from planetscale/cli/agent-onboarding

Make pscale agent-friendly: JSON auth, sql command, AGENTS.md

Author: no-itsbackpack

AGENTS.md

@@ -0,0 +1,187 @@
+# PlanetScale CLI — agent guide
+
+For **any** automated agent or script using `pscale`. Always pass **`--format json`**. Substitute placeholders from the user's request or from prior command output (`org list`, `database list`, `branch list`).
+
+If you only have the installed `pscale` binary, start here:
+
+```bash
+pscale agent-guide --format json
+pscale auth check --format json
+```
+
+Use direct CLI automation for shell commands and scripts. Use the hosted PlanetScale MCP server for MCP clients.
+
+This file documents **how to invoke `pscale`**. For database assessment, safety review, and operational workflows, install the [PlanetScale skills pack](https://github.com/planetscale/skills) (`14-pscale-cli-automation` covers CLI automation; `00-safe-orchestrator` runs the full review). In application repositories, add a separate **project** `AGENTS.md` with org, database, branch, and approval rules (see skill `09-mcp-agent-operating-model` in that repo).
+
+| Placeholder | Meaning |
+|-------------|---------|
+| `<org>` | Organization name |
+| `<database>` | Database name |
+| `<branch>` | Branch name (pick one with `"ready": true` from `branch list`) |
+
+## Flag placement
+
+- **`--org`** is a flag on resource subcommands (`database`, `branch`, `sql`, `api`, …). It is **not** on root `pscale` — `pscale --org …` fails.
+- **`--format json`** is a global flag. It can go on `pscale` or on the subcommand.
+- Commands with positional args (`sql`, `branch list`, …): put **positionals first**, then flags.
+
+```bash
+# Correct
+pscale auth check --format json
+pscale org list --format json
+pscale database list --org <org> --format json
+pscale branch list <database> --org <org> --format json
+pscale sql <database> <branch> --org <org> --format json --query "SELECT 1"
+
+# Also valid — global --format
+pscale --format json database list --org <org>
+
+# Wrong — unknown flag: --org
+pscale --org <org> database list --format json
+```
+
+## Workflow
+
+1. **Guide** — discover machine-readable conventions when you do not have this file:
+
+   ```bash
+   pscale agent-guide --format json
+   ```
+
+2. **Auth** — check before anything else:
+
+   ```bash
+   pscale auth check --format json
+   ```
+
+   `"status": "ok"` and `"authenticated": true` with no blocking `issues` means proceed. `"status": "action_required"` exits non-zero — log in, pick an org, or fix credentials (see `issues` and `next_steps`).
+
+3. **Login** (when not authenticated):
+
+   ```bash
+   pscale auth login --format json
+   ```
+
+   Pending JSON is written to **stderr** while waiting; **stdout** has a single final JSON object when login completes (`status: ok` or `action_required` if org setup fails after credentials are saved). Fields include `verification_url`, `user_code`, and `browser_opened`. Open `verification_url` manually if the browser does not open. Do not retry login in a loop without browser access.
+
+4. **Organization** — use `"organization"` from `auth check`, ask the user, or list orgs:
+
+   ```bash
+   pscale org list --format json
+   ```
+
+   Pass `--org <org>` on resource commands (`database`, `branch`, `sql`, `api`, …). Not on `org list`.
+
+5. **Discover resources** before SQL:
+
+   ```bash
+   pscale database list --org <org> --format json
+   pscale branch list <database> --org <org> --format json
+   ```
+
+6. **Query** (read-only default):
+
+   ```bash
+   pscale sql <database> <branch> --org <org> --format json --query "SELECT 1"
+   ```
+
+## Flags
+
+| Flag | Purpose |
+|------|---------|
+| `--format json` | JSON on stdout |
+| `--org <org>` | Organization (on resource subcommands only) |
+| `--api-url` | Non-production API base URL — pass on every command when not using production |
+
+## Authentication
+
+`pscale auth login` stores credentials in the OS keychain; agents on the same machine reuse them.
+
+Headless / CI: pass `--service-token-id` and `--service-token` on the subcommand that needs auth.
+
+## SQL
+
+Non-interactive queries. Default **`--role` is `reader`** (unlike `pscale shell`, which defaults to admin). Use `pscale shell` for interactive sessions.
+
+```bash
+# Read (default)
+pscale sql <database> <branch> --org <org> --format json --query "SELECT 1"
+
+# Read from replica
+pscale sql <database> <branch> --org <org> --format json --replica --query "SELECT 1"
+
+# PostgreSQL — optional --dbname (default postgres)
+pscale sql <database> <branch> --org <org> --format json --query "SELECT 1"
+
+# MySQL multi-keyspace — optional --keyspace (default @primary)
+pscale sql <database> <branch> --org <org> --format json --keyspace <keyspace> --query "SELECT 1"
+```
+
+| Flag | Purpose |
+|------|---------|
+| `--role` | `reader` (default), `writer`, `readwriter`, `admin` — same names as `pscale shell` |
+| `--replica` | Route reads to replicas |
+| `--dbname` | PostgreSQL database name (default `postgres`) |
+| `--keyspace` | MySQL keyspace (default `@primary`) |
+| `--force` | Allow destructive SQL after explicit user approval |
+
+**`--role` by engine** (same as `pscale shell`):
+
+| `--role` | MySQL (Vitess) | PostgreSQL |
+|----------|----------------|------------|
+| `reader` | Branch password, reader role | Ephemeral role inheriting `pg_read_all_data` |
+| `writer` | Branch password, writer role | Role inheriting `pg_write_all_data` |
+| `readwriter` | Branch password, readwriter role | Role inheriting read + write |
+| `admin` | Branch password, admin role | Role inheriting `postgres` |
+
+### Destructive SQL
+
+`DELETE`, `DROP`, and `TRUNCATE` anywhere in a query are blocked by default (word match, not substring — `deleted_at` is fine). Returns `"status": "action_required"` with `"query_kind": "destructive"`.
+
+1. Ask the user to approve the query.
+2. Re-run with `--force` only after they approve:
+
+```bash
+pscale sql <database> <branch> --org <org> --format json --force --query "DELETE FROM ..."
+```
+
+Never use `--force` without explicit user approval.
+
+### SQL JSON
+
+Success: `status`, `database`, `branch`, `kind` (`mysql` or `postgresql`), `role`, `row_count`, `columns`, `rows`; `replica` when `--replica` was used.
+
+MySQL may return synthetic column names (e.g. `:vtg1 /* INT64 */`). PostgreSQL may use names like `?column?`.
+
+Error: one JSON object on stdout with `status: "error"`, `error`, and `next_steps`.
+
+Destructive SQL without `--force`: `status: "action_required"`, `query_kind: "destructive"`, `issues`, and `next_steps` (includes `--force` retry command).
+
+## API passthrough
+
+```bash
+pscale api --org <org> organizations/<org>/databases
+```
+
+## MCP
+
+For MCP clients, use the hosted PlanetScale MCP server:
+
+```text
+https://mcp.pscale.dev/mcp/planetscale
+```
+
+See the current MCP docs: https://planetscale.com/docs/connect/mcp
+
+Do not use the deprecated local `pscale mcp server` path unless you explicitly need backward compatibility with an old setup.
+
+## PlanetScale agent skills
+
+Operational workflows (inventory, safety review, Insights, schema recommendations, Traffic Control) live in the public skills repo — not in this file.
+
+```bash
+git clone https://github.com/planetscale/skills.git && cd skills && script/setup
+# or: npx skills add planetscale/skills -g -y
+```
+
+After installing skills, load `14-pscale-cli-automation` for CLI conventions (or re-run `pscale agent-guide --format json` from any `pscale` binary that includes agent onboarding). Use `00-safe-orchestrator` when the user asks for a full PlanetScale assessment.

README.md

@@ -124,3 +124,7 @@ And then use the `pscale` binary built in `cmd/pscale/` for testing:
 ## Documentation
 
 Please checkout our Documentation page: [planetscale.com/docs](https://planetscale.com/docs/reference/planetscale-cli)
+
+For AI agents and automation, run `pscale agent-guide` or see [AGENTS.md](./AGENTS.md).
+For operational workflows (inventory, safety review, schema recommendations), install
+[planetscale/skills](https://github.com/planetscale/skills).

agentguide_content.go

@@ -0,0 +1,8 @@
+package cli
+
+import _ "embed"
+
+// AgentGuide is the embedded agent guide shipped with the pscale binary.
+//
+//go:embed AGENTS.md
+var AgentGuide string

internal/cmd/agentguide/agentguide.go

@@ -0,0 +1,81 @@
+package agentguide
+
+import (
+	"github.com/spf13/cobra"
+
+	clicontent "github.com/planetscale/cli"
+	"github.com/planetscale/cli/internal/cmdutil"
+	"github.com/planetscale/cli/internal/printer"
+)
+
+const (
+	HostedMCPURL        = "https://mcp.pscale.dev/mcp/planetscale"
+	MCPDocsURL          = "https://planetscale.com/docs/connect/mcp"
+	SkillsRepoURL       = "https://github.com/planetscale/skills"
+	SkillsSetupCmd      = "git clone https://github.com/planetscale/skills.git && cd skills && script/setup"
+	SkillsNPXInstall    = "npx skills add planetscale/skills -g -y"
+	SkillsCLIAutomation = "14-pscale-cli-automation"
+)
+
+type response struct {
+	Status              string   `json:"status"`
+	Guide               string   `json:"guide"`
+	FirstCommand        string   `json:"first_command"`
+	AgentGuideCommand   string   `json:"agent_guide_command"`
+	HostedMCPURL        string   `json:"hosted_mcp_url"`
+	MCPDocsURL          string   `json:"mcp_docs_url"`
+	SkillsRepoURL       string   `json:"skills_repo_url"`
+	SkillsSetupCommand  string   `json:"skills_setup_command"`
+	SkillsNPXCommand    string   `json:"skills_npx_command"`
+	SkillsCLIAutomation string   `json:"skills_cli_automation_skill"`
+	SupportedEngines    []string `json:"supported_engines"`
+	Conventions         []string `json:"conventions"`
+	NextSteps           []string `json:"next_steps"`
+}
+
+// AgentGuideCmd prints the embedded guide for agents and automation.
+func AgentGuideCmd(ch *cmdutil.Helper) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "agent-guide",
+		Short: "Show guidance for AI agents and automation",
+		Long: `Show guidance for AI agents and automation using pscale.
+
+Use --format json for a machine-readable bootstrap response with first commands,
+supported engines, hosted MCP details, and PlanetScale skills install hints.`,
+		Args: cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if ch.Printer.Format() == printer.JSON {
+				return ch.Printer.PrintJSON(response{
+					Status:              "ok",
+					Guide:               clicontent.AgentGuide,
+					FirstCommand:        cmdutil.AgentAuthCheckCmd(),
+					AgentGuideCommand:   cmdutil.AgentGuideCmd(),
+					HostedMCPURL:        HostedMCPURL,
+					MCPDocsURL:          MCPDocsURL,
+					SkillsRepoURL:       SkillsRepoURL,
+					SkillsSetupCommand:  SkillsSetupCmd,
+					SkillsNPXCommand:    SkillsNPXInstall,
+					SkillsCLIAutomation: SkillsCLIAutomation,
+					SupportedEngines:    []string{"mysql", "postgresql"},
+					Conventions: []string{
+						"Always pass --format json for automation",
+						"Put --org on resource subcommands, not on pscale root",
+						"Put positional arguments before flags for commands like sql and branch list",
+						"Use hosted MCP for MCP clients; direct CLI automation should start with auth check",
+						"Install planetscale/skills for operational workflows; this guide covers pscale invocation only",
+						"Project AGENTS.md is for org/database/branch targeting — separate from the CLI agent guide",
+					},
+					NextSteps: []string{
+						cmdutil.AgentAuthCheckCmd(),
+						SkillsSetupCmd,
+					},
+				})
+			}
+
+			ch.Printer.Print(clicontent.AgentGuide)
+			return nil
+		},
+	}
+
+	return cmd
+}

internal/cmd/agentguide/agentguide_test.go

@@ -0,0 +1,53 @@
+package agentguide
+
+import (
+	"bytes"
+	"encoding/json"
+	"testing"
+
+	"github.com/planetscale/cli/internal/cmdutil"
+	"github.com/planetscale/cli/internal/printer"
+)
+
+func TestAgentGuideJSONBootstrap(t *testing.T) {
+	format := printer.JSON
+	var out bytes.Buffer
+	ch := &cmdutil.Helper{
+		Printer: printer.NewPrinter(&format),
+	}
+	ch.Printer.SetResourceOutput(&out)
+
+	cmd := AgentGuideCmd(ch)
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("execute: %v", err)
+	}
+
+	var resp response
+	if err := json.Unmarshal(out.Bytes(), &resp); err != nil {
+		t.Fatalf("json: %v", err)
+	}
+	if resp.Status != "ok" {
+		t.Fatalf("status = %q", resp.Status)
+	}
+	if resp.FirstCommand != cmdutil.AgentAuthCheckCmd() {
+		t.Fatalf("first command = %q", resp.FirstCommand)
+	}
+	if resp.HostedMCPURL != HostedMCPURL {
+		t.Fatalf("hosted MCP URL = %q", resp.HostedMCPURL)
+	}
+	if resp.SkillsRepoURL != SkillsRepoURL {
+		t.Fatalf("skills repo URL = %q", resp.SkillsRepoURL)
+	}
+	if resp.SkillsSetupCommand != SkillsSetupCmd {
+		t.Fatalf("skills setup command = %q", resp.SkillsSetupCommand)
+	}
+	if resp.SkillsCLIAutomation != SkillsCLIAutomation {
+		t.Fatalf("skills CLI automation skill = %q", resp.SkillsCLIAutomation)
+	}
+	if len(resp.NextSteps) < 2 || resp.NextSteps[1] != SkillsSetupCmd {
+		t.Fatalf("next_steps = %#v", resp.NextSteps)
+	}
+	if resp.Guide == "" {
+		t.Fatal("expected embedded guide")
+	}
+}