> ## Documentation Index
> Fetch the complete documentation index at: https://docs.postlybee.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI authentication

> Configure user API Tokens, Workspace defaults, and self-hosted origins.

The CLI uses the same `pbk_` user API Tokens as the Public API and SDK. Create a Token from **Settings → Public API**, restrict it to the required Workspaces, and select only the scopes used by your commands.

## Interactive login

```bash theme={null}
postlybee auth:login
```

The CLI reads the Token through a hidden terminal prompt, validates it by calling `GET /public/v1/workspaces`, and saves it to:

```text theme={null}
~/.postlybee/credentials.json
```

The directory is created with mode `0700` and the credentials file with mode `0600`.

```bash theme={null}
postlybee auth:status
postlybee auth:logout
```

`auth:logout` removes only the local credentials file. Revoke a compromised or unused Token from the PostlyBee dashboard as well.

## Environment variables

Environment variables take priority over saved configuration and are recommended for CI:

```bash theme={null}
export POSTLYBEE_API_TOKEN="pbk_your_token"
export POSTLYBEE_WORKSPACE_ID="your-workspace-id"
export POSTLYBEE_API_URL="https://api.postlybee.com"
```

The global `--token`, `--workspace`, and `--base-url` options override environment variables for one command.

<Warning>
  Avoid putting a Token directly in a shell command because it may be saved in
  shell history or visible in the process list. Prefer `auth:login` or a masked
  environment variable.
</Warning>

## Required scopes

| Command family                                                                    | Scopes               |
| --------------------------------------------------------------------------------- | -------------------- |
| `workspaces:list`, `ping`                                                         | `workspaces:read`    |
| `accounts:list`, `accounts:settings`, `accounts:trigger`                          | `accounts:read`      |
| `accounts:connect`, `accounts:delete`                                             | `accounts:write`     |
| `posts:list`, `posts:missing`                                                     | `posts:read`         |
| `posts:create`, `posts:delete`, `posts:connect`, `posts:status`, `posts:settings` | `posts:write`        |
| `media:*`                                                                         | `media:write`        |
| `analytics:*`                                                                     | `analytics:read`     |
| `notifications:list`                                                              | `notifications:read` |

Scopes restrict a Token but never grant Workspace membership. If the Token owner stops managing a Workspace, CLI access ends immediately.

## Self-hosted installations

```bash theme={null}
postlybee --base-url https://api.example.com workspaces:list
```

Save the custom URL during `auth:login`, or set `POSTLYBEE_API_URL` for every command.