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

# Roles

> List the roles available in an organization.

Roles define the permissions that can be granted within an organization. Permissions are not assigned to users directly — a role is attached to a [group](/docs/cli/groups), and every user in that group inherits it.

Roles are predefined, so this command is read-only. Use it to look up the role IDs you need for the `spec.roleIDs` field when creating or updating a group. For how groups and roles fit together, see [Groups and roles](/docs/manage/roles-and-groups).

## Subcommands

* [list](#list) — List roles

***

## list

List the roles available in an organization, with their names and descriptions.

**Aliases:** `list`, `ls`

```bash theme={null}
nscale roles list --org <org-id> [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### Examples

```bash theme={null}
# List all roles in an organization
nscale roles list --org <org-id>

# Extract the ID and name of each role
nscale roles list --org <org-id> -q ".[].metadata.id" -q ".[].metadata.name"
```