list-permissions

List all permissions in your Unkey workspace using the CLI. View every permission defined in your RBAC system for auditing and management.

Retrieve all permissions in your workspace.

Results are paginated and sorted by their id. Use the --limit and --cursor flags to traverse large permission sets efficiently.

Required permissions:

• rbac.*.read_permission

See the API reference for the full HTTP endpoint documentation.

Usage

unkey api permissions list-permissions [flags]

Flags

--limit · integer

Maximum number of permissions to return in a single response. Accepts a value between 1 and 100. Defaults to 100 when omitted.

--cursor · string

Pagination cursor from a previous response to fetch the next page of permissions. Include this value when you need to retrieve additional permissions beyond the initial response. Leave empty or omit this flag to start from the beginning of the permission list. Cursors are temporary and may expire — always handle cases where a cursor becomes invalid.

--search · string

Free-form text to filter permissions. Returns permissions whose ID, name, slug, or description contains the search string. Matching is case-insensitive.

Global Flags

Flag	Type	Description
--root-key	string	Override root key ($UNKEY_ROOT_KEY)
--api-url	string	Override API base URL (default: https://api.unkey.com)
--config	string	Path to config file (default: ~/.unkey/config.toml)
--output	string	Output format. Use json for raw JSON
--body	string	Send this JSON string as the request body. You cannot combine it with request-building flags.

Examples

Basic

unkey api permissions list-permissions

Output

Default output shows the request ID, followed by the list of permissions:

req_2c9a0jf23l4k567

[
  {
    "id": "perm_1234567890abcdef",
    "name": "users.read",
    "slug": "users-read",
    "description": "Allows reading user profile information and account details"
  }
]

With --output=json, the full response envelope including pagination metadata is returned:

{
  "meta": {
    "requestId": "req_2c9a0jf23l4k567"
  },
  "data": [
    {
      "id": "perm_1234567890abcdef",
      "name": "users.read",
      "slug": "users-read",
      "description": "Allows reading user profile information and account details"
    }
  ],
  "pagination": {
    "hasMore": true,
    "cursor": "eyJrZXkiOiJwZXJtXzEyMzQiLCJ0cyI6MTY5OTM3ODgwMH0="
  }
}