Planetscale Pscale CLI Automation — Agent Skill by PlanetScale

From the author

Use the PlanetScale CLI (pscale) from automated agents with --format json, auth check, pscale sql, and per-command --force. Run before other PlanetScale skills when driving pscale directly. Use when the user asks to automate pscale, run CLI commands headless, or verify pscale auth from an agent.

— the description by PlanetScale

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides essential conventions for integrating the PlanetScale CLI into automated agent workflows. It focuses on non-interactive execution, ensuring that agents correctly handle authentication, JSON formatting, and command-line flag placement. By following these patterns, developers can reliably script database operations, perform health checks, and execute SQL queries without requiring a TTY or manual intervention.

What it does

Standardizes the use of --format json for machine-readable output
Defines authentication verification procedures for automated agents
Outlines correct flag placement for resource subcommands
Provides patterns for executing SQL queries non-interactively
Clarifies the usage of --force for destructive operations
Distinguishes between CLI automation and MCP server usage

When to use it

When building automated scripts or agents that interact with PlanetScale
When an agent needs to verify its authentication status before performing tasks
When executing SQL queries programmatically against a database branch
When integrating PlanetScale operations into CI/CD or background pipelines

Advantages

Ensures consistent and predictable CLI behavior in headless environments
Reduces errors by enforcing correct flag and argument ordering
Provides a clear path for handling authentication programmatically
Maintains safety by requiring explicit --force usage for destructive commands

Usage examples

“Check if the PlanetScale CLI is authenticated.”: The agent executes pscale auth check --format json and parses the output to verify the status.
“List all databases for my organization.”: The agent runs pscale database list --org my-org --format json to retrieve the data.
“Run a select query on the main branch of my database.”: The agent executes pscale sql my-db main --org my-org --format json --query SELECT 1.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/planetscale/planetscale-pscale-cli-automation/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip planetscale-pscale-cli-automation.zip -d .agents/skills

Documentation by PlanetScale

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)

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 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.

Files

ATTRIBUTION.mdAdded by AutoGineer894 B
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md3.5 KiB

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs an MCP server, Needs a command-line tool, Needs Node.js

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Modal
K-Dense· Community
A serverless cloud platform for deploying and scaling Python applications, AI models, and GPU-accelerated workloads.
Cloud and DevOpsClaude CodeClaude appsOpenAI Codex+14 more
Apache-2.0Low riskGitHub stars of the source repository56.4k
Cloud Infrastructure Network Engineer
Seth Hobson· Community
An expert network engineer persona specializing in cloud architecture, security, and performance optimization.
Cloud and DevOpsClaude Code
MITGitHub stars of the source repository42.3k
Deployment Validation Cloud Architect
Seth Hobson· Community
Expert cloud architect for multi-cloud infrastructure, cost optimization, and resilient system design.
Cloud and DevOpsClaude Code
MITGitHub stars of the source repository42.3k
Airflow Dag Patterns
Seth Hobson· Community
Best practices and design patterns for building and maintaining production-ready Apache Airflow DAGs.
Cloud and DevOpsClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository42.3k
Cost Optimization
Seth Hobson· Community
A comprehensive framework for reducing cloud infrastructure costs across AWS, Azure, GCP, and OCI.
Cloud and DevOpsClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository42.3k
Hybrid Cloud Networking
Seth Hobson· Community
A guide to configuring secure, high-performance network connectivity between on-premises infrastructure and major cloud providers.
Cloud and DevOpsClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository42.3k

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download planetscale-pscale-cli-automation.zip