> ## Documentation Index > Fetch the complete documentation index at: https://planetscale.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # PlanetScale CLI commands: role Postgres and Neki ## Getting Started Make sure to first [set up your PlanetScale developer environment](/docs/cli/planetscale-environment-setup.md). Once you've installed the `pscale` CLI, you can interact with PlanetScale and manage your databases straight from the command line. > **Postgres** > > Create **role credentials** with [`pscale role`](/docs/cli/role), then connect using a [connection string](/docs/postgres/connecting/quickstart.md). > > `pscale connect` is not supported. > **Vitess / MySQL** > > Create a **branch password** with [`pscale password`](/docs/cli/password), then connect with a [connection string](/docs/vitess/connecting/connection-strings.md) or [`pscale connect`](/docs/cli/connect). ## The `role` command Manage database roles for a Postgres or Neki database branch. **Usage:** ```bash theme={null} pscale role [command] ``` ### Available sub-commands | **Sub-Command** | **Product** | **Description** | | :- | :- | :- | | `create` | Postgres, Neki | Create a new role for a database branch | | `default` | Postgres, Neki | Show the default role without rotating its credentials | | `delete` | Postgres, Neki | Delete a role | | `get` | Postgres, Neki | Retrieve information about a specific role | | `list` | Postgres, Neki | List all roles for a database branch | | `reassign` | Postgres, Neki | Reassign objects owned by a role to another role | | `renew` | Postgres, Neki | Renew a role's expiration | | `reset` | Postgres, Neki | Reset a role's password | | `reset-default` | Postgres, Neki | Reset the credentials for the default `postgres` role | | `update` | Postgres, Neki | Update a role's name | ### Service token automation: `role` Legend: ✅ supported · Postgres 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 ` | ✅ | ✅ | ✅ | Postgres | ✅ | `pscale api organizations//databases//branches//roles --format json` | | `get ` | ✅ | ✅ | ✅ | Postgres | ✅ | `pscale api organizations//databases//branches//roles/ --format json` | | `create` / `delete` / `update` / `renew` / `reset` | ✅ | ✅ | ✅ | Postgres | ✅ | `POST pscale api organizations//databases//branches//roles --format json` · `DELETE pscale api organizations//databases//branches//roles/ --format json` · `PATCH pscale api organizations//databases//branches//roles/ --format json` · `POST pscale api organizations//databases//branches//roles//renew --format json` · `POST pscale api organizations//databases//branches//roles//reset --format json` | ```bash theme={null} export PLANETSCALE_ORG="" pscale role list --format json ``` Setup and commands to avoid: [CLI overview](/docs/cli.md) · [Service tokens](/docs/api/service-tokens.md#service-token-automation) ### Available flags | **Flag** | **Description** | | :- | :- | | `-h`, `--help` | View help for `role` command | | `--org string` | 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 ### The `create` sub-command Create a new role for a Postgres or Neki database branch: **Usage:** ```bash theme={null} pscale role create [flags] ``` **Available flags:** * `--inherited-roles string` - Comma-separated list of role names to inherit privileges from. Common values are 'pg\_read\_all\_data' for read access, 'pg\_write\_all\_data' for write access, and 'postgres' for admin access. * `--ttl duration` - TTL defines the time to live for the role. Durations such as "30m", "24h", or bare integers such as "3600" (seconds) are accepted. The default TTL is 0s, which means the role will never expire. * `--with-replication` - Grant the `REPLICATION` privilege for logical replication. Requires `--inherited-roles postgres`. **Example:** ```bash theme={null} pscale role create my-database main api-user --inherited-roles pg_read_all_data --ttl 24h ``` ### The `default` sub-command Show the default role for a Postgres or Neki database branch without rotating its credentials: **Usage:** ```bash theme={null} pscale role default [flags] ``` **Example:** ```bash theme={null} pscale role default my-database main ``` ### The `delete` sub-command Delete a role: **Usage:** ```bash theme={null} pscale role delete [flags] ``` **Available flags:** * `--force` - Delete a role without confirmation * `--successor string` - Role to transfer ownership to before deletion. Usually 'postgres'. **Aliases:** `delete`, `rm` **Example:** ```bash theme={null} pscale role delete my-database main role-123 --successor postgres ``` ### The `get` sub-command Retrieve information about a specific role: **Usage:** ```bash theme={null} pscale role get [flags] ``` **Available flags:** * `--replica` - Return connection details for a branch replica. * `--dedicated-read-replica ` - Return connection details for a dedicated read replica. Postgres only. * `--bouncer ` - Return connection details for a named PgBouncer on Postgres or Neki. These connection-target flags are mutually exclusive. **Example:** ```bash theme={null} pscale role get pscale role get --replica ``` ### The `list` sub-command List all roles for a Postgres or Neki database branch: **Usage:** ```bash theme={null} pscale role list [flags] ``` **Available flags:** * `-w`, `--web` - List roles in your web browser. **Aliases:** `list`, `ls` **Example:** ```bash theme={null} pscale role list my-database main ``` ### The `reassign` sub-command Reassign objects owned by one role to any other role: > [!WARNING] > > Be careful with this command. Reassigning objects like databases, tables, or schemas will change who is able to write to them, alter them, or delete them. **Usage:** ```bash theme={null} pscale role reassign --successor ``` **Available flags:** * `--force` - Force reset without confirmation **Example:** ```bash theme={null} pscale role reassign my-database main role-123 --successor postgres ``` ### The `renew` sub-command Renew a role's expiration: **Usage:** ```bash theme={null} pscale role renew [flags] ``` **Example:** ```bash theme={null} pscale role renew my-database main role-123 ``` ### The `reset` sub-command Reset the credentials for any API-created role: > [!WARNING] > > Be careful with this command. If you are currently using the affected role's credentials for connecting to your database, running this command will reset the password, and new connections using the old password will not work. **Usage:** ```bash theme={null} pscale role reset [flags] ``` **Available flags:** * `--force` - Force reset without confirmation **Example:** ```bash theme={null} pscale role reset my-database main role-123 ``` ### The `reset-default` sub-command Reset the credentials for the default `postgres` role: > [!WARNING] > > Be careful with this command. If you are currently using the default `postgres` role credentials for connecting to your database, running this command will reset the password, and new connections using the old password will not work. **Usage:** ```bash theme={null} pscale role reset-default [flags] ``` **Available flags:** * `--force` - Force reset without confirmation **Example:** ```bash theme={null} pscale role reset-default my-database main ``` ### The `update` sub-command Update a role's name: **Usage:** ```bash theme={null} pscale role update [flags] ``` **Available flags:** * `--name string` - New name for the role **Example:** ```bash theme={null} pscale role update my-database main role-123 --name new-role-name ``` ## Related documentation > **[Managing Postgres roles](/docs/postgres/connecting/roles.md)** > **[Managing Neki roles](/docs/neki/connecting/roles.md)** > **[Postgres roles API documentation](/docs/api/reference/list_roles.md)** ## 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.