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

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

Both verbs honor the global options and the standard exit codes. 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

uip insights roles list

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

Data shape — default view

{
  "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

{
  "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

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

Data shape (--output 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
• users, groups — the other RBAC read surfaces; both show role names resolved by this command's data.