Skip to main content

​
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-CommandDescriptionProduct
loginAuthenticate with the PlanetScale APIPostgres, Vitess
logoutLog out of the PlanetScale APIPostgres, Vitess
checkCheck if you are authenticatedPostgres, 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

FlagDescription
-h, --helpView help for auth command

​
Global flags

CommandDescription
--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.
--debugEnable debug mode.
-f, --format <FORMAT>Show output in a specific format. Possible values: human (default), json, csv.
--no-colorDisable 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.
statusMeaning
okAuthenticated and ready (may include non-blocking notes such as missing org)
action_requiredExit 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"

​
The login sub-command (JSON for agents)

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.

​
The login sub-command (interactive)

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.