planetscale-pscale-cli-automation
Use a CLI do PlanetScale (pscale) a partir de agentes automatizados com --format json, verificação de autenticação, pscale sql e --force por comando. Execute antes de outras habilidades do PlanetScale…
npx skills add https://github.com/planetscale/skills --skill planetscale-pscale-cli-automationPlanetScale 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
../planetscale-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
../planetscale-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 jsonfor automation. - Put
--org <org>on resource subcommands (database,branch,sql,api, …) — not on rootpscale. - Put positional arguments before flags (
pscale sql mydb main --org bb …). - Use
pscale sql, notpscale shell(shell requires a TTY). - Default SQL role is reader; pass
--role admin(or writer/readwriter) for writes. Matchpscale shellsemantics for--roleand--replica. --forceis per subcommand only (e.g.database delete … --force,pscale sql … --force). There is no global--forceorPSCALE_FORCE.--format jsonalone never skips confirmations — add--forceon 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 jsonfor the current URL). - Shell scripts and coding agents — use
pscalewith--format jsonas 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 ../planetscale-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.