> ## 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](https://docs.nscale.com/docs/cli/groups.md), 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](https://docs.nscale.com/docs/manage/roles-and-groups.md).

## 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>`--org string`</td><td>Organization ID or name</td></tr>

    <tr>
      <td>
        `--json`
      </td>

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

    <tr>
      <td>
        `-q, --query stringArray`
      </td>

      <td>jq filter for value extraction (see [Query output with `-q`](https://docs.nscale.com/docs/cli/query-output))</td>
    </tr>

    <tr>
      <td>
        `--limit int`
      </td>

      <td>Show at most N results (client-side; every result is still fetched). Cuts before `-q`. `0` for all</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"
```
