list-roles

List all roles in your Unkey workspace using the CLI, including their assigned permissions. Review your full RBAC configuration at a glance.

Retrieve all roles in your workspace including their assigned permissions. Results are paginated and sorted by their id.

Use this to audit your access control setup, verify role-permission mappings, or build automation that reacts to your current RBAC configuration.

Required permissions:

• rbac.*.read_role

See the API reference for the full HTTP endpoint documentation.

Usage

unkey api permissions list-roles [flags]

Flags

--limit · integer

Maximum number of roles to return in a single response (1-100, default 100). Use smaller values for faster response times and better UI performance. Use larger values when you need to process many roles efficiently. Results exceeding this limit will be paginated with a cursor for continuation.

--cursor · string

Pagination cursor from a previous response to fetch the next page of roles. Include this when you need to retrieve additional roles beyond the first page. Each response containing more results will include a cursor value that can be used here. Leave empty or omit this flag to start from the beginning of the role list.

--search · string

Free-form text to filter roles. Returns roles whose ID, name, 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-roles

Output

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

req_2c9a0jf23l4k567

[
  {
    "id": "role_1234567890abcdef",
    "name": "support.readonly",
    "description": "Provides read-only access for customer support representatives",
    "permissions": [
      {
        "id": "perm_abc123",
        "name": "tickets.read"
      }
    ]
  }
]

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

{
  "meta": {
    "requestId": "req_2c9a0jf23l4k567"
  },
  "data": [
    {
      "id": "role_1234567890abcdef",
      "name": "support.readonly",
      "description": "Provides read-only access for customer support representatives",
      "permissions": [
        {
          "id": "perm_abc123",
          "name": "tickets.read"
        }
      ]
    }
  ],
  "pagination": {
    "cursor": "eyJrZXkiOiJyb2xlXzEyMzQiLCJ0cyI6MTY5OTM3ODgwMH0=",
    "hasMore": true
  }
}