# Planetscale CLI Skills > PlanetScale CLI (pscale) command reference and workflows. Use for authentication, organizations, SSO, directory sync, teams, members, billing, invoices, payment methods, databases, branches, PostgreSQL point-in-time recovery, branch maintenance, extension catalogs, metrics, insights, diagnostics, SQL, deploy requests, schema migrations, keyspaces, Lookup Vindexes, VTGate sizing, database/deploy/tablet throttlers, aggressive cutover, Postgres switchovers, Traffic Control, PgBouncers, PostgreSQL read-only replicas, Postgres role connection targets, Postgres IP restrictions, Vitess read-only regions, backups, webhooks, audit logs, service tokens, passwords, binary-native agent guidance, Cloudflare D1 imports, and automation. Routes to specialized pscale sub-skills. Triggers on PlanetScale CLI, pscale, pscale --skill, restore point, point-in-time recovery, PITR, pscale maintenance, maintenance window, pscale metrics, performance report, pscale insights, pscale inspect, pscale sql, pscale role get, deploy request, - Skill: `vince-winkintel/planetscale-cli-skills` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds add vince-winkintel/planetscale-cli-skills` - Raw SKILL.md: https://api.skillmd.com/api/skills/vince-winkintel/planetscale-cli-skills/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: vince-winkintel (https://skillmd.com/u/vince-winkintel) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/vince-winkintel/planetscale-cli-skills --- # PlanetScale CLI Skills Comprehensive `pscale` command reference and workflows for managing PlanetScale databases via terminal. ## Overview The PlanetScale CLI brings database branches, deploy requests, and schema migrations to your fingertips. This skill provides command references, automation scripts, and decision trees for all `pscale` operations. ## Configuration and credential safety - Directory-local `.pscale.yml` files are project configuration, not trusted credential configuration. The CLI accepts only `org`, `database`, and `branch` from them and warns while ignoring keys such as API endpoints or tokens. - Keep API URLs and credentials in the user config, environment/secret manager, or explicit approved flags. Never commit them to a repository-local config. - `pscale api` follows cross-host redirects without forwarding authentication or caller-supplied headers. Even with this protection, pass secret-bearing headers only to an explicitly verified API host and do not expose them in logs. - When `--format json` is active, API error codes are preserved in the top-level `code` field instead of being collapsed to `COMMAND_FAILED`. Branch automation should branch on exact codes when present; for `schema_mutation_blocked`, wait for the active vtctld mutation or deploy to finish before retrying. ## Binary-native agent bootstrap - `pscale --skill` prints the current binary's installable `pscale-cli` skill file to stdout when no positional arguments follow it. `pscale agent-guide --skill` is equivalent. - Both forms still emit the raw Markdown skill when `--format json` is present; redirect the output to an approved skills directory when a standalone binary-native guide is wanted. - Validate automated bootstrap output starts with `---\nname: pscale-cli`; `pscale --skill ` prints root help and exits zero instead of emitting the skill. - The binary-native guide is useful for first-party command discovery, but it does not replace this repository's specialized safety workflows, focused references, and helper scripts. - When a command name is assembled dynamically, validate the expected JSON/resource shape as well as the exit code. A bare unrecognized root token currently prints root help and exits zero, so zero alone does not prove that a resource operation ran. ## Sub-Skills | Command | Skill | Use When | |---------|-------|----------| | **auth** | `pscale-auth` | Login, logout, service tokens, authentication management | | **branch** | `pscale-branch` | Create, restore to a PostgreSQL recovery point, rename, protect, delete, promote, diff, list, and switchover branches; inspect branch infra, manage Postgres size/replicas/parameters/maintenance/extensions, resize Vitess VTGates, manage live keyspace routing rules, Lookup Vindexes, and tablet throttling, manage query pattern reports, manage Vitess MoveTables workflows | | **deploy-request** | `pscale-deploy-request` | Create, review, inspect queues/operations, check storage, throttle, deploy, update auto-apply/auto-delete settings, unblock failed deploy/revert queues, force cutover, and revert schema changes | | **database** | `pscale-database` | Create, list, show, update, delete, and dump databases; manage database-level Vitess throttler/aggressive-cutover defaults, keyspaces, PostgreSQL IP restrictions, and read-only regions | | **maintenance** | `pscale-maintenance` | Inspect Vitess Enterprise maintenance schedules, pending versions, deadlines, and historical windows | | **sql** | `pscale-sql` | Run non-interactive SQL queries with JSON output and ephemeral credentials | | **metrics** | `pscale-metrics` | Query historical/current branch metrics and engine-aware grouped performance reports | | **insights** | `pscale-insights` | Analyze production query statistics, execution samples, query tags, error details, anomaly correlations, and schema recommendations | | **traffic-control** | `pscale-traffic-control` | Inventory and safely manage Postgres Traffic Control budgets and fingerprint/keyspace/tag rules | | **inspect** | `pscale-inspect` | Run point-in-time, read-only MySQL/Vitess and PostgreSQL diagnostic checks | | **import d1** | `pscale-import-d1` | Import Cloudflare D1 SQLite exports into PlanetScale Postgres | | **backup** | `pscale-backup` | Create, list, show, restore, and delete branch backups; manage scheduled backup policies | | **billing** | `pscale-billing` | Inspect invoices and manage organization payment methods with sensitive billing-data safeguards | | **audit-log** | `pscale-audit-log` | List audit events and export filtered authentication attempts | | **password** | `pscale-password` | Create, list, show, update, delete, and scope Vitess connection passwords to read-only regions; inspect Postgres role connection targets by replica name | | **pgbouncer** | `pscale-pgbouncer` | List, inspect, create, resize, cancel, and delete dedicated PostgreSQL PgBouncers | | **read-only-replica** | `pscale-read-only-replica` | List, inspect, create, resize, configure, and delete dedicated PostgreSQL read-only replicas | | **webhook** | `pscale-webhook` | List, inspect, create, update, test, and delete database webhooks, including authorization headers | | **org** | `pscale-org` | List, show, switch, and update organizations; manage SSO, directory sync, email domains, members, and teams | | **service-token** | `pscale-service-token` | Create, show, and manage CI/CD service tokens | ## Decision Trees ### Should I use a branch or deploy request? ``` What's your goal? ├─ Experimenting with schema changes → Create branch (pscale-branch) ├─ Testing schema in isolation → Create branch (pscale-branch) ├─ Ready to deploy schema to production → Create deploy request (pscale-deploy-request) └─ Reviewing schema changes before production → Review deploy request (pscale-deploy-request) ``` ### Service token vs password? ``` What's your use case? ├─ CI/CD pipeline → Service token (pscale-service-token) ├─ Local development → Password (pscale-password) ├─ Production application → Service token (rotatable, secure) └─ One-off admin task → Password (temporary) ``` ### Direct promotion vs deploy request? ``` Production readiness? ├─ Immediate promotion (dangerous) → pscale branch promote (pscale-branch) ├─ Review + approval workflow → pscale deploy-request create (pscale-deploy-request) └─ Safe production deployment → Always use deploy requests ``` ## Common Workflows ### Schema Migration Workflow Complete workflow from branch creation to production deployment: ```bash # 1. Create development branch pscale branch create # 2. Make schema changes (via shell, ORM, or direct SQL) pscale shell # 3. View schema diff pscale branch diff # 4. Create deploy request pscale deploy-request create # 5. Review and deploy pscale deploy-request deploy # 6. Verify deployment pscale deploy-request show ``` See `scripts/` directory for automation. ### Branch Development Workflow ```bash # Create branch from main pscale branch create --from main # Work on schema changes pscale shell # Check diff before deploying pscale branch diff # Create deploy request when ready pscale deploy-request create ``` ### CI/CD Integration ```bash # Create service token for CI/CD pscale service-token create --org # Use in CI/CD pipelines (GitHub Actions, GitLab CI, etc.) export PLANETSCALE_SERVICE_TOKEN_ID= export PLANETSCALE_SERVICE_TOKEN= # Create and deploy via CI/CD after review/approval gates pass pscale deploy-request create --format json pscale deploy-request deploy ``` ### Cloudflare D1 to PlanetScale Postgres import ```bash # Lint and dry-run first; review the JSON migration ID and warnings pscale import d1 lint --input ./d1-export.sql --format json pscale import d1 start --input ./d1-export.sql --dry-run --format json # After explicit confirmation, run and verify the import pscale import d1 start --input ./d1-export.sql --migration-id --format json pscale import d1 verify --migration-id --input ./d1-export.sql --format json ``` ## Quick Reference ### Most Common Commands ```bash # Authentication pscale auth login pscale auth logout # Branch management pscale branch create [--from ] pscale branch list pscale branch delete pscale branch parameters list --format json pscale branch resize status --format json pscale branch vtgate show --format json pscale branch update --deletion-protected=true --format json # Discover and use a Vitess read-only region pscale keyspace read-only-regions --format json pscale keyspace read-only-regions add --cluster-size --replicas pscale password create --read-only-region --format json # Deploy requests pscale deploy-request create pscale deploy-request list pscale deploy-request storage-check --format json pscale deploy-request operations --format json pscale deploy-request deploy # Dedicated PostgreSQL PgBouncers pscale pgbouncer list --format json pscale pgbouncer show --format json # Dedicated PostgreSQL read-only replicas pscale read-only-replica list --org --format json pscale read-only-replica show --org --format json # Database operations pscale database create --org pscale database list pscale database show --format json pscale database ip-restriction list --format json pscale database throttler show --org --format json pscale database aggressive-cutover show --org --format json pscale shell # Database webhooks # Webhook resource JSON may include the signing secret; redact before capture. set -o pipefail pscale webhook list --org --format json | jq 'map(del(.secret))' # Use `show` only when intentionally retrieving the secret; otherwise use the redacted sub-skill workflow. # Maintenance schedules and windows (Vitess Enterprise) pscale maintenance list --org --format json pscale maintenance windows --org --format json # Backup policies and authentication-attempt exports pscale backup policy list --format json pscale audit-log auth-attempts download --org --since 24h --outcome deny # Non-interactive read query for agents/scripts pscale sql --org --format json --query "SELECT 1" # Point-in-time diagnostics, branch metrics, and query-fingerprint analysis pscale inspect all --org --format json pscale metrics report --org --period 1d --format json pscale metrics show --org --metric queries --metric latency_p99 --period 1h --format json pscale insights queries --org --sort p99Latency --period 1h --format json pscale insights queries samples --org --keyspace --format json pscale insights tags summaries --org --tags app --sort totalTime --format json pscale insights errors show --org --format json pscale insights anomalies show --org --format json pscale insights recommendations --org --format json pscale insights recommendations show --org --format json pscale insights queries show --org --format json pscale insights queries summary --org --keyspace --format json # Postgres Traffic Control inventory pscale traffic-control budget list --org --format json # Organization billing inspection pscale billing invoice list --org --page 1 --per-page 25 --format json pscale billing payment-method show --org --format json # Cloudflare D1 import dry-run pscale import d1 start --input ./d1-export.sql --dry-run --format json ``` ## Related Skills - **drizzle-kit** - ORM schema management and migrations - **gitlab-cli-skills** - GitLab MR workflow integration - **github** - GitHub PR and CI/CD integration ## Automation Scripts See `scripts/` directory for token-efficient automation: - `create-branch-for-mr.sh` - Create PlanetScale branch matching your MR/PR branch name - `deploy-schema-change.sh` - Complete schema migration workflow - `sync-branch-with-main.sh` - Create a replacement branch from main/base for conflict resolution Scripts execute without loading into context (~90% token savings). ## Resources - Official docs: https://planetscale.com/docs/reference/planetscale-cli - GitHub: https://github.com/planetscale/cli - Community: https://github.com/planetscale/discussion