PlanetScale CLI commands: auth

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.

The `auth` command

This command allows you to login, logout, and refresh your authentication. Auth tokens generated by pscale are valid for one month. Usage:

pscale auth <SUB-COMMAND> <FLAG>

Available sub-commands

Sub-Command	Description	Product
`login`	Authenticate with the PlanetScale API	Postgres, Vitess
`logout`	Log out of the PlanetScale API	Postgres, Vitess
`check`	Check if you are authenticated	Postgres, Vitess

Agents and automation should use --format json on auth check and auth login. Start with pscale agent-guide --format json or the Agent setup prompt.

Available flags

Flag	Description
`-h`, `--help`	View help for `auth` command

Global flags

Command	Description
`--api-token <TOKEN>`	The API token to use for authenticating against the PlanetScale API.
`--api-url <URL>`	The base URL for the PlanetScale API. Default is `https://api.planetscale.com/`.
`--config <CONFIG_FILE>`	Config file. Default is `$HOME/.config/planetscale/pscale.yml`.
`--debug`	Enable debug mode.
`-f`, `--format <FORMAT>`	Show output in a specific format. Possible values: `human` (default), `json`, `csv`.
`--no-color`	Disable color output.
`--service-token <TOKEN>`	The service token for authenticating.
`--service-token-id <TOKEN_ID>`	The service token ID for authenticating.

Examples

The `check` sub-command

Command:

pscale auth check

Output:

You are authenticated.

If you are not authenticated, exit code 1 will be returned. JSON mode (recommended for agents):

pscale auth check --format json

Returns a structured response with status, authenticated, auth_method, organization, issues, and next_steps.

`status`	Meaning
`ok`	Authenticated and ready (may include non-blocking notes such as missing org)
`action_required`	Exit code 2 — follow `issues` and `next_steps` (login, org switch, or fix credentials)

Service tokens in CI:

pscale auth check --format json \
  --service-token-id "$PLANETSCALE_SERVICE_TOKEN_ID" \
  --service-token "$PLANETSCALE_SERVICE_TOKEN"

Command:

pscale auth login --format json

Pending authorization JSON is written to stderr while waiting for browser approval. Stdout contains a single final JSON object when login completes (status: ok or action_required if organization setup fails after credentials are saved). Fields include verification_url, user_code, and browser_opened. Open verification_url manually if the browser does not open. Do not retry login in a loop without browser access.

pscale auth login

Output: A new browser tab will open and ask you to sign in via browser if you’re not already signed in. Next, you’ll be asked to confirm the Device confirmation code displayed in your terminal:

Confirmation Code: XXXXXXX

If they match, click “Confirm code”, and you’ll be signed in to the CLI.

The `logout` sub-command

Command:

pscale auth logout

Output:

Press Enter to log out of the PlanetScale API.

Need help?

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

Introduction

Using the pscale CLI

CLI command reference

PlanetScale CLI commands: auth

Getting Started

The `auth` command

Available sub-commands

Available flags

Global flags

Examples

The `check` sub-command

The `logout` sub-command

Need help?

​Getting Started

​The auth command

​Available sub-commands

​Available flags

​Global flags

​Examples

​The check sub-command

​The login sub-command (JSON for agents)

​The login sub-command (interactive)

​The logout sub-command

​Need help?

Getting Started

The `auth` command

Available sub-commands

Available flags

Global flags

Examples

The `check` sub-command

The `login` sub-command (JSON for agents)

The `login` sub-command (interactive)

The `logout` sub-command

Need help?