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 ../safe-orchestrator/SKILL.md for a full assessment.

Two AGENTS.md files (do not confuse them)

Do not edit project AGENTS.md without operator approval (see ../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 ../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.