Skip to content

PlanetScale CLI commands: api

Use the PlanetScale CLI to make authenticated calls against the PlanetScale API.

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 api command

A helper for constructing any call to the PlanetScale API. It can invoke any endpoint, whether support in equivalent commands of the CLI has been added or not. For these reasons, the api command is useful in cases such as scripting or where you might use curl against the API.

Usage:

Terminal
pscale api <ENDPOINT> <FLAG>

The <ENDPOINT> is a URL path such as /organizations/{org}/databases/{db}/branches/{branch}, omitting the v1 prefix. You can use placeholders such as {org}, {db} and {branch} in the endpoint, and these will be replaced by the values found in ~/.config/planetscale/pscale.yml and in the .pscale.yml at the root of the current Git repository (if present). These values can also be specified by the --org, --database, and --branch flags. Refer to the API documentation for details.

Available flags

FlagDescription
-h, --helpView help for audit-log command.
-F, --field key=valueHTTP body to send with the request, in key=value format.
-H, --header stringArrayHTTP headers to add to the request.
-I, --inputHTTP body to send with the request, as a file that will be read and then sent.
-X, --methodHTTP method to use for the request.
-Q, --queryQuery to append to the URL path, in key=value format.
--org <ORGANIZATION_NAME>The organization for the current user.
--database <DATABASE_NAME>The database for the current project.
--branch <BRANCH_NAME>The name of the current branch.

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

To get the current user:

Command:

Terminal
pscale api user

Output:

The body of the HTTP response.

To list an organization's databases:

Command:

Terminal
pscale api organizations/{org}/databases

Output:

The body of the HTTP response.

To create a database:

Command:

Terminal
pscale api organizations/{org}/databases -F 'name="my-database"'

Output:

The body of the HTTP response.

To get a database:

Command:

Terminal
pscale api organizations/{org}/databases/my-database

Output:

The body of the HTTP response.

To delete a database:

Command:

Terminal
pscale api -X DELETE organizations/{org}/databases/my-database

Output:

The body of the HTTP response.

To add a note on a database from the content of a file:

Command:

Terminal
pscale api -X PATCH organizations/{org}/databases/{db} -F 'notes=@mynotes.txt'

Output:

The body of the HTTP response.

To create a database branch from a file:

Command:

Terminal
pscale api organizations/{org}/databases/{db}/branches --input=spec.json

Output:

The body of the HTTP response.

To create a database branch from stdin, override the name:

Command:

Terminal
pscale api organizations/{org}/databases/{db}/branches --input=- -F 'name="my-name"'

Output:

The body of the HTTP response.

Need help?

Get help from the PlanetScale support team, or join our GitHub discussion board to see how others are using PlanetScale.

Was this page useful?
Last updated on Help us improve this page