> ## 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: service-token

Available for Vitess, Neki, and Postgres.

## Getting Started

Make sure to first [set up your PlanetScale developer environment](https://planetscale.com/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.

## The `service-token` command

This command allows you to create, list, and manage access for service tokens.

**Usage:**

```bash theme={null}
pscale service-token <SUB-COMMAND> <FLAG>
```

### Available sub-commands

| **Sub-command** | **Sub-command flags** | **Product** | **Description** |
| :- | :- | :- | :- |
| `add-access <TOKEN_ID> <PERMISSION> <PERMISSION>` | `--database <DATABASE_NAME>` | Postgres, Vitess, Neki | Add individual permissions to the specified service token in the organization |
| `create` | `--name <NAME>`, `--ttl <SECONDS>`, `--cidrs <CIDRS>` | Postgres, Vitess, Neki | Create a service token for the organization |
| `delete <TOKEN_ID>` | | Postgres, Vitess, Neki | Delete an entire service token in the organization |
| `delete-access <TOKEN_ID> <PERMISSION> <PERMISSION>` | `--database <DATABASE_NAME>` | Postgres, Vitess, Neki | Delete individual permissions granted to a service token in the organization |
| `duplicate <TOKEN_ID>` | `--name <NAME>`\*, `--ttl <SECONDS>` | Postgres, Vitess, Neki | Duplicate a service token in the organization |
| `list` | | Postgres, Vitess, Neki | List the IDs, names, IP restrictions, and expiration times of an organization's service tokens |
| `show <TOKEN_ID>` | | Postgres, Vitess, Neki | Show a service token in the organization |
| `show-access` | | Postgres, Vitess, Neki | Fetch a service token and its accesses |
| `update <TOKEN_ID>` | `--name <NAME>`, `--ttl <SECONDS>`, `--cidrs <CIDRS>` | Postgres, Vitess, Neki | Change a service token's name, expiry, or IP restrictions without rotating its secret |

### Service token automation: `service-token`

Legend: 🚫 unavailable with a service token (all sub-commands).

All `service-token` sub-commands are **unavailable when authenticated with a service token**. Exact error: `pscale service-token <sub-command> is unavailable when authenticated with a service token`. Do not retry the CLI. Use the alternatives below.

| Sub-command | Env-var auth | `--service-token` flag | Requires `--org` | Postgres / Vitess | `--format json` | API equivalent |
| :- | :-: | :-: | :-: | :- | :-: | :- |
| `list` | 🚫 | 🚫 | ✅ | Both | ✅ | `pscale api organizations/<org>/service-tokens --format json` |
| `show-access <id>` | 🚫 | 🚫 | ✅ | Both | ✅ | `pscale api organizations/<org>/service-tokens/<id> --format json` |
| `create` | 🚫 | 🚫 | ✅ | Both | ✅ | `pscale auth login`, then CLI; or [Service tokens API](https://planetscale.com/docs/api/reference/service-tokens.md) |
| `add-access` / `delete-access` / `delete` / `duplicate` / `update` | 🚫 | 🚫 | ✅ | Both | ✅ | `pscale auth login`, then CLI; or [Service tokens API](https://planetscale.com/docs/api/reference/service-tokens.md) |

Read operations (`list`, `show-access`): use `pscale api` with the same service token. Create and manage operations: run under `pscale auth login`; there is no service-token CLI path for those sub-commands.

Setup and commands to avoid: [CLI overview](https://planetscale.com/docs/cli.md) · [Service tokens](https://planetscale.com/docs/api/service-tokens.md#service-token-automation)

> \* *Flag is required*

#### 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** |
| :- | :- | :- |
| `--database <DATABASE_NAME>` | The database this project is using. | `add-access`, `delete-access` |
| `--name <NAME>` | The name for the service token. Required for `duplicate`. | `create`, `duplicate`, `update` |
| `--ttl <SECONDS>` | Time to live (in seconds) for the service token. The token will be invalid when the TTL has passed. With `update`, pass `never` to remove the expiry. | `create`, `duplicate`, `update` |
| `--cidrs <CIDRS>` | IPv4 addresses and CIDR ranges allowed to use this service token. Repeat the flag or separate values with commas. On `create`, omit it to leave the token unrestricted. On `update`, this replaces the list. An empty value removes all restrictions. | `create`, `update` |

### Available flags

| **Flag** | **Description** |
| :- | :- |
| `-h`, `--help` | View help for `service-token` command |
| `--org <ORGANIZATION_NAME>` | The organization for the current user |

### Global flags

| **Command** | **Description** |
| :- | :- |
| `--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`. |
| `--debug` | Enable debug mode. |
| `-f`, `--format <FORMAT>` | Show output in a specific format. Possible values: `human` (default), `json`, `csv`. |
| `--no-color` | Disable color output. |
| `--service-token <TOKEN>` | The service token for authenticating. |
| `--service-token-id <TOKEN_ID>` | The service token ID for authenticating. |

## Examples

### Adding service token access for a database

**Command:**

```bash theme={null}
pscale service-token add-access <TOKEN_ID> read_branch delete_branch create_branch --database <DATABASE_NAME>
```

This will add the following permissions to the specified access token: `read_branch`, `delete_branch`, `create_branch`. The output will show the updated permissions on all databases.

You can find a list of all permissions in the [PlanetScale API documentation](https://planetscale.com/docs/api/reference/service-tokens.md#access-permissions).

**Output:**

| RESOURCE NAME | RESOURCE TYPE | ACCESSES |
| :- | :- | :- |
| dbname | Database | read\_branch, delete\_branch, create\_branch |
| dbname2 | Database | create\_branch |
| my-org | Organization | create\_databases, delete\_databases |

### Adding service token access for an organization

**Command:**

```bash theme={null}
pscale service-token add-access <TOKEN_ID> read_organization
```

This will grant the service token the `read_organization` access on the organization.

**Output:**

| RESOURCE NAME | RESOURCE TYPE | ACCESSES |
| :- | :- | :- |
| my-org | Organization | read\_organization |

### Show a service token

```bash theme={null}
pscale service-token show <TOKEN_ID>
```

### Create a service token with IP restrictions

```bash theme={null}
pscale service-token create --name ci --cidrs 10.0.0.0/8,192.168.1.1
```

`--cidrs` accepts IPv4 addresses and CIDR ranges, up to 10. A bare address is stored as a `/32`. Omit `--cidrs` to leave the token unrestricted. See [IP restrictions](https://planetscale.com/docs/api/service-tokens.md#ip-restrictions).

### Duplicate a service token

```bash theme={null}
pscale service-token duplicate <TOKEN_ID> --name "My Token Copy"
pscale service-token duplicate <TOKEN_ID> --name "My Token Copy" --ttl 3600
```

This creates a copy of the service token with a new name and prints the new token ID and value, the same as `create`. The copy keeps the original token's permissions and IP restrictions. `--ttl` sets the copy's time to live in seconds. The copy doesn't take the original token's expiration.

### Update a service token's name, expiry, or IP restrictions

```bash theme={null}
pscale service-token update <TOKEN_ID> --name "Renamed Token"
pscale service-token update <TOKEN_ID> --ttl 3600
pscale service-token update <TOKEN_ID> --ttl never
pscale service-token update <TOKEN_ID> --cidrs 203.0.113.0/24
pscale service-token update <TOKEN_ID> --cidrs ""
```

Pass at least one of `--name`, `--ttl`, or `--cidrs`. A flag you leave out keeps its current value. `--ttl` sets a new time to live in seconds, and `--ttl never` removes the expiry. `--cidrs` replaces the allowed addresses, and `--cidrs ""` removes all restrictions. The token's ID, value, and permissions don't change.

## 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.