> ## 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 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!

<Card title="Install pscale" icon="download" horizontal href="/docs/cli/planetscale-environment-setup">
  Install or upgrade the PlanetScale CLI for macOS, Linux, or Windows.
</Card>

Agents and automation should start with the [Agent setup prompt](/docs/agent-setup/prompt) 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.
</Note>

## Getting Started

Make sure to first [set up your PlanetScale developer environment](/docs/cli/planetscale-environment-setup). 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`](/docs/cli/agent-guide)         |                                                                                                                                                                                                                                                                                  | `--format json`                                                                                                                                                                  | Vitess, Postgres | Bootstrap JSON for AI agents; embeds CLI conventions and skills/MCP hints                                                                                                        |
| [`api`](/docs/cli/api)                         |                                                                                                                                                                                                                                                                                  | `--help`, `--org string`, `--database string`, `--branch string`, `--field key=value`, `--header stringArray`, `--input string`, `--method string`, `--query key=value`          | Vitess, Postgres | Performs authenticated calls against the PlanetScale API and prints the response to stdout.                                                                                      |
| [`audit-log`](/docs/cli/audit-log)             | `list`                                                                                                                                                                                                                                                                           | `--help`, `--org string`                                                                                                                                                         | Vitess, Postgres | List all [audit logs](/docs/security/audit-log#review-your-organization-audit-log)                                                                                                    |
| [`auth`](/docs/cli/auth)                       | `login`, `logout`, `check`                                                                                                                                                                                                                                                       | `--help`, `--format json`                                                                                                                                                        | Vitess, Postgres | Authenticate via console or JSON device login for agents                                                                                                                         |
| [`backup`](/docs/cli/backup)                   | `create`, `delete`, `list`, `restore`, `show`                                                                                                                                                                                                                                    | `--help`, `--org string`                                                                                                                                                         | Vitess, Postgres | Manage [branch backups](/docs/vitess/backups)                                                                                                                                         |
| [`branch`](/docs/cli/branch)                   | `connections`, `create`, `delete`, `diff`, `keyspaces`, `list`, `promote`, `query-patterns`, `refresh-schema`, `schema`, `show`, `switch`, `vschema`                                                                                                                             | `--help`, `--org string`                                                                                                                                                         | Vitess, Postgres | Manage [branches](/docs/vitess/schema-changes/branching)                                                                                                                              |
| [`completion`](/docs/cli/completion)           | `bash`, `zsh`, `fish`, `powershell`                                                                                                                                                                                                                                              | `--help`                                                                                                                                                                         | Vitess, Postgres | Generate completion script for specified shell                                                                                                                                   |
| [`connect`](/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](/docs/vitess/tutorials/connect-any-application#option-2-connect-using-the-planetscale-proxy) to the given database and branch                            |
| [`database`](/docs/cli/database)               | `create`, `delete`, `dump`, `list`, `restore-dump`, `show`                                                                                                                                                                                                                       | `--help`                                                                                                                                                                         | Vitess, Postgres | Manage databases                                                                                                                                                                 |
| [`deploy-request`](/docs/cli/deploy-request)   | `apply`, `cancel`, `close`, `create`, `deploy`, `diff`, `edit`, `list`, `revert`, `review`, `show`, `skip-revert`                                                                                                                                                                | `--help`                                                                                                                                                                         | Vitess           | Manage [deploy requests](/docs/vitess/schema-changes/deploy-requests#create-a-deploy-request) including [gated deployments](/docs/vitess/schema-changes/deploy-requests#gated-deployments) |
| `help`                                    | `agent-guide`, `audit-log`, `auth`, `backup`, `branch`, `completion`, `connect`, `database`, `deploy-request`, `help`, `import`, `mcp`, `org`, `password`, `ping`, `region`, `role`, `service-token`, `shell`, `signup`, `size`, `sql`, `traffic-control`, `webhook`, `workflow` | `--help`                                                                                                                                                                         | Vitess, Postgres | View help for any command                                                                                                                                                        |
| [`import`](/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](/docs/postgres/imports/postgres-imports)) into PlanetScale Postgres                                                                        |
| [`org`](/docs/cli/org)                         | `list`, `show`, `switch`                                                                                                                                                                                                                                                         | `--help`                                                                                                                                                                         | Vitess, Postgres | Manage and switch [organizations](/docs/security/access-control)                                                                                                                      |
| [`mcp`](/docs/cli/mcp)                         | `install`, `server`                                                                                                                                                                                                                                                              | `--target string (cursor\|claude-code\|zed)`, `--format json`, `--help`                                                                                                          | Vitess, Postgres | Install hosted MCP config ([docs](/docs/connect/mcp))                                                                                                                                 |
| [`password`](/docs/cli/password)               | `create`, `delete`, `list`                                                                                                                                                                                                                                                       | `--help`, `--org string`                                                                                                                                                         | Vitess           | Manage [branch credentials](/docs/vitess/connecting/connection-strings)                                                                                                               |
| [`ping`](/docs/cli/ping)                       |                                                                                                                                                                                                                                                                                  | `--help`, `--count, -n int`, `--concurrency int`, `--provider, -p string` `--timeout duration`                                                                                   | Vitess, Postgres | Check [latency](/docs/vitess/connecting/network-latency) between your machine and PlanetScale's public regions                                                                        |
| [`region`](/docs/cli/region)                   | `list`                                                                                                                                                                                                                                                                           | `--org string`                                                                                                                                                                   | Vitess, Postgres | View available [regions](/docs/vitess/regions)                                                                                                                                        |
| [`role`](/docs/cli/role)                       | `create`, `delete`, `get`, `list`, `reassign`, `renew`, `reset`, `reset-default`, `update`                                                                                                                                                                                       | `--help`, `--org string`, `--inherited-roles string`, `--ttl duration`, `--force`, `--successor string`, `--name string`, `--web`                                                | Postgres         | Manage [Postgres roles](/docs/postgres/connecting/roles)                                                                                                                              |
| [`service-token`](/docs/cli/service-token)     | `add-access`, `create`, `delete`, `delete-access`, `list`, `show-access`                                                                                                                                                                                                         | `--help`, `--org string`                                                                                                                                                         | Vitess, Postgres | Manage access of [service tokens](/docs/api/reference/service-tokens)                                                                                                                 |
| [`size`](/docs/planetscale-plans)              | `cluster list`                                                                                                                                                                                                                                                                   | `--help`, `--org string`, `--region string`, `--metal`                                                                                                                           | Vitess, Postgres | View available [cluster sizes](/docs/planetscale-plans)                                                                                                                               |
| [`traffic-control`](/docs/cli/traffic-control) | `budget`, `rule`                                                                                                                                                                                                                                                                 | `--help`, `--org string`                                                                                                                                                         | Postgres         | Manage [Database Traffic Control](/docs/postgres/traffic-control) budgets and rules for a Postgres database branch                                                                    |
| [`shell`](/docs/cli/shell)                     | `<database_name>` `<branch_name>`                                                                                                                                                                                                                                                | `--help`, `--local-addr string`, `--org string`, `--remote-addr string`, `--role string`, `--replica`                                                                            | Vitess, Postgres | Open an interactive shell to the specified database and branch                                                                                                                   |
| [`signup`](/docs/cli/signup)                   |                                                                                                                                                                                                                                                                                  | `--help`                                                                                                                                                                         | Vitess, Postgres | Sign up for a new PlanetScale account                                                                                                                                            |
| [`sql`](/docs/cli/sql)                         | `<database>` `<branch>`                                                                                                                                                                                                                                                          | `--org string`, `--query string`, `--role string`, `--replica`, `--dbname string`, `--keyspace string`, `--force`, `--format json`                                               | Vitess, Postgres | Execute a SQL query without an interactive shell (agents/scripts)                                                                                                                |
| [`webhook`](/docs/cli/webhook)                 | `create`, `delete`, `list`, `show`, `test`, `update`                                                                                                                                                                                                                             | `--help`, `--org string`, `--events string`, `--url string`, `--enabled`                                                                                                         | Vitess, Postgres | Manage [webhooks](/docs/api/webhooks) for databases                                                                                                                                   |
| [`workflow`](/docs/cli/workflow)               | `cancel`, `complete`, `create`, `cutover`, `list`, `retry`, `reverse-cutover`, `reverse-traffic`, `show`, `switch-traffic`, `verify-data`                                                                                                                                        | `--help`, `--org string`                                                                                                                                                         | Vitess           | Manage the workflows for PlanetScale databases                                                                                                                                   |

## 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                                                                        |
| `--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](/docs/api/reference/service-tokens#access-permissions).

## Service token automation

Running `pscale` in CI or an AI agent uses a [service token](/docs/cli/service-tokens) 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`.
</Warning>

Per-command-family matrices (env-var auth, `--service-token` flag, required `--org`, Postgres/Vitess, `--format json`, API equivalent): [`org`](/docs/cli/org#service-token-automation-org) · [`service-token`](/docs/cli/service-token#service-token-automation-service-token) · [`database`](/docs/cli/database#service-token-automation-database) · [`branch`](/docs/cli/branch#service-token-automation-branch) · [`role`](/docs/cli/role#service-token-automation-role) · [`password`](/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](/docs/api/reference/service-tokens) | `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`](/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`.
</Warning>

`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.