Skip to main content
To interact with PlanetScale and manage your databases, you can use the pscale CLI to do the following:
  • Create, delete and list your databases and branches
  • Run non-interactive SQL for agents and scripts (pscale sql)
  • Open a secure MySQL or PostgreSQL shell instance
  • Manage your deploy requests
  • Bootstrap AI agents (pscale agent-guide)
  • …and more!
AI agents: start with the Agent setup prompt or pscale agent-guide --format json. Requires pscale 0.292.0+ — run brew upgrade pscale if agent-guide is unknown. Always pass --format json in automation.
pscale can use the MySQL command-line client to quickly open an interactive shell for a database branch. Optional instructions for installing the MySQL client can be found for each platform below.

​
Getting Started

Make sure to first set up your PlanetScale developer environment. Once you’ve installed the pscale CLI, you can interact with PlanetScale and manage your databases straight from the command line.

​
Available Commands

Use pscale [command] [command] to start up the pscale CLI in your terminal.
CommandSubcommands/OptionsFlagsProductDescription
agent-guide--format jsonVitess, PostgresBootstrap JSON for AI agents; embeds CLI conventions and skills/MCP hints
api--help, --org string, --database string, --branch string, --field key=value, --header stringArray, --input string, --method string, --query key=valueVitess, PostgresPerforms authenticated calls against the PlanetScale API and prints the response to stdout.
audit-loglist--help, --org stringVitess, PostgresList all audit logs
authlogin, logout, check--help, --format jsonVitess, PostgresAuthenticate via console or JSON device login for agents
backupcreate, delete, list, restore, show--help, --org stringVitess, PostgresManage branch backups
branchconnections, create, delete, diff, keyspaces, list, promote, refresh-schema, schema, show, switch, vschema--help, --org stringVitess, PostgresManage branches
completionbash, zsh, fish, powershell--helpVitess, PostgresGenerate completion script for specified shell
connect<database_name> <branch_name>--execute string, --execute-env-url string, --execute-protocol string, --help, --host string, --org string, --port string, --remote-addr string, --role stringVitessCreate a secure connection to the given database and branch
databasecreate, delete, dump, list, restore-dump, show--helpVitess, PostgresManage databases
deploy-requestapply, cancel, close, create, deploy, diff, edit, list, revert, review, show, skip-revert--helpVitessManage deploy requests including gated deployments
helpagent-guide, audit-log, auth, backup, branch, completion, connect, database, deploy-request, help, mcp, org, password, ping, region, role, service-token, shell, signup, size, sql, traffic-control, webhook, workflow--helpVitess, PostgresView help for any command
orglist, show, switch--helpVitess, PostgresManage and switch organizations
mcpinstall, server--target string (cursor|claude-code|zed), --format json, --helpVitess, PostgresInstall hosted MCP config (docs)
passwordcreate, delete, list--help, --org stringVitessManage branch credentials
ping--help, --count, -n int, --concurrency int, --provider, -p string --timeout durationVitess, PostgresCheck latency between your machine and PlanetScale’s public regions
regionlist--org stringVitess, PostgresView available regions
rolecreate, delete, get, list, reassign, renew, reset, reset-default, update--help, --org string, --inherited-roles string, --ttl duration, --force, --successor string, --name string, --webPostgresManage Postgres roles
service-tokenadd-access, create, delete, delete-access, list, show-access--help, --org stringVitess, PostgresManage access of service tokens
sizecluster list--help, --org string, --region string, --metalVitess, PostgresView available cluster sizes
traffic-controlbudget, rule--help, --org stringPostgresManage Database Traffic Control budgets and rules for a Postgres database branch
shell<database_name> <branch_name>--help, --local-addr string, --org string, --remote-addr string, --role string, --replicaVitess, PostgresOpen an interactive shell to the specified database and branch
signup--helpVitess, PostgresSign up for a new PlanetScale account
sql<database> <branch>--org string, --query string, --role string, --replica, --dbname string, --keyspace string, --force, --format jsonVitess, PostgresExecute a SQL query without an interactive shell (agents/scripts)
webhookcreate, delete, list, show, test, update--help, --org string, --events string, --url string, --enabledVitess, PostgresManage webhooks for databases
workflowcancel, complete, create, cutover, list, retry, reverse-cutover, reverse-traffic, show, switch-traffic, verify-data--help, --org stringVitessManage the workflows for PlanetScale databases

​
Flags

You may use the following flags with the PlanetScale CLI commands.
FlagDescription
--api-token stringThe API token to use for authenticating against the PlanetScale API
--api-url stringThe base URL for the PlanetScale API. (default “https://api.planetscale.com/“)
--config stringConfig file (default: $HOME/.config/planetscale/pscale.yml)
--debugEnable debug mode
-f, --format stringShow output in specific format. Possible values: [human, json, csv] (default: “human”)
-h, --helpGet more information about a command
--no-colorDisable color output
--service-token stringService Token for authenticating
--service-token-id stringThe Service Token ID for authenticating
--versionShow pscale version

​
Service tokens permissions

A complete list of access permissions available for use with service tokens can be found in the PlanetScale API documentation.

​
Need help?

Get help from the PlanetScale Support team, or join our Discord community to see how others are using PlanetScale.