PlanetScale CLI for coding agents

If a coding agent can run shell commands against a PlanetScale database, it can use the pscale command-line interface (CLI) to check its connection and run SQL in scripts or non-interactive commands. PlanetScale offers MySQL databases (built on Vitess) and Postgres databases, and the CLI works with both. A branch is an isolated database inside a PlanetScale database. Changes to one branch's schema or data do not affect other branches, and the default branch, main, is the production branch.

For a read-only check, have the agent run a SELECT query against a named database branch and request JSON output, which scripts can parse more easily. The CLI also manages databases and branches. For Vitess databases, it handles schema changes through deploy requests, which let operators review proposed changes before deployment. Follow the PlanetScale CLI documentation for installation and the platform-specific authentication flow.

Prepare the CLI for an agent

PlanetScale’s documentation says the agent automation commands require pscale 0.292.0 or later. On macOS, install it with Homebrew. The setup page covers Linux packages and Scoop on Windows.

brew install pscale
pscale auth login

pscale auth login opens a browser and asks you to confirm a code shown in the terminal. After that, check the version and confirm the CLI can access the account:

pscale version
pscale auth check --format json

The check contacts PlanetScale and returns JSON that scripts can parse. If it reports "status": "action_required", its issues and next_steps fields say what to fix. For CI or another machine without a browser, the auth documentation uses a service token instead. Keep login credentials or service-token values in the approved local credential store or environment, rather than putting them in the agent prompt.

Before asking an agent to use the CLI, provide its built-in instructions:

pscale --skill

Or request the same guide as JSON:

pscale agent-guide --format json

The guide describes command syntax and automation rules. PlanetScale's agent setup prompt says to pass --format json on pscale commands in automation. Place positional arguments before flags. For example, provide the database and branch before --query and --format. Put --org on the resource subcommand, such as database, branch or sql, because the root pscale command does not accept it.

Run a read-only query

An agent can verify database access with a query that does not depend on application tables:

pscale sql <database> <branch> --org <org> --format json --query "SELECT 1 AS agent_check"

Replace the placeholders with real names that the signed-in account can access. The pscale sql command runs one query without an interactive shell and requires both --query and --org. It contacts PlanetScale and runs the SQL against that branch.

By default pscale sql connects with the reader role, so a write needs an explicit --role such as writer or admin. Queries that contain DELETE, DROP or TRUNCATE are blocked unless --force is passed. With JSON output, a blocked query returns "status": "action_required". PlanetScale's documentation tells agents to ask the user and only then rerun with --force. A successful JSON response includes fields such as status, row_count, columns and rows.

For an application-specific check, the agent can substitute a SELECT query against a known table. It should use the branch intended for the work and keep the query read-only. PlanetScale advises caution when granting language models write access to a production database; review any proposed write query before executing it. On Vitess databases, schema changes follow a separate path through deploy requests, which let operators review proposed changes before deployment.

Give the agent a bounded task

A useful prompt names the database branch, the permitted action, and what the agent should return. For example:

Use pscale to run a read-only check against the <database> database on the <branch> branch in the <org> organization. First confirm authentication with pscale auth check --format json. Then run SELECT 1 AS agent_check using pscale sql with --query and JSON output. Report whether the query succeeded and summarize the returned result. Do not run write queries, and do not pass --force or a write role.

The agent should follow the syntax in pscale agent-guide --format json, particularly if it needs to query application tables or pass values between commands. Keep credentials out of the prompt; the CLI uses the authentication already configured for the local environment.