> ## Documentation Index
> Fetch the complete documentation index at: https://planetscale.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# PlanetScale CLI

To interact with PlanetScale and manage your databases, you can use the `pscale` CLI to do the following:

* Create, delete and list your Vitess, Neki, and Postgres databases and branches
* Run non-interactive SQL for agents and scripts (`pscale sql`)
* Open a secure MySQL or PostgreSQL shell instance, including Neki router and replica routing
* Manage Neki configuration profiles, shards, routers, sidecars, and data topology
* Manage your deploy requests
* Bootstrap AI agents (`pscale agent-guide`)
* ...and more!

> **[Install pscale](https://planetscale.com/docs/cli/planetscale-environment-setup.md)**
>
> Install or upgrade the PlanetScale CLI for macOS, Linux, or Windows.

Agents and automation should start with the [Agent setup prompt](https://planetscale.com/docs/agent-setup/prompt.md), `pscale --skill`, or `pscale agent-guide --format json`. Agent automation commands require `pscale` 0.292.0 or later; run `brew upgrade pscale` if `agent-guide` is unknown. Always pass `--format json` in automation.

> [!NOTE]
>
> `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](https://planetscale.com/docs/cli/planetscale-environment-setup.md). 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.

| **Command** | **Subcommands/Options** | **Flags** | **Product** | **Description** |
| :- | :- | :- | :- | :- |
| [`agent-guide`](https://planetscale.com/docs/cli/agent-guide) | | `--format json`, `--skill` | Vitess, Postgres, Neki | Bootstrap JSON for AI agents or print the installable agent skill |
| [`api`](https://planetscale.com/docs/cli/api) | | `--help`, `--org string`, `--database string`, `--branch string`, `--field key=value`, `--header stringArray`, `--input string`, `--method string`, `--query key=value` | Vitess, Postgres, Neki | Performs authenticated calls against the PlanetScale API and prints the response to stdout. |
| [`audit-log`](https://planetscale.com/docs/cli/audit-log) | `list`, `auth-attempts download` | `--help`, `--org string` | Vitess, Postgres, Neki | List all [audit logs](https://planetscale.com/docs/security/audit-log.md#review-your-organization-audit-log) and download authentication-attempt exports |
| [`auth`](https://planetscale.com/docs/cli/auth) | `login`, `logout`, `check` | `--help`, `--format json` | Vitess, Postgres, Neki | Authenticate via console or JSON device login for agents |
| [`backup`](https://planetscale.com/docs/cli/backup) | `create`, `delete`, `list`, `policy`, `restore`, `restore show`, `show`, `update` | `--help`, `--org string` | Vitess, Postgres, Neki | Manage [Vitess](https://planetscale.com/docs/vitess/backups.md), [Postgres](https://planetscale.com/docs/postgres/backups.md), and [Neki](https://planetscale.com/docs/neki/backups.md) branch backups |
| [`billing`](https://planetscale.com/docs/cli/billing) | `payment-method` | `--help`, `--org string` | Vitess, Postgres, Neki | Show, update, or delete the organization [payment method](https://planetscale.com/docs/billing.md#payment-methods) |
| [`branch`](https://planetscale.com/docs/cli/branch) | `admin`, `config-profile`, `connections`, `create`, `data-topology`, `delete`, `demote`, `diff`, `extensions list`, `lint`, `list`, `maintenance`, `parameters list`, `promote`, `query-patterns`, `refresh-schema`, `resize`, `router`, `routing-rules`, `safe-migrations`, `schema`, `shard`, `show`, `sidecar`, `switch`, `switchover`, `update`, `vtctld`, `vtgate` | `--help`, `--org string` | Vitess, Postgres, Neki | Manage [Vitess](https://planetscale.com/docs/vitess/schema-changes/branching.md), [Postgres](https://planetscale.com/docs/postgres/branching.md), and [Neki](https://planetscale.com/docs/neki/branching.md) branches, including [Neki configuration](https://planetscale.com/docs/neki/cluster-configuration.md) |
| [`completion`](https://planetscale.com/docs/cli/completion) | `bash`, `zsh`, `fish`, `powershell` | `--help` | Vitess, Postgres, Neki | Generate completion script for specified shell |
| [`connect`](https://planetscale.com/docs/cli/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 string` | Vitess | Create a [secure connection](https://planetscale.com/docs/vitess/tutorials/connect-any-application.md#option-2-connect-using-the-planetscale-proxy) to the given database and branch |
| [`database`](https://planetscale.com/docs/cli/database) | `aggressive-cutover`, `create`, `delete`, `dump`, `ip-restriction`, `list`, `read-only-regions`, `regions`, `restore-dump`, `show`, `throttler`, `update` | `--help` | Vitess, Postgres, Neki | Manage databases |
| `dedicated-read-replica` | `create`, `delete`, `list`, `show`, `update` | `--help`, `--org string`, `--region string`, `--replicas int`, `--cluster-size string`, `--parameters stringArray`, `--force` | Postgres | Manage dedicated read replicas for a Postgres branch |
| [`deploy-request`](https://planetscale.com/docs/cli/deploy-request) | `apply`, `cancel`, `close`, `create`, `deploy`, `deployment`, `diff`, `force-cutover`, `list`, `operations`, `queue`, `retry`, `revert`, `review`, `reviews`, `show`, `skip-revert`, `storage-check`, `throttler`, `unblock`, `update` | `--help` | Vitess | Manage [deploy requests](https://planetscale.com/docs/vitess/schema-changes/deploy-requests.md#create-a-deploy-request) including [gated deployments](https://planetscale.com/docs/vitess/schema-changes/deploy-requests.md#gated-deployments) |
| `help` | `agents`, `agent-guide`, `api`, `audit-log`, `auth`, `backup`, `billing`, `branch`, `completion`, `connect`, `database`, `dedicated-read-replica`, `deploy-request`, `help`, `import`, `insights`, `inspect`, `keyspace`, `logs`, `maintenance`, `metrics`, `org`, `password`, `pgbouncer`, `ping`, `region`, `role`, `service-token`, `shell`, `signup`, `size`, `sql`, `traffic-control`, `webhook`, `workflow` | `--help` | Vitess, Postgres, Neki | View help for any command or the agent automation help topic |
| [`import`](https://planetscale.com/docs/cli/import) | `d1 doctor`, `d1 lint`, `d1 convert-schema`, `d1 start`, `d1 verify`, `d1 status`, `d1 complete` | `--help`, `--org string` | Postgres | Import external databases ([Cloudflare D1](https://planetscale.com/docs/postgres/imports/postgres-imports.md)) into PlanetScale Postgres |
| [`insights`](https://planetscale.com/docs/cli/insights) | `queries`, `queries samples`, `queries show`, `queries summary`, `queries traffic-budgets`, `errors`, `errors show`, `anomalies`, `anomalies show`, `tags`, `tags show`, `tags summaries`, `recommendations`, `recommendations show`, `recommendations dismiss` | `--help`, `--org string`, `--format json` | Vitess, Postgres, Neki | Server-side query insights, anomalies, and schema recommendations from production traffic |
| [`inspect`](https://planetscale.com/docs/cli/inspect) | `all`, `table-sizes`, `index-sizes`, `unused-indexes`, `redundant-indexes`, `invalid-indexes`, `seq-scans`, `long-running-queries`, `locks`, `outliers`, `calls`, `bloat`, `vacuum-stats`, `replication-slots`, `subscriptions` | `--help`, `--org string`, `--format json`, `--keyspace string`, `--dbname string`, `--role string`, `--replica` | Vitess, Postgres, Neki | Live, read-only diagnostic checks over a direct database connection |
| [`logs`](https://planetscale.com/docs/cli/logs) | `<database>` `<branch>` | `--help`, `--org string`, `--query string`, `--period string`, `--from string`, `--to string`, `--level string`, `--server string`, `--shard string`, `--limit int`, `--page int` | Postgres, Neki | Query recent [Postgres](https://planetscale.com/docs/postgres/monitoring/logs.md) or [Neki](https://planetscale.com/docs/neki/monitoring/logs.md) branch logs |
| [`keyspace`](https://planetscale.com/docs/cli/keyspace) | `create`, `create-external`, `delete`, `list`, `parameters`, `read-only-regions`, `resize`, `rollout-status`, `settings`, `show`, `update-settings`, `vschema` | `--help`, `--org string` | Vitess | Manage [keyspaces](https://planetscale.com/docs/vitess/sharding/keyspaces.md) within a database branch, including [external keyspaces](https://planetscale.com/docs/cli/keyspace.md#create-an-external-keyspace) |
| [`maintenance`](https://planetscale.com/docs/cli/maintenance) | `list`, `show`, `windows` | `--help`, `--org string` | Vitess | View planned maintenance schedules and windows for a database |
| [`org`](https://planetscale.com/docs/cli/org) | `list`, `member`, `show`, `sso`, `switch`, `team`, `update` | `--help` | Vitess, Postgres, Neki | Manage and switch [organizations](https://planetscale.com/docs/security/access-control.md), including members, teams, and SSO |
| [`metrics`](https://planetscale.com/docs/cli/metrics) | `instant`, `keyspace-tables`, `queries`, `report`, `show`, `tables`, `tablets`, `tags` | `--help`, `--org string`, `--format json`, `--metric string`, `--period string`, `--from string`, `--to string`, `--steps int` | Vitess, Postgres, Neki | Query historical and current branch metrics from PlanetScale's metrics service |
| [`move-tables`](https://planetscale.com/docs/cli/move-tables) | `list`, `create`, `show`, `status`, `start`, `stop`, `switch-traffic`, `reverse-traffic`, `complete`, `cancel` | `--help`, `--org string` | Vitess | Move tables between keyspaces and [import external MySQL databases](https://planetscale.com/docs/vitess/imports/database-imports.md) with [Vitess MoveTables](https://planetscale.com/docs/cli/move-tables.md) (`pscale branch vtctl move-tables`) |
| [`password`](https://planetscale.com/docs/cli/password) | `create`, `delete`, `list`, `renew`, `show`, `update` | `--help`, `--org string`, `--name string`, `--new-name string`, `--cidrs strings`, `--status string` | Vitess | Manage [branch credentials](https://planetscale.com/docs/vitess/connecting/connection-strings.md) |
| [`pgbouncer`](https://planetscale.com/docs/cli/pgbouncer) | `create`, `delete`, `list`, `resize`, `show` | `--help`, `--org string` | Postgres | Manage dedicated [PgBouncers](https://planetscale.com/docs/postgres/connecting/pgbouncer.md) for a Postgres branch |
| [`ping`](https://planetscale.com/docs/cli/ping) | | `--help`, `--count, -n int`, `--concurrency int`, `--provider, -p string` `--timeout duration` | Vitess, Postgres, Neki | Check [latency](https://planetscale.com/docs/vitess/connecting/network-latency.md) between your machine and PlanetScale's public regions |
| [`region`](https://planetscale.com/docs/cli/region) | `list` | `--org string` | Vitess, Postgres, Neki | View available [regions](https://planetscale.com/docs/vitess/regions.md) |
| [`role`](https://planetscale.com/docs/cli/role) | `create`, `default`, `delete`, `get`, `list`, `reassign`, `renew`, `reset`, `reset-default`, `update` | `--help`, `--org string`, `--inherited-roles string`, `--ttl duration`, `--force`, `--successor string`, `--name string`, `--web` | Postgres, Neki | Manage [Postgres](https://planetscale.com/docs/postgres/connecting/roles.md) and [Neki](https://planetscale.com/docs/neki/connecting/roles.md) roles |
| [`service-token`](https://planetscale.com/docs/cli/service-token) | `add-access`, `create`, `delete`, `delete-access`, `list`, `show-access` | `--help`, `--org string` | Vitess, Postgres, Neki | Manage access of [service tokens](https://planetscale.com/docs/api/reference/service-tokens.md) |
| [`size`](https://planetscale.com/docs/cli/size) | `cluster list` | `--help`, `--org string`, `--engine string`, `--region string`, `--metal`, `--external` | Vitess, Postgres, Neki | View available [cluster sizes](https://planetscale.com/docs/planetscale-plans.md), including [external keyspace sizes](https://planetscale.com/docs/cli/size.md#list-external-keyspace-cluster-sizes) |
| [`traffic-control`](https://planetscale.com/docs/cli/traffic-control) | `budget`, `rule` | `--help`, `--org string` | Postgres | Manage [Database Traffic Control](https://planetscale.com/docs/postgres/traffic-control.md) budgets and rules for a Postgres database branch |
| [`shell`](https://planetscale.com/docs/cli/shell) | `<database_name>` `[branch_name]` `[db_name]` | `--help`, `--db-name string`, `--local-addr string`, `--org string`, `--remote-addr string`, `--role string`, `--replica`, `--router` | Vitess, Postgres, Neki | Open an interactive shell to the specified database and branch |
| [`signup`](https://planetscale.com/docs/cli/signup) | | `--help` | Vitess, Postgres, Neki | Sign up for a new PlanetScale account |
| [`sql`](https://planetscale.com/docs/cli/sql) | `<database>` `<branch>` | `--org string`, `--query string`, `--role string`, `--replica`, `--dbname string`, `--keyspace string`, `--force`, `--vertical`, `--format json` | Vitess, Postgres, Neki | Execute a SQL query without an interactive shell (agents/scripts) |
| [`webhook`](https://planetscale.com/docs/cli/webhook) | `create`, `delete`, `list`, `show`, `test`, `update` | `--help`, `--org string`, `--events string`, `--url string`, `--enabled` | Vitess, Postgres, Neki | Manage [webhooks](https://planetscale.com/docs/api/webhooks.md) for databases |
| [`workflow`](https://planetscale.com/docs/cli/workflow) | `cancel`, `complete`, `create`, `cutover`, `list`, `retry`, `reverse-cutover`, `reverse-traffic`, `show`, `switch-traffic`, `verify-data` | `--help`, `--org string` | Vitess | Deprecated. Use [`move-tables`](https://planetscale.com/docs/cli/move-tables) instead |

## Flags

You may use the following flags with the PlanetScale CLI commands.

| **Flag** | **Description** |
| :- | :- |
| `--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/](https://api.planetscale.com/)") |
| `--config string` | Config file *(default: `$HOME/.config/planetscale/pscale.yml`)* |
| `--debug` | Enable debug mode |
| `-f, --format string` | Show output in specific format. Possible values: *\[human, json, csv] (default: "human")* |
| `-h, --help` | Get more information about a command |
| `--no-color` | Disable color output |
| `--service-token string` | Service Token for authenticating |
| `--service-token-id string` | The Service Token ID for authenticating |
| `--skill` | Print the installable agent skill file and exit |
| `--version` | Show 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](https://planetscale.com/docs/api/reference/service-tokens.md#access-permissions).

## Service token automation

Running `pscale` in CI or an AI agent uses a [service token](https://planetscale.com/docs/cli/service-tokens.md) instead of `pscale auth login`. Provide the token as environment variables (recommended) or as flags on each command; both are equivalent:

```bash theme={null}
# Environment variables (recommended for CI and agents)
export PLANETSCALE_SERVICE_TOKEN_ID="<SERVICE_TOKEN_ID>"
export PLANETSCALE_SERVICE_TOKEN="<SERVICE_TOKEN>"

# Or per-command flags
pscale database list --org <org> \
  --service-token-id "<SERVICE_TOKEN_ID>" \
  --service-token "<SERVICE_TOKEN>"
```

A service token has **no active organization**, so resource commands need the org supplied explicitly. Set it with `PLANETSCALE_ORG`, the `--org` flag on the subcommand, or `pscale org switch <org>` (which works with a service token):

```bash theme={null}
export PLANETSCALE_ORG="<org>"
pscale database list --format json          # uses PLANETSCALE_ORG
pscale database list --org <org> --format json   # explicit flag
```

> [!WARNING]
>
> `--org` goes on the **resource subcommand** (`database`, `branch`, `sql`, `api`, …), never on root `pscale`. `pscale --org <org> database list` fails with `unknown flag: --org`.

Per-command-family matrices (env-var auth, `--service-token` flag, required `--org`, Postgres/Vitess, `--format json`, API equivalent): [`org`](https://planetscale.com/docs/cli/org#service-token-automation-org) · [`service-token`](https://planetscale.com/docs/cli/service-token#service-token-automation-service-token) · [`database`](https://planetscale.com/docs/cli/database#service-token-automation-database) · [`branch`](https://planetscale.com/docs/cli/branch#service-token-automation-branch) · [`role`](https://planetscale.com/docs/cli/role#service-token-automation-role) · [`password`](https://planetscale.com/docs/cli/password#service-token-automation-password).

### Commands to avoid under a service token

Do not retry these with service-token auth. The failure is by design, not transient. This is the most common cause of agent retry loops.

| Command | Why | Do this instead | Exact error |
| :- | :- | :- | :- |
| `pscale org show` | A service token has no "current" organization | `pscale org list --format json`, then pass `--org` or `PLANETSCALE_ORG` | `not authenticated yet. Please run 'pscale auth login'` |
| `pscale service-token list` | Token management is blocked when authenticated with a token | `pscale api organizations/<org>/service-tokens --format json` | `pscale service-token list is unavailable when authenticated with a service token` |
| `pscale service-token show-access` | Same as `list` | `pscale api organizations/<org>/service-tokens/<id> --format json` | `pscale service-token show-access is unavailable when authenticated with a service token` |
| `pscale service-token` (other sub-commands) | Create/manage tokens blocked under service-token auth | `pscale auth login`, then CLI; or [Service tokens API](https://planetscale.com/docs/api/reference/service-tokens.md) | `pscale service-token <sub-command> is unavailable when authenticated with a service token` |
| `pscale auth login` / `logout` | Not needed; the token is the credential | Set the token env vars; run `pscale auth check --format json` to confirm | requires an interactive browser device flow |
| `pscale shell` / `connect` | Interactive sessions | Use [`pscale sql`](https://planetscale.com/docs/cli/sql) for non-interactive queries | opens an interactive session |

> [!WARNING]
>
> `pscale org show` prints `not authenticated yet. Please run 'pscale auth login'` under a valid service token. This is the **no-current-org** state, not an auth failure. Do **not** respond by running `pscale auth login`. Discover the org with `pscale org list` and pass it with `--org` or `PLANETSCALE_ORG`.

`pscale auth check --format json` confirms a token is wired up. Expect `"authenticated": true`, `"auth_method": "service_token"`, and (until an org is set) an `action_required` status with a `NO_ORG` issue and a non-zero exit code. Resolve it by passing `--org`/`PLANETSCALE_ORG` on your commands.

### `pscale api` fallback for hard-to-parse output

When a command's human output is hard to parse, prefer `--format json`, or drop to the raw API with `pscale api`, which returns the API response verbatim and uses the same token:

```bash theme={null}
# org list
pscale api organizations --format json

# database list / show
pscale api organizations/<org>/databases --format json
pscale api organizations/<org>/databases/<database> --format json

# branch list / show
pscale api organizations/<org>/databases/<database>/branches --format json
pscale api organizations/<org>/databases/<database>/branches/<branch> --format json

# service-token list / show-access (CLI blocked under service-token auth)
pscale api organizations/<org>/service-tokens --format json
pscale api organizations/<org>/service-tokens/<id> --format json
```

## Need help?

Get help from [the PlanetScale Support team](https://planetscale.com/contact?initial=support), or join our [Discord community](https://pscale.link/community) to see how others are using PlanetScale.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.