# uip insights roles

> Syntax and options for `uip insights roles`, which reads the Insights roles of the active tenant.

`uip insights roles` reads the Insights roles defined in the active tenant. This is a read-only surface — there is no create, update, or delete verb.

:::important
Reading Insights roles requires the **Insights Management View** permission in the active tenant. A session with no user identity (for example, one signed in with client credentials) cannot read this data at all and gets a 403.
:::

## Synopsis

```text
uip insights roles list [--include-resource] [-l <n>] [-o <n>]
uip insights roles get <role-id> [--include-resource]
```

Both verbs honor the [global options](./global-options.md) and the standard [exit codes](./exit-codes.md). Neither accepts `-t, --tenant` — they use the tenant selected during `uip login`.

## uip insights roles list

List Insights roles visible to the current caller. The list can be entitlement-filtered — a tenant without the full-mode entitlement only sees the readonly role set — and listing can trigger a cached call to Licensing to check that entitlement.

### Options

| Flag | Description |
|---|---|
| `--include-resource` | Include the role resource string, which can carry the organization and tenant GUIDs, in the output. Off by default. |
| `-l, --limit <number>` | Maximum rows to return. Defaults to `50`. |
| `-o, --offset <number>` | Rows to skip before returning results. |

Pagination is client-side: the backend returns the full unpaginated list, and the CLI slices it after fetching.

### Examples

```bash
uip insights roles list

uip insights roles list --include-resource --limit 100
```

### Data shape — default view

```json
{
  "Code": "InsightsRolesList",
  "Data": [
    { "id": "c1d2e3f4-0000-0000-0000-000000000001", "name": "Viewer", "actions": ["Read"] }
  ],
  "Pagination": { "Returned": 1, "Limit": 50, "Offset": 0, "Total": 1, "HasMore": false },
  "Instructions": "Role names can be entitlement-filtered: a role missing from this list can still exist and 'roles get' can still resolve it. Listing roles can trigger a cached entitlement call to Licensing. 'uip insights users list' and 'uip insights groups list' show these roles by name on each principal's row."
}
```

### Data shape — with `--include-resource`

```json
{
  "Code": "InsightsRolesList",
  "Data": [
    {
      "id": "c1d2e3f4-0000-0000-0000-000000000001",
      "name": "Viewer",
      "actions": ["Read"],
      "resource": "orn:orch:tenant:t1:role:Viewer"
    }
  ],
  "Pagination": { "Returned": 1, "Limit": 50, "Offset": 0, "Total": 1, "HasMore": false }
}
```

An empty list is a successful result, not an error — the response omits the standing/withheld notes above when there are no rows, since nothing was withheld from an empty result.

## uip insights roles get

Get one Insights role by its GUID. The list's entitlement filter does not apply here — `get` can resolve a role that `list` filtered out.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<role-id>` | yes | Role GUID. Must be a real GUID — a malformed value fails client-side with `Run 'uip insights roles list' to find a role ID.` before any network call. |

### Options

| Flag | Description |
|---|---|
| `--include-resource` | Include the role resource string in the output. Off by default. |

### Example

```bash
uip insights roles get c1d2e3f4-0000-0000-0000-000000000001
```

### Data shape (--output json)

```json
{
  "Code": "InsightsRoleGet",
  "Data": { "id": "c1d2e3f4-0000-0000-0000-000000000001", "name": "Viewer", "actions": ["Read"] }
}
```

With `--include-resource`, the same shape gains a `resource` field, same as the list view.

`Role <id> was not found in the active Insights tenant, or is not visible there.` on a 404 — if every Insights RBAC command 404s, the tenant likely doesn't have the Insights Portal service provisioned.

## See also

- [Insights overview](./uip-insights.md)
- [users](./uip-insights-users.md), [groups](./uip-insights-groups.md) — the other RBAC read surfaces; both show role names resolved by this command's data.