Planetscale Pscale CLI Automation Agent Skill

PlanetScale CLI automation

Purpose

Teach agents how to invoke pscale non-interactively. This skill covers **CLI

conventions only**. Operational workflows (inventory, safety review, schema

recommendations) use the other skills in this repo — start with

../00-safe-orchestrator/SKILL.md for a full assessment.

Two AGENTS.md files (do not confuse them)

| Document | Where | Purpose |

|----------|-------|---------|

| CLI agent guide | Shipped with pscale (AGENTS.md in the CLI repo, or pscale agent-guide) | How to call pscale: auth, --format json, flag placement, pscale sql |

| Project agent guide | Your application repository's AGENTS.md | Which org, database, branch, engine, prod branch, MCP scope, approval rules |

Do not edit project AGENTS.md without operator approval (see

../09-mcp-agent-operating-model/SKILL.md).

Bootstrap (always start here)

pscale agent-guide --format json
pscale auth check --format json

If auth check returns "status": "action_required", follow issues and

next_steps in the JSON. For login, the human may need to approve in the

browser; use pscale auth login --format json.

Conventions

• Always pass --format json for automation.
• Put --org <org> on resource subcommands (database, branch, sql,

api, …) — not on root pscale.

• Put positional arguments before flags (pscale sql mydb main --org bb …).
• Use pscale sql, not pscale shell (shell requires a TTY).
• Default SQL role is reader; pass --role admin (or writer/readwriter) for

writes. Match pscale shell semantics for --role and --replica.

• --force is per subcommand only (e.g. database delete … --force, `pscale

sql … --force). There is no global --force or PSCALE_FORCE`.

• --format json alone never skips confirmations — add --force on the

destructive subcommand after explicit user approval.

Typical workflow

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"

MySQL uses @primary by default (same as pscale shell); pass --keyspace only

for multi-keyspace databases.

MCP vs CLI

• MCP clients — use the hosted PlanetScale MCP server (see `pscale agent-guide

--format json` for the current URL).

• Shell scripts and coding agents — use pscale with --format json as above.

When this skill is not enough

Install the full PlanetScale skills pack (if not already):

git clone https://github.com/planetscale/skills.git && cd skills && script/setup
# or: npx skills add planetscale/skills -g -y

Then run sub-skills or ../00-safe-orchestrator/SKILL.md for database operations

beyond basic CLI invocation.

Current conventions source of truth

Prefer live output over memorized flag syntax:

pscale agent-guide --format json

The embedded guide field contains the full CLI agent guide shipped with your

pscale binary.