;
};
## 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.
Create **role credentials** with [`pscale role`](/docs/cli/role), then connect using a [connection string](/docs/postgres/connecting/quickstart).
`pscale connect` is not supported.
Create a **branch password** with [`pscale password`](/docs/cli/password), then connect with a [connection string](/docs/vitess/connecting/connection-strings) or [`pscale connect`](/docs/cli/connect).
## The `password` command
Manage database passwords for a Vitess database branch. This command is only supported for Vitess databases.
To manage a role for Postgres, see the [role command](/docs/cli/role).
**Usage:**
```bash theme={null}
pscale password
```
### Available sub-commands
| **Sub-command** | **Sub-command flags** | **Product** | **Description** |
| :- | :- | :- | :- |
| `create ` | `--ttl`, `--role`, `--replica`, `--read-only-region` | Vitess | Create new credentials to access a branch's data |
| `delete ` | `--force` | Vitess | Delete the specified branch credentials |
| `list ` | `--name`, `--status`, `--page`, `--per-page`, `--web` | Vitess | List all credentials of a database |
| `renew ` | | Vitess | Renew the specified branch credentials |
| `show []` | `--name` | Vitess | Show the metadata of one set of branch credentials |
| `update []` | `--name`, `--new-name`, `--cidrs` | Vitess | Rename credentials or replace their IP restrictions |
### Service token automation: `password`
Legend: ✅ supported · Vitess only. All sub-commands require `--org` or `PLANETSCALE_ORG`.
| Sub-command | Env-var auth | `--service-token` flag | Requires `--org` | Postgres / Vitess | `--format json` | API equivalent |
| :- | :-: | :-: | :-: | :- | :-: | :- |
| `list ` | ✅ | ✅ | ✅ | Vitess | ✅ | `pscale api organizations//databases//branches//passwords --format json` |
| `create` | ✅ | ✅ | ✅ | Vitess | ✅ | `POST pscale api organizations//databases//branches//passwords --format json` |
| `delete` | ✅ | ✅ | ✅ | Vitess | ✅ | `DELETE pscale api organizations//databases//branches//passwords/ --format json` |
```bash theme={null}
export PLANETSCALE_ORG=""
pscale password list --format json
```
Setup and commands to avoid: [CLI overview](/docs/cli) · [Service tokens](/docs/api/service-tokens#service-token-automation)
The value `` represents the ID number of the set of credentials. To find all available credentials and their IDs, run `pscale list `.
#### Sub-command flag descriptions
Some of the sub-commands have additional flags unique to the sub-command. This section covers what each of those does. See the above table for which context.
| **Sub-command flag** | **Description** | **Applicable sub-commands** |
| :- | :- | :- |
| `--ttl` | TTL defines the time to live for the password. Durations such as `30m` or `24h`, or bare seconds like `3600`, are accepted. Default is `0` (never expires). | `create` |
| `--role ` | Add a [role to a password](/docs/vitess/security/password-roles). Defaults to `reader` for `--replica` and `--read-only-region`, otherwise `admin`. | `create` |
| `--replica` | Route reads to the branch's primary-region replicas and all [read-only regions](/docs/vitess/scaling/read-only-regions) (nearest replica). Cannot be combined with `--read-only-region`. | `create` |
| `--read-only-region ` | Scope the password to a Vitess [read-only region](/docs/vitess/scaling/read-only-regions). Accepts a region slug, display name, or id. List regions with `pscale keyspace read-only-regions`. Cannot be combined with `--replica`. | `create` |
| `--force` | Delete a password without confirmation. | `delete` |
| `--name ` | Select the password by name instead of ID (`show`, `update`), or filter the list by a name substring (`list`). | `list`, `show`, `update` |
| `--new-name ` | New name for the password. | `update` |
| `--cidrs ` | Replace the IP addresses and CIDR ranges allowed to use this password. Pass an empty value to remove all restrictions. | `update` |
| `--status ` | Filter passwords by status: `active`, `renewable`, or `expired`. | `list` |
| `--page ` | Page of results to fetch. | `list` |
| `--per-page ` | Number of results per page. Default is `100`. | `list` |
| `--web` | Perform the action in your web browser | `list` |
Available roles for the `--role` flag are:
* `reader`
* `writer`
* `readwriter`
* `admin`
### Available flags
| **Flag** | **Description** |
| :- | :- |
| `-h`, `--help` | View help for `password` command |
| `--org ` | The organization for the current user |
### Global flags
| **Command** | **Description** |
| :- | :- |
| `--api-token ` | The API token to use for authenticating against the PlanetScale API. |
| `--api-url ` | The base URL for the PlanetScale API. Default is `https://api.planetscale.com/`. |
| `--config ` | Config file. Default is `$HOME/.config/planetscale/pscale.yml`. |
| `--debug` | Enable debug mode. |
| `-f`, `--format ` | Show output in a specific format. Possible values: `human` (default), `json`, `csv`. |
| `--no-color` | Disable color output. |
| `--service-token ` | The service token for authenticating. |
| `--service-token-id ` | The service token ID for authenticating. |
## Examples
### Create a read-only region password
Create credentials that always connect to a specific Vitess read-only region:
```bash theme={null}
pscale password create --read-only-region eu-west
```
List configured regions for a keyspace first:
```bash theme={null}
pscale keyspace read-only-regions
```
### The `show` sub-command
Show the metadata of one set of credentials, by ID or by name:
```bash theme={null}
pscale password show
pscale password show --name
```
Only metadata is returned. The password itself is shown once, when it is created or renewed, and cannot be
retrieved afterwards.
### The `update` sub-command
Rename credentials or replace the IP addresses allowed to use them, without rotating the password:
```bash theme={null}
pscale password update --new-name reporting
pscale password update --name reporting --cidrs 10.0.0.0/8,192.168.1.1/32
pscale password update --name reporting --cidrs ""
```
An empty `--cidrs` value clears all IP restrictions. To rotate a password, create a new one and delete the
old one.
### The `list` sub-command with filters
Filter credentials by a name substring and by status:
```bash theme={null}
pscale password list --name prod --status active
```
### The `delete` sub-command
Delete a password from a database branch:
**Command:**
```bash theme={null}
pscale password delete
```
**Output:**
```bash theme={null}
? Please type // to confirm:
Password was successfully deleted from .
```
## 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.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.