Planetscale Cli Skills

pscale auth

Manage authentication for the PlanetScale CLI.

Common Commands

# Login to PlanetScale (opens browser)
pscale auth login

# Logout
pscale auth logout

# Check current authentication status
pscale org show

Authentication Methods

1. Interactive Login (Default)

Opens browser for OAuth flow:

pscale auth login

Best for: Local development, first-time setup

2. Service Tokens (CI/CD)

For automated environments:

export PLANETSCALE_SERVICE_TOKEN_ID=<token-id>
export PLANETSCALE_SERVICE_TOKEN=<token>
pscale database list --org <org>

Best for: CI/CD pipelines, automation, production deployments

See pscale-service-token skill for token creation.

Workflows

First-Time Setup

# 1. Login
pscale auth login

# 2. Verify authentication
pscale org show

# 3. List databases to confirm access
pscale database list --org <org>

Switch Between Accounts

# Logout current account
pscale auth logout

# Login with different account
pscale auth login

CI/CD Authentication

# Create service token (see pscale-service-token)
pscale service-token create --org <org>

# Use in CI/CD environment
export PLANETSCALE_SERVICE_TOKEN_ID=<token-id>
export PLANETSCALE_SERVICE_TOKEN=<token>

# Test authentication
pscale database list --org <org>

Troubleshooting

Login fails / browser doesn't open

Symptoms: pscale auth login hangs or fails

Solutions:

• Check network connectivity
• Ensure firewall allows https://auth.planetscale.com
• Try headless browser auth (not supported by pscale, use service tokens instead)
• Use service token for non-interactive environments

"Unauthorized" errors

Symptoms: 401 Unauthorized or 403 Forbidden responses

Solutions:

• Run pscale auth logout && pscale auth login to refresh session
• Verify organization access: pscale org show
• Check service token hasn't expired (if using tokens)
• Ensure token has required permissions (database read/write, branch create, etc.)

Multiple accounts / wrong org

Symptoms: Cannot access expected databases

Solutions:

• Check current org: pscale org show
• Switch org: pscale org switch <org-name>
• List all orgs: pscale org list
• Logout and login with correct account

Service token authentication fails

Symptoms: Token authentication not working in CI/CD

Solutions:

• Verify both PLANETSCALE_SERVICE_TOKEN_ID and PLANETSCALE_SERVICE_TOKEN are set
• Check token hasn't been revoked: pscale service-token list --org <org>
• Ensure token has required permissions for the operation
• Use --debug flag to see authentication details

Related Skills

• pscale-service-token - Create and manage service tokens for CI/CD
• pscale-org - Switch between organizations
• pscale-database - Database operations requiring authentication

References

See references/commands.md for complete pscale auth command reference.

Manage authentication

Usage: pscale auth [command]

Available Commands: check Check if you are authenticated login Authenticate with the PlanetScale API logout Log out of the PlanetScale API

Flags: -h, --help help for auth

Global Flags: --api-token string The API token to use for authenticating against the PlanetScale API. --api-url string The base URL for the PlanetScale API. (default "https://api.planetscale.com/") --config string Config file (default is $HOME/.config/planetscale/pscale.yml) --debug Enable debug mode -f, --format string Show output in a specific format. Possible values: [human, json, csv] (default "human") --no-color Disable color output --service-token string Service Token for authenticating. --service-token-id string The Service Token ID for authenticating.

Use "pscale auth [command] --help" for more information about a command.

Create, list, show, and delete branch backups

Usage: pscale backup [command]

Available Commands: create Backup a branch's data and schema delete Delete a branch backup list List all backups of a branch restore Restore a backup to a new branch show Show a specific backup of a branch

Flags: -h, --help help for backup --org string The organization for the current user

Global Flags: --api-token string The API token to use for authenticating against the PlanetScale API. --api-url string The base URL for the PlanetScale API. (default "https://api.planetscale.com/") --config string Config file (default is $HOME/.config/planetscale/pscale.yml) --debug Enable debug mode -f, --format string Show output in a specific format. Possible values: [human, json, csv] (default "human") --no-color Disable color output --service-token string Service Token for authenticating. --service-token-id string The Service Token ID for authenticating.

Use "pscale backup [command] --help" for more information about a command.

Create, delete, diff, and manage branches

Usage: pscale branch [command]

Available Commands: create Create a new branch from a database delete Delete a branch from a database demote Demote a production branch to development diff Show the diff of a branch lint Lints the schema for a branch list List all branches of a database promote Promote a new branch from a database refresh-schema Refresh the schema for a database branch routing-rules Fetch or update your keyspace routing rules safe-migrations Enable or disable safe migrations on a branch schema Show the schema of a branch show Show a specific branch of a database switch Switches the current project to use the specified branch

Flags: -h, --help help for branch --org string The organization for the current user

Global Flags: --api-token string The API token to use for authenticating against the PlanetScale API. --api-url string The base URL for the PlanetScale API. (default "https://api.planetscale.com/") --config string Config file (default is $HOME/.config/planetscale/pscale.yml) --debug Enable debug mode -f, --format string Show output in a specific format. Possible values: [human, json, csv] (default "human") --no-color Disable color output --service-token string Service Token for authenticating. --service-token-id string The Service Token ID for authenticating.

Use "pscale branch [command] --help" for more information about a command.

Create, read, delete, and dump/restore databases

Usage: pscale database [command]

Aliases: database, db

Available Commands: create Create a database instance delete Delete a database instance dump Backup and dump your database (Vitess databases only) list List databases restore-dump Restore your database from a local dump directory (Vitess databases only) show Retrieve information about a database

Flags: -h, --help help for database --org string The organization for the current user

Global Flags: --api-token string The API token to use for authenticating against the PlanetScale API. --api-url string The base URL for the PlanetScale API. (default "https://api.planetscale.com/") --config string Config file (default is $HOME/.config/planetscale/pscale.yml) --debug Enable debug mode -f, --format string Show output in a specific format. Possible values: [human, json, csv] (default "human") --no-color Disable color output --service-token string Service Token for authenticating. --service-token-id string The Service Token ID for authenticating.

Use "pscale database [command] --help" for more information about a command.

Create, review, diff, revert, and manage deploy requests.

This command is only supported for Vitess databases.

Usage: pscale deploy-request [command]

Aliases: deploy-request, dr

Available Commands: apply Apply changes to a gated deploy request cancel Cancel a deploy request close Close a deploy request create Create a deploy request from a branch deploy Deploy a specific deploy request diff Show the diff of a deploy request edit Edit a deploy request list List all deploy requests for a database revert Revert a deployed deploy request review Review a deploy request (approve, comment, etc...) show Show a specific deploy request skip-revert Skip and close a pending deploy request revert

Flags: -h, --help help for deploy-request --org string The organization for the current user

Global Flags: --api-token string The API token to use for authenticating against the PlanetScale API. --api-url string The base URL for the PlanetScale API. (default "https://api.planetscale.com/") --config string Config file (default is $HOME/.config/planetscale/pscale.yml) --debug Enable debug mode -f, --format string Show output in a specific format. Possible values: [human, json, csv] (default "human") --no-color Disable color output --service-token string Service Token for authenticating. --service-token-id string The Service Token ID for authenticating.

Use "pscale deploy-request [command] --help" for more information about a command.

List, show, and switch organizations

Usage: pscale org [command]

Available Commands: list List the currently active organizations show Display the currently active organization switch Switch the currently active organization

Flags: -h, --help help for org

Global Flags: --api-token string The API token to use for authenticating against the PlanetScale API. --api-url string The base URL for the PlanetScale API. (default "https://api.planetscale.com/") --config string Config file (default is $HOME/.config/planetscale/pscale.yml) --debug Enable debug mode -f, --format string Show output in a specific format. Possible values: [human, json, csv] (default "human") --no-color Disable color output --service-token string Service Token for authenticating. --service-token-id string The Service Token ID for authenticating.

Use "pscale org [command] --help" for more information about a command.

Create, list, and delete branch passwords.

This command is only supported for Vitess databases.

Usage: pscale password [command]

Available Commands: create Create password to access a branch's data delete Delete a branch password list List all passwords of a database renew Renew a branch password

Flags: -h, --help help for password --org string The organization for the current user

Global Flags: --api-token string The API token to use for authenticating against the PlanetScale API. --api-url string The base URL for the PlanetScale API. (default "https://api.planetscale.com/") --config string Config file (default is $HOME/.config/planetscale/pscale.yml) --debug Enable debug mode -f, --format string Show output in a specific format. Possible values: [human, json, csv] (default "human") --no-color Disable color output --service-token string Service Token for authenticating. --service-token-id string The Service Token ID for authenticating.

Use "pscale password [command] --help" for more information about a command.

Create, list, and manage access for service tokens

Usage: pscale service-token [command]

Available Commands: add-access add access to a service token in the organization create create a service token for the organization delete delete an entire service token in an organization delete-access delete access granted to a service token in the organization list list service tokens for the organization show-access fetch a service token and its accesses

Flags: -h, --help help for service-token --org string The organization for the current user

Global Flags: --api-token string The API token to use for authenticating against the PlanetScale API. --api-url string The base URL for the PlanetScale API. (default "https://api.planetscale.com/") --config string Config file (default is $HOME/.config/planetscale/pscale.yml) --debug Enable debug mode -f, --format string Show output in a specific format. Possible values: [human, json, csv] (default "human") --no-color Disable color output --service-token string Service Token for authenticating. --service-token-id string The Service Token ID for authenticating.

Use "pscale service-token [command] --help" for more information about a command.

🌐 PlanetScale CLI Skills

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

 

🎯 What This Skill Provides

• 8 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

Via ClawHub

clawhub install planetscale-cli-skills

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

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

🛠️ 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

Refresh development branch with main:

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

🌊 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

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

🔗 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

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

PlanetScale CLI Skills - Automation Scripts

Token-efficient scripts for common PlanetScale operations. Execute without loading into context.

Available Scripts

🌿 create-branch-for-mr.sh

Create PlanetScale branch matching your MR or PR branch name.

Usage:

./scripts/create-branch-for-mr.sh --database <db> --branch <name> [--from <source>] [--org <org>]

Examples:

# Create branch for MR/PR
./scripts/create-branch-for-mr.sh \
  --database my-database \
  --branch feature-user-settings

# Create from specific source branch
./scripts/create-branch-for-mr.sh \
  --database my-db \
  --branch feature-x \
  --from development

# With organization
./scripts/create-branch-for-mr.sh \
  --database my-db \
  --branch feature-x \
  --org my-org

What it does:

• Creates new database branch
• Sources from main (or specified branch)
• Provides next steps (shell, diff, deploy request)

---

🚀 deploy-schema-change.sh

Create deploy request and optionally deploy schema changes.

Usage:

./scripts/deploy-schema-change.sh --database <db> --branch <name> [--deploy] [--org <org>]

Examples:

# Create deploy request only (manual deploy later)
./scripts/deploy-schema-change.sh \
  --database my-database \
  --branch feature-schema-v2

# Create and auto-deploy
./scripts/deploy-schema-change.sh \
  --database my-database \
  --branch feature-schema-v2 \
  --deploy

# With organization
./scripts/deploy-schema-change.sh \
  --database my-db \
  --branch feature-x \
  --org my-org \
  --deploy

What it does: 1. Creates deploy request from branch 2. Shows deploy request diff 3. Optionally deploys (if --deploy flag) 4. Shows final deploy request status

Token efficiency: ~95% savings (7-step manual process → 1 command)

---

🔄 sync-branch-with-main.sh

Refresh development branch schema with main branch.

Usage:

./scripts/sync-branch-with-main.sh --database <db> --branch <name> [--org <org>]

Examples:

# Sync branch with main
./scripts/sync-branch-with-main.sh \
  --database my-database \
  --branch feature-branch

# With organization
./scripts/sync-branch-with-main.sh \
  --database my-db \
  --branch dev-branch \
  --org my-org

What it does:

• Refreshes branch schema to match main
• Useful when main has been updated
• Prevents deployment conflicts

---

Benefits

Token Efficiency

Scripts execute without loading into context - only output consumes tokens. ~90-95% token savings for repetitive operations.

Deterministic Operations

No code regeneration needed for common tasks. Same input = same output.

Quick Workflows

Complete multi-step workflows in single commands.

Prerequisites

All Scripts

• pscale CLI installed and in PATH
• Authenticated (pscale auth login or service tokens)

For Service Token Auth

export PLANETSCALE_SERVICE_TOKEN_ID=<token-id>
export PLANETSCALE_SERVICE_TOKEN=<token>

Integration with Skills

Scripts are referenced from relevant skills:

• pscale-branch skill → create-branch-for-mr.sh, sync-branch-with-main.sh
• pscale-deploy-request skill → deploy-schema-change.sh

Error Handling

All scripts:

• Use set -e (exit on error)
• Return non-zero exit codes on failure
• Provide actionable error messages
• Include help via --help flag

Complete Workflow Examples

Schema Migration for MR/PR

# 1. Create PlanetScale branch matching MR branch
./scripts/create-branch-for-mr.sh \
  --database my-database \
  --branch feature-user-settings

# 2. Make schema changes
pscale shell my-database feature-user-settings
# ... run ALTER TABLE, etc.

# 3. Deploy schema change
./scripts/deploy-schema-change.sh \
  --database my-database \
  --branch feature-user-settings \
  --deploy

# 4. Pull schema back to Drizzle (if using Drizzle ORM)
pnpm drizzle-kit introspect

Sync Stale Branch Before Deploy

# If main has been updated since branch creation
./scripts/sync-branch-with-main.sh \
  --database my-database \
  --branch old-feature-branch

# Verify diff shows only your changes
pscale branch diff my-database old-feature-branch

# Then deploy
./scripts/deploy-schema-change.sh \
  --database my-database \
  --branch old-feature-branch \
  --deploy

CI/CD Integration

# In your CI/CD pipeline config (.github/workflows, .gitlab-ci.yml, etc.)

deploy-schema:
  script:
    # Create branch from CI branch name
    - ./scripts/create-branch-for-mr.sh \
        --database $DATABASE \
        --branch $CI_COMMIT_REF_NAME \
        --org $ORG
    
    # Apply schema changes (from migrations file, ORM, etc.)
    - pscale shell $DATABASE $CI_COMMIT_REF_NAME < migrations.sql
    
    # Deploy automatically
    - ./scripts/deploy-schema-change.sh \
        --database $DATABASE \
        --branch $CI_COMMIT_REF_NAME \
        --deploy \
        --org $ORG

Common Patterns

Drizzle ORM Schema Migration Pattern

Generic workflow for Drizzle users:

# 1. Edit your schema.sql file
vim schema.sql

# 2. Create PlanetScale branch
./scripts/create-branch-for-mr.sh \
  --database my-database \
  --branch $(git branch --show-current)

# 3. Apply schema changes
pscale shell my-database $(git branch --show-current) < schema.sql

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

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

Contributing

When adding new scripts: 1. Include --help flag with examples 2. Use set -e for bash scripts (exit on error) 3. Provide clear error messages 4. Document in this README 5. Reference from relevant SKILL.md files 6. Make scripts executable (chmod +x)

Script Dependencies

All scripts work with both interactive auth (pscale auth login) and service token auth (env vars).