pscale-auth - SKILL.md Agent Skill

name: pscale-auth description: Manage PlanetScale CLI authentication including login/logout, check auth status, and switch accounts. Use when setting up pscale for first time, troubleshooting auth issues, switching PlanetScale accounts, or managing authentication sessions. Triggers on auth, login, logout, authentication, credentials, PlanetScale account.

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.