Navigation

PlanetScale CLI commands: 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:

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:

pscale api user

Output:

The body of the HTTP response.

To list an organization's databases:

Command:

pscale api organizations/{org}/databases

Output:

The body of the HTTP response.

To create a database:

Command:

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

Output:

The body of the HTTP response.

To get a database:

Command:

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

Output:

The body of the HTTP response.

To delete a database:

Command:

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:

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:

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:

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.