mcpField
P
planetscale-pscale-cli-automation

planetscale-pscale-cli-automation

github.com/planetscaleData & databases1361.7k installsUpdated 8w ago
Repository

About planetscale-pscale-cli-automation

A skill for coding agents and shell automation that documents non-interactive PlanetScale CLI usage, including JSON output, authentication checks, and safe flag placement. It focuses on CLI conventions rather than database operations.

Key features

  1. 01JSON-first CLI conventions
  2. 02Authentication bootstrap steps
  3. 03Resource command flag placement
  4. 04SQL invocation and role guidance
  5. 05Destructive command approval rules

Use cases

  1. 01Automating PlanetScale checks in shell scripts
  2. 02Guiding coding agents through CLI authentication
  3. 03Running database queries without an interactive shell

MCP support

For MCP clients, the skill directs users to the hosted PlanetScale MCP server and its current URL. For shell scripts and coding agents, it recommends using `pscale` with JSON output.

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/planetscale/skills --skill planetscale-pscale-cli-automation

After installing, type/planetscale-pscale-cli-automationin Claude Code to confirm it loaded.

Details

From the project README

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

Two AGENTS.md files (do not confuse them)

DocumentWherePurpose
CLI agent guideShipped 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 guideYour application repository's AGENTS.mdWhich 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 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 ../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.

Comments

Markdown supported