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 <extra-arg> 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:
# 1. Create development branch
pscale branch create <database> <branch-name>
# 2. Make schema changes (via shell, ORM, or direct SQL)
pscale shell <database> <branch-name>
# 3. View schema diff
pscale branch diff <database> <branch-name>
# 4. Create deploy request
pscale deploy-request create <database> <branch-name>
# 5. Review and deploy
pscale deploy-request deploy <database> <deploy-request-number>
# 6. Verify deployment
pscale deploy-request show <database> <deploy-request-number>
See scripts/ directory for automation.
Branch Development Workflow
# Create branch from main
pscale branch create <database> <feature-branch> --from main
# Work on schema changes
pscale shell <database> <feature-branch>
# Check diff before deploying
pscale branch diff <database> <feature-branch>
# Create deploy request when ready
pscale deploy-request create <database> <feature-branch>
CI/CD Integration
# Create service token for CI/CD
pscale service-token create --org <org>
# Use in CI/CD pipelines (GitHub Actions, GitLab CI, etc.)
export PLANETSCALE_SERVICE_TOKEN_ID=<token-id>
export PLANETSCALE_SERVICE_TOKEN=<token>
# Create and deploy via CI/CD after review/approval gates pass
pscale deploy-request create <database> <branch> --format json
pscale deploy-request deploy <database> <deploy-request-number>
Cloudflare D1 to PlanetScale Postgres import
# 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 <database> <branch> --input ./d1-export.sql --dry-run --format json
# After explicit confirmation, run and verify the import
pscale import d1 start <database> <branch> --input ./d1-export.sql --migration-id <id> --format json
pscale import d1 verify <database> <branch> --migration-id <id> --input ./d1-export.sql --format json
Quick Reference
Most Common Commands
# Authentication
pscale auth login
pscale auth logout
# Branch management
pscale branch create <database> <branch> [--from <source-branch>]
pscale branch list <database>
pscale branch delete <database> <branch>
pscale branch parameters list <database> <branch> --format json
pscale branch resize status <database> <branch> --format json
pscale branch vtgate show <database> <branch> --format json
pscale branch update <database> <branch> --deletion-protected=true --format json
# Discover and use a Vitess read-only region
pscale keyspace read-only-regions <database> <branch> <keyspace> --format json
pscale keyspace read-only-regions add <database> <branch> <keyspace> <region> --cluster-size <size> --replicas <count>
pscale password create <database> <branch> <name> --read-only-region <region> --format json
# Deploy requests
pscale deploy-request create <database> <branch>
pscale deploy-request list <database>
pscale deploy-request storage-check <database> <number> --format json
pscale deploy-request operations <database> <number> --format json
pscale deploy-request deploy <database> <number>
# Dedicated PostgreSQL PgBouncers
pscale pgbouncer list <database> <branch> --format json
pscale pgbouncer show <database> <branch> <name> --format json
# Dedicated PostgreSQL read-only replicas
pscale read-only-replica list <database> <branch> --org <org> --format json
pscale read-only-replica show <database> <branch> <name> --org <org> --format json
# Database operations
pscale database create <database> --org <org>
pscale database list
pscale database show <database> --format json
pscale database ip-restriction list <database> --format json
pscale database throttler show <database> --org <org> --format json
pscale database aggressive-cutover show <database> --org <org> --format json
pscale shell <database> <branch>
# Database webhooks
# Webhook resource JSON may include the signing secret; redact before capture.
set -o pipefail
pscale webhook list <database> --org <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 <database> --org <org> --format json
pscale maintenance windows <database> <schedule-id> --org <org> --format json
# Backup policies and authentication-attempt exports
pscale backup policy list <database> --format json
pscale audit-log auth-attempts download --org <org> --since 24h --outcome deny
# Non-interactive read query for agents/scripts
pscale sql <database> <branch> --org <org> --format json --query "SELECT 1"
# Point-in-time diagnostics, branch metrics, and query-fingerprint analysis
pscale inspect all <database> <branch> --org <org> --format json
pscale metrics report <database> <branch> --org <org> --period 1d --format json
pscale metrics show <database> <branch> --org <org> --metric queries --metric latency_p99 --period 1h --format json
pscale insights queries <database> <branch> --org <org> --sort p99Latency --period 1h --format json
pscale insights queries samples <database> <branch> <fingerprint> --org <org> --keyspace <keyspace> --format json
pscale insights tags summaries <database> <branch> --org <org> --tags app --sort totalTime --format json
pscale insights errors show <database> <branch> <full-error-fingerprint> --org <org> --format json
pscale insights anomalies show <database> <branch> <anomaly-id> --org <org> --format json
pscale insights recommendations <database> --org <org> --format json
pscale insights recommendations show <database> <number> --org <org> --format json
pscale insights queries show <database> <branch> <query-id> --org <org> --format json
pscale insights queries summary <database> <branch> <fingerprint> --org <org> --keyspace <keyspace> --format json
# Postgres Traffic Control inventory
pscale traffic-control budget list <database> <branch> --org <org> --format json
# Organization billing inspection
pscale billing invoice list --org <org> --page 1 --per-page 25 --format json
pscale billing payment-method show --org <org> --format json
# Cloudflare D1 import dry-run
pscale import d1 start <database> <branch> --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
1---2name: planetscale-cli-skills3description: 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,4---56# PlanetScale CLI Skills78Comprehensive `pscale` command reference and workflows for managing PlanetScale databases via terminal.910## Overview1112The 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.1314## Configuration and credential safety1516- 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.17- Keep API URLs and credentials in the user config, environment/secret manager, or explicit approved flags. Never commit them to a repository-local config.18- `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.19- 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.2021## Binary-native agent bootstrap2223- `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.24- 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.25- Validate automated bootstrap output starts with `---\nname: pscale-cli`; `pscale --skill <extra-arg>` prints root help and exits zero instead of emitting the skill.26- 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.27- 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.2829## Sub-Skills3031| Command | Skill | Use When |32|---------|-------|----------|33| **auth** | `pscale-auth` | Login, logout, service tokens, authentication management |34| **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 |35| **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 |36| **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 |37| **maintenance** | `pscale-maintenance` | Inspect Vitess Enterprise maintenance schedules, pending versions, deadlines, and historical windows |38| **sql** | `pscale-sql` | Run non-interactive SQL queries with JSON output and ephemeral credentials |39| **metrics** | `pscale-metrics` | Query historical/current branch metrics and engine-aware grouped performance reports |40| **insights** | `pscale-insights` | Analyze production query statistics, execution samples, query tags, error details, anomaly correlations, and schema recommendations |41| **traffic-control** | `pscale-traffic-control` | Inventory and safely manage Postgres Traffic Control budgets and fingerprint/keyspace/tag rules |42| **inspect** | `pscale-inspect` | Run point-in-time, read-only MySQL/Vitess and PostgreSQL diagnostic checks |43| **import d1** | `pscale-import-d1` | Import Cloudflare D1 SQLite exports into PlanetScale Postgres |44| **backup** | `pscale-backup` | Create, list, show, restore, and delete branch backups; manage scheduled backup policies |45| **billing** | `pscale-billing` | Inspect invoices and manage organization payment methods with sensitive billing-data safeguards |46| **audit-log** | `pscale-audit-log` | List audit events and export filtered authentication attempts |47| **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 |48| **pgbouncer** | `pscale-pgbouncer` | List, inspect, create, resize, cancel, and delete dedicated PostgreSQL PgBouncers |49| **read-only-replica** | `pscale-read-only-replica` | List, inspect, create, resize, configure, and delete dedicated PostgreSQL read-only replicas |50| **webhook** | `pscale-webhook` | List, inspect, create, update, test, and delete database webhooks, including authorization headers |51| **org** | `pscale-org` | List, show, switch, and update organizations; manage SSO, directory sync, email domains, members, and teams |52| **service-token** | `pscale-service-token` | Create, show, and manage CI/CD service tokens |5354## Decision Trees5556### Should I use a branch or deploy request?5758```59What's your goal?60├─ Experimenting with schema changes → Create branch (pscale-branch)61├─ Testing schema in isolation → Create branch (pscale-branch)62├─ Ready to deploy schema to production → Create deploy request (pscale-deploy-request)63└─ Reviewing schema changes before production → Review deploy request (pscale-deploy-request)64```6566### Service token vs password?6768```69What's your use case?70├─ CI/CD pipeline → Service token (pscale-service-token)71├─ Local development → Password (pscale-password)72├─ Production application → Service token (rotatable, secure)73└─ One-off admin task → Password (temporary)74```7576### Direct promotion vs deploy request?7778```79Production readiness?80├─ Immediate promotion (dangerous) → pscale branch promote (pscale-branch)81├─ Review + approval workflow → pscale deploy-request create (pscale-deploy-request)82└─ Safe production deployment → Always use deploy requests83```8485## Common Workflows8687### Schema Migration Workflow8889Complete workflow from branch creation to production deployment:9091```bash92# 1. Create development branch93pscale branch create <database> <branch-name>9495# 2. Make schema changes (via shell, ORM, or direct SQL)96pscale shell <database> <branch-name>9798# 3. View schema diff99pscale branch diff <database> <branch-name>100101# 4. Create deploy request102pscale deploy-request create <database> <branch-name>103104# 5. Review and deploy105pscale deploy-request deploy <database> <deploy-request-number>106107# 6. Verify deployment108pscale deploy-request show <database> <deploy-request-number>109```110111See `scripts/` directory for automation.112113### Branch Development Workflow114115```bash116# Create branch from main117pscale branch create <database> <feature-branch> --from main118119# Work on schema changes120pscale shell <database> <feature-branch>121122# Check diff before deploying123pscale branch diff <database> <feature-branch>124125# Create deploy request when ready126pscale deploy-request create <database> <feature-branch>127```128129### CI/CD Integration130131```bash132# Create service token for CI/CD133pscale service-token create --org <org>134135# Use in CI/CD pipelines (GitHub Actions, GitLab CI, etc.)136export PLANETSCALE_SERVICE_TOKEN_ID=<token-id>137export PLANETSCALE_SERVICE_TOKEN=<token>138139# Create and deploy via CI/CD after review/approval gates pass140pscale deploy-request create <database> <branch> --format json141pscale deploy-request deploy <database> <deploy-request-number>142```143144### Cloudflare D1 to PlanetScale Postgres import145146```bash147# Lint and dry-run first; review the JSON migration ID and warnings148pscale import d1 lint --input ./d1-export.sql --format json149pscale import d1 start <database> <branch> --input ./d1-export.sql --dry-run --format json150151# After explicit confirmation, run and verify the import152pscale import d1 start <database> <branch> --input ./d1-export.sql --migration-id <id> --format json153pscale import d1 verify <database> <branch> --migration-id <id> --input ./d1-export.sql --format json154```155156## Quick Reference157158### Most Common Commands159160```bash161# Authentication162pscale auth login163pscale auth logout164165# Branch management166pscale branch create <database> <branch> [--from <source-branch>]167pscale branch list <database>168pscale branch delete <database> <branch>169pscale branch parameters list <database> <branch> --format json170pscale branch resize status <database> <branch> --format json171pscale branch vtgate show <database> <branch> --format json172pscale branch update <database> <branch> --deletion-protected=true --format json173174# Discover and use a Vitess read-only region175pscale keyspace read-only-regions <database> <branch> <keyspace> --format json176pscale keyspace read-only-regions add <database> <branch> <keyspace> <region> --cluster-size <size> --replicas <count>177pscale password create <database> <branch> <name> --read-only-region <region> --format json178179# Deploy requests180pscale deploy-request create <database> <branch>181pscale deploy-request list <database>182pscale deploy-request storage-check <database> <number> --format json183pscale deploy-request operations <database> <number> --format json184pscale deploy-request deploy <database> <number>185186# Dedicated PostgreSQL PgBouncers187pscale pgbouncer list <database> <branch> --format json188pscale pgbouncer show <database> <branch> <name> --format json189190# Dedicated PostgreSQL read-only replicas191pscale read-only-replica list <database> <branch> --org <org> --format json192pscale read-only-replica show <database> <branch> <name> --org <org> --format json193194# Database operations195pscale database create <database> --org <org>196pscale database list197pscale database show <database> --format json198pscale database ip-restriction list <database> --format json199pscale database throttler show <database> --org <org> --format json200pscale database aggressive-cutover show <database> --org <org> --format json201pscale shell <database> <branch>202203# Database webhooks204# Webhook resource JSON may include the signing secret; redact before capture.205set -o pipefail206pscale webhook list <database> --org <org> --format json |207 jq 'map(del(.secret))'208# Use `show` only when intentionally retrieving the secret; otherwise use the redacted sub-skill workflow.209210# Maintenance schedules and windows (Vitess Enterprise)211pscale maintenance list <database> --org <org> --format json212pscale maintenance windows <database> <schedule-id> --org <org> --format json213214# Backup policies and authentication-attempt exports215pscale backup policy list <database> --format json216pscale audit-log auth-attempts download --org <org> --since 24h --outcome deny217218# Non-interactive read query for agents/scripts219pscale sql <database> <branch> --org <org> --format json --query "SELECT 1"220221# Point-in-time diagnostics, branch metrics, and query-fingerprint analysis222pscale inspect all <database> <branch> --org <org> --format json223pscale metrics report <database> <branch> --org <org> --period 1d --format json224pscale metrics show <database> <branch> --org <org> --metric queries --metric latency_p99 --period 1h --format json225pscale insights queries <database> <branch> --org <org> --sort p99Latency --period 1h --format json226pscale insights queries samples <database> <branch> <fingerprint> --org <org> --keyspace <keyspace> --format json227pscale insights tags summaries <database> <branch> --org <org> --tags app --sort totalTime --format json228pscale insights errors show <database> <branch> <full-error-fingerprint> --org <org> --format json229pscale insights anomalies show <database> <branch> <anomaly-id> --org <org> --format json230pscale insights recommendations <database> --org <org> --format json231pscale insights recommendations show <database> <number> --org <org> --format json232pscale insights queries show <database> <branch> <query-id> --org <org> --format json233pscale insights queries summary <database> <branch> <fingerprint> --org <org> --keyspace <keyspace> --format json234235# Postgres Traffic Control inventory236pscale traffic-control budget list <database> <branch> --org <org> --format json237238# Organization billing inspection239pscale billing invoice list --org <org> --page 1 --per-page 25 --format json240pscale billing payment-method show --org <org> --format json241242# Cloudflare D1 import dry-run243pscale import d1 start <database> <branch> --input ./d1-export.sql --dry-run --format json244```245246## Related Skills247248- **drizzle-kit** - ORM schema management and migrations249- **gitlab-cli-skills** - GitLab MR workflow integration250- **github** - GitHub PR and CI/CD integration251252## Automation Scripts253254See `scripts/` directory for token-efficient automation:255256- `create-branch-for-mr.sh` - Create PlanetScale branch matching your MR/PR branch name257- `deploy-schema-change.sh` - Complete schema migration workflow258- `sync-branch-with-main.sh` - Create a replacement branch from main/base for conflict resolution259260Scripts execute without loading into context (~90% token savings).261262## Resources263264- Official docs: https://planetscale.com/docs/reference/planetscale-cli265- GitHub: https://github.com/planetscale/cli266- Community: https://github.com/planetscale/discussion