🌐 PlanetScale CLI Skills

Comprehensive pscale command reference and automation workflows for managing PlanetScale databases via terminal.

Destructive examples require explicit approval for the exact organization and applicable database, branch, resource, operation, and flags. Check dependencies and availability, establish a verified recovery path that survives the operation, then verify the result and service health with read-back checks. Troubleshooting errors, stale resources, and CLI confirmation prompts do not authorize deletion or demotion. Each affected standalone skill carries these gates for selective installs.

🎯 What This Skill Provides

• 21 sub-skills covering all major pscale commands
• 3 automation scripts for common workflows (create branch, deploy schema, sync)
• Decision trees for common questions (branch vs deploy request, tokens vs passwords)
• Troubleshooting sections for self-service problem solving
• Complete command reference in each sub-skill's references/ directory
• Token-efficient workflows (~90-95% reduction for repetitive operations)

📦 Installation

Agent Skills (npx skills)

This repository is a collection containing the planetscale-cli-skills orchestrator plus 21 standalone pscale-* skills. Each skill lives in its own directory with its own SKILL.md; there is intentionally no root SKILL.md so Agent Skills can discover every sibling instead of stopping at the repository root.

# List all discoverable skills without installing
npx skills add vince-winkintel/planetscale-cli-skills --list

# Interactive picker
npx skills add vince-winkintel/planetscale-cli-skills

# Install everything
npx skills add vince-winkintel/planetscale-cli-skills --all

# Install only selected skills
npx skills add vince-winkintel/planetscale-cli-skills \
  --skill planetscale-cli-skills \
  --skill pscale-import-d1

Via ClawHub

clawhub install planetscale-cli-skills

ClawHub releases preserve the existing full-collection install shape. Build the registry package from a git archive of the release tag (which excludes developer-only docs/ and tests/), copy planetscale-cli-skills/SKILL.md to package-root SKILL.md, remove the now-redundant nested orchestrator directory, and retain all standalone pscale-* skill directories. Do not publish the repository root directly or publish only planetscale-cli-skills/; either choice would break one of the supported discovery/install paths. The live listing remains on its last published version until the transformed package is published.

Via Git

git clone https://github.com/vince-winkintel/planetscale-cli-skills.git

🚀 Quick Start

Prerequisites

Install the PlanetScale CLI:

# macOS
brew install planetscale/tap/pscale

# Linux
wget https://github.com/planetscale/cli/releases/latest/download/pscale_X.X.X_linux_amd64.tar.gz
tar -xzf pscale_*.tar.gz
sudo mv pscale /usr/local/bin/

# Windows
scoop bucket add pscale https://github.com/planetscale/scoop-bucket.git
scoop install pscale

Automation scripts that parse pscale --format json output also require jq.

Authenticate

# Interactive login
pscale auth login

# Or use service tokens for CI/CD
export PLANETSCALE_SERVICE_TOKEN_ID=<token-id>
export PLANETSCALE_SERVICE_TOKEN=<token>

Create Your First Branch

# Using automation script
./scripts/create-branch-for-mr.sh \
  --database my-database \
  --branch feature-branch

# Or manually
pscale branch create my-database feature-branch --from main

🧩 Sub-Skills

Skill	Use When	Common Commands
pscale-auth	Login, logout, authentication	pscale auth login/logout
pscale-branch	Refresh MySQL schema snapshots with bounded readiness checks; create, restore to a PostgreSQL recovery point, rename, protect, diff, promote/demote with approved sizing, and switchover branches; query PostgreSQL/Neki logs; inspect live connections, including Neki router sessions with incomplete-result warnings and separately approved termination using fresh action IDs; manage Postgres size/replicas/parameters/maintenance and extension toggles, run Postgres/Neki branch-wide maintenance, resize Vitess VTGates and roll out VTGate parameters, inspect branch infra, manage live routing rules, Lookup Vindexes, tablet throttling, query pattern reports, and Vitess MoveTables workflows	pscale branch create/update/switchover/diff/refresh-schema/parameters/maintenance/extensions/resize/vtgate/infra/query-patterns/vtctl lookup-vindex, pscale branch connections show/top, pscale logs
pscale-deploy-request	Deploy schema changes safely; inspect queues, operations, reviews, storage, and throttling; update auto-apply/auto-delete/per-request aggressive-cutover settings with approval and read-back; retry diagnosed failed operations; unblock failed deploy/revert queues	pscale deploy-request create/deploy/update/retry/unblock/queue/operations/storage-check/throttler
pscale-database	Manage settings, database-level and keyspace-level Vitess throttlers, keyspace VTTablet/MySQL parameters, rollout concurrency, disk-storage settings, internal/external keyspaces, aggressive-cutover defaults, PostgreSQL IP restrictions, shells, and read-only regions/dumps	pscale database show/update/throttler/aggressive-cutover/ip-restriction, pscale keyspace create-external/settings/update-settings/parameters/delete/read-only-regions, pscale shell
pscale-neki	Manage Neki data topology, shards, branch-wide change requests, configuration profiles, per-shard read-only replica capacity (--read-only-replicas) and extension sets, routers, sidecar settings through the owning profile after catalog checks and exact-target approval (legacy branch sidecar is deprecated), admin config, profile maintenance, restore sizing overrides, target-specific inspection, and router/shard role access	pscale branch changes, pscale branch data-topology/shard/config-profile/router/admin, pscale branch config-profile update --parameters sidecar.<name>=<value>, pscale inspect, pscale role get
pscale-maintenance	Inspect Vitess Enterprise schedules/history and Postgres windows/events; approve window changes and event rescheduling	pscale maintenance list/show/windows, pscale branch maintenance window/event
pscale-sql	Non-interactive SQL for agents/scripts	pscale sql --query
pscale-metrics	Query historical/current branch metrics and engine-aware performance reports	pscale metrics show/instant/report
pscale-insights	Analyze production query performance, execution samples, tags, error details, anomaly correlations, and schema recommendations	pscale insights queries/tags/errors/errors show/anomalies/anomalies show/recommendations
pscale-traffic-control	Inventory and safely manage Postgres Traffic Control budgets and matching rules	pscale traffic-control budget list/show/create/update/delete, pscale traffic-control rule create/delete
pscale-inspect	Run point-in-time, read-only MySQL/Vitess, PostgreSQL, and Neki diagnostics against one connection target	pscale inspect all/locks/seq-scans/bloat
pscale-import-d1	Import Cloudflare D1 exports into PlanetScale Postgres	pscale import d1 lint/start/verify
pscale-backup	Create/restore backups, approve emergency live-tablet sources, and manage scheduled policies	pscale backup create/list/policy
pscale-billing	Inspect invoices and manage organization payment methods	pscale billing payment-method show/update/delete, pscale billing invoice list/show/line-items
pscale-audit-log	List audit events and export authentication attempts	pscale audit-log list/auth-attempts
pscale-password	Connection passwords and Postgres/Neki roles, including Vitess read-only-region credentials, Neki inherited-role pairings and router/shard targets, named Postgres replica targets, status/expiration, and metadata/IP restriction updates	pscale password create/list/show/update, pscale role create/list/get/default/reset/delete/reassign
pscale-pgbouncer	Dedicated PostgreSQL PgBouncer lifecycle and asynchronous resizing	pscale pgbouncer list/show/create/resize/delete
pscale-read-only-replica	Dedicated PostgreSQL read-replica lifecycle, sizing, regions, parameters, and approved irreversible feature-gated detach	pscale dedicated-read-replica list/show/create/update/delete/detach
pscale-webhook	Database webhook lifecycle, authorization headers, and test events	pscale webhook list/show/create/update/test/delete
pscale-org	Switch organizations, update settings, manage SSO/directory sync/domains, and inspect or manage members/teams	pscale org list/switch/update/sso/member/team
pscale-service-token	CI/CD authentication and last-used IP/network metadata	pscale service-token create/show

🛠️ Automation Scripts

All scripts in scripts/ directory execute without loading into context (~90% token savings).

create-branch-for-mr.sh

Create PlanetScale branch matching your MR or PR:

./scripts/create-branch-for-mr.sh \
  --database my-database \
  --branch feature-schema-migration

deploy-schema-change.sh

Complete schema deployment workflow:

./scripts/deploy-schema-change.sh \
  --database my-database \
  --branch feature-schema-v2 \
  --deploy

sync-branch-with-main.sh

Create a replacement branch from the current base branch when production/base has changed:

./scripts/sync-branch-with-main.sh \
  --database my-db \
  --branch feature-branch \
  --new-branch feature-branch-rebased

🌊 Common Workflows

Schema Migration (Safe Production Deployment)

# 1. Create branch
pscale branch create my-db feature-schema --from main

# 2. Make schema changes
pscale shell my-db feature-schema
-- ALTER TABLE users ADD COLUMN last_login DATETIME;

# 3. View diff
pscale branch diff my-db feature-schema

# 4. Create deploy request
pscale deploy-request create my-db feature-schema

# 5. Deploy
pscale deploy-request deploy my-db 1

CI/CD Integration (GitHub Actions)

deploy-schema:
  steps:
    - name: Create branch
      run: |
        ./scripts/create-branch-for-mr.sh \
          --database ${{ secrets.DATABASE }} \
          --branch ${{ github.ref_name }}
    
    - name: Apply schema
      run: |
        pscale shell ${{ secrets.DATABASE }} ${{ github.ref_name }} < migrations.sql
    
    - name: Deploy
      run: |
        ./scripts/deploy-schema-change.sh \
          --database ${{ secrets.DATABASE }} \
          --branch ${{ github.ref_name }} \
          --deploy

Non-interactive SQL for agents/scripts

# Default role is reader; use JSON for machine-readable results
pscale sql my-db main --org my-org --format json --query "SELECT 1"

# Writes require an explicit write-capable role; destructive SQL also needs --force
# and should only be run after explicit user approval.
pscale sql my-db main --org my-org --role admin --query "UPDATE users SET disabled = true WHERE id = 123"

Database diagnostics

# Point-in-time, connection-level diagnostics (JSON combined report)
pscale inspect all my-db main --org my-org --format json
# Neki: inspect exactly one shard on the primary path by default
pscale inspect all my-db main --org my-org --shard <shard-id> --format json
# Add --router <router> and/or --replica only for that explicit target path

# Historical/current branch metrics and a curated engine-aware report
pscale metrics report my-db main --org my-org --period 1d --format json
pscale metrics show my-db main --org my-org --metric queries --metric latency_p99 --period 1h --format json

# Query-fingerprint analysis of production traffic
pscale insights queries my-db main --org my-org --sort p99Latency --period 1h --format json
pscale insights queries samples my-db main <fingerprint> --org my-org --keyspace <keyspace> --format json
pscale insights tags summaries my-db main --org my-org --tags app --sort totalTime --format json
pscale insights errors my-db main --org my-org --period 1h --format json
pscale insights errors show my-db main <full-error-fingerprint> --org my-org --period 1h --format json
pscale insights anomalies show my-db main <anomaly-id> --org my-org --format json
pscale insights recommendations my-db --org my-org --format json
pscale insights recommendations show my-db <number> --org my-org --format json
pscale insights queries show my-db main <query-id> --org my-org --format json
pscale insights queries summary my-db main <fingerprint> --org my-org --keyspace <keyspace> --format json
pscale insights queries traffic-budgets my-db main <fingerprint> --org my-org --keyspace <keyspace> --format json

# Recent PostgreSQL or Neki branch logs
pscale logs my-db main --org my-org --format json --period 1h

# Inventory Postgres Traffic Control budgets and their rules
pscale traffic-control budget list my-db main --org my-org --format json

# Drill into specialized metrics for queries, tables, or tablets
pscale metrics queries my-db main --org my-org --metric latency_p99 --query-id <fingerprint-keyspace> --period 1h --format json
pscale metrics tables my-db main --org my-org --format json
pscale metrics tablets my-db main --org my-org --metric vreplication_lag --workflow <workflow> --period 1h --format json

pscale metrics provides historical/current branch telemetry, pscale insights provides query-fingerprint analysis, and pscale inspect provides live target-specific checks. For inspection, choose --dbname for PostgreSQL, --keyspace <keyspace>/<shard> for Vitess, or --shard <shard-id> and optional --router/--replica for Neki when defaults are not the intended target. Treat recommendation DDL as a proposal that still requires review and explicit approval.

Cloudflare D1 Import

# Export D1 with wrangler, then lint and dry-run before loading PlanetScale
pscale import d1 lint --input ./d1-export.sql --format json
pscale import d1 start my-db migration-branch --input ./d1-export.sql --dry-run --format json

# After reviewing the migration ID and warnings, run and verify the import
pscale import d1 start my-db migration-branch --input ./d1-export.sql --migration-id <id> --format json
pscale import d1 verify my-db migration-branch --migration-id <id> --input ./d1-export.sql --format json

Drizzle ORM Integration

# 1. Edit your schema file
vim schema.sql

# 2. Create PlanetScale branch and apply changes
./scripts/create-branch-for-mr.sh --database my-database --branch $(git branch --show-current)
pscale shell my-database $(git branch --show-current) < schema.sql

# 3. Deploy
./scripts/deploy-schema-change.sh --database my-database --branch $(git branch --show-current) --deploy

# 4. Pull schema back to Drizzle
pnpm drizzle-kit introspect

🎓 Decision Trees

Branch vs Deploy Request?

What's your goal?
├─ Experimenting → Create branch
├─ Testing changes → Create branch
├─ Ready for production → Create deploy request
└─ Review before prod → Deploy request (safe, reviewable)

Service Token vs Password?

Use case?
├─ CI/CD pipeline → Service token (rotatable, scoped)
├─ Local development → Password (temporary)
├─ Production app → Service token
└─ One-off admin → Password

Direct Promotion vs Deploy Request?

⚠️ Always use deploy requests for production

📊 Token Efficiency

Operation	Manual (7 steps)	Script (1 command)	Savings
Schema migration	~3000 tokens	~150 tokens	95%
Branch creation	~500 tokens	~50 tokens	90%
Deploy request	~800 tokens	~80 tokens	90%

🔗 Related Skills

• drizzle-kit - ORM schema management
• gitlab-cli-skills - GitLab MR integration
• github - GitHub PR and CI/CD

📚 Resources

• PlanetScale CLI Docs
• PlanetScale GitHub
• ClawHub Page

🤝 Contributing

Offline security regressions: python3 -m unittest discover -s tests -v. The suite records extracted documentation command arguments without invoking PlanetScale, checks identical standalone safety gates and authentication prohibitions, and verifies local references and release-archive contents. See the audit dispositions for evidence, scope, and limitations. Release/version history remains in VERSION.

Contributions welcome! Please:

1. Follow existing skill structure patterns
2. Include decision trees and troubleshooting
3. Add scripts to scripts/ directory
4. Update README.md and relevant SKILL.md files

📄 License

MIT License - see LICENSE file.

🙏 Acknowledgments

• Built for OpenClaw AI agents
• Optimized using skill-creator patterns
• Inspired by gitlab-cli-skills