# uip or roles

> Syntax and options for `uip or roles`, which manages Orchestrator RBAC roles, permissions, and folder-level assignments.

`uip or roles` manages Orchestrator roles and permissions (RBAC). Roles bundle permissions and are assigned to users, groups, robots, machines, or external applications at either the tenant (globally) or folder (scoped) level. Verbs on this page cover roles and their permissions, role-user membership, principal-level role/permission inspection, and folder-level assignments. For tenant-level role assignment per user, see `users assign-roles` in [`uip or users`](./uip-or-users.md).

## Synopsis

```
uip or roles permissions list [options]
uip or roles list [options]
uip or roles get <role-key>
uip or roles create --name <name> --type <Tenant|Folder>
uip or roles update <role-key> [--add-permissions <names>] [--remove-permissions <names>]
uip or roles delete <role-key> -y
uip or roles users list <role-key> [options]
uip or roles users set <role-key> [--add-user-keys <keys>] [--remove-user-keys <keys>]
uip or roles user-roles list <principal-name> [--type <type>] [options]
uip or roles user-permissions list <username> [--folder-path <path> | --folder-key <key>]
uip or roles assign --user-key <key> --role-keys <keys> [--folder-path <path> | --folder-key <key>]
```

## Verbs

| Verb | Purpose |
|---|---|
| `permissions list` | List grantable permission names. |
| `list` | List roles in the tenant. |
| `get` | Fetch one role with its granted permissions. |
| `create` | Create a role (with no permissions) at `Tenant` or `Folder` scope. |
| `update` (alias `edit`) | Add or remove permissions on a role. |
| `delete` | Delete a user-created role. |
| `users list` | List users assigned to a role. |
| `users set` | Add or remove users on a role (bulk). |
| `user-roles list` | List a principal's (user, group, robot, machine, or external app) complete role assignments across tenant and every folder. |
| `user-permissions list` | List a user's effective permissions, tenant-wide or scoped to one folder. |
| `assign` | Assign folder-level roles to a user in a specific folder. |

## uip or roles permissions list

List every grantable permission name. Use these names with `roles update --add-permissions`.

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-l` | `--limit` | number | `50` | Page size. |
| — | `--offset` | number | `0` | Skip count. |
| — | `--sort-by` | field | `Name asc` | OData sort. |

### Examples

```bash
uip or roles permissions list --limit 200
uip or roles permissions list --output-filter 'Data[].Name'
uip or roles permissions list --output table
```

### Data shape (--output json)

```json
{
  "Code": "PermissionList",
  "Data": [{ "Name": "Assets.Create" }, { "Name": "Assets.Delete" }]
}
```

## uip or roles list

List roles. Returns key (GUID), ID, name, display name, type, and whether the role is editable. Use the role key with `roles get`, `roles update`, or `roles users set`.

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-l` | `--limit` | number | `50` | Page size. |
| — | `--offset` | number | `0` | Skip count. |
| — | `--sort-by` | field | `Id desc` | OData sort. |

### Examples

```bash
uip or roles list --limit 50
uip or roles list --output-filter "Data[?Type=='Tenant'].Name"
uip or roles list --output table
```

### Data shape (--output json)

```json
{
  "Code": "RoleList",
  "Data": [
    {
      "Key": "a1b2c3d4-0000-0000-0000-000000000001",
      "ID": 1,
      "Name": "Administrator",
      "DisplayName": "Administrator",
      "Type": "Tenant",
      "IsEditable": false
    }
  ]
}
```

## uip or roles get

Fetch a role with its granted permissions.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<role-key>` | yes | Role key (GUID). Use `roles list` to find it. |

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|

### Examples

```bash
uip or roles get a1b2c3d4-0000-0000-0000-000000000001
uip or roles get a1b2c3d4-0000-0000-0000-000000000001 \
    --output-filter 'Data.Permissions'
uip or roles get a1b2c3d4-0000-0000-0000-000000000001 --output table
```

### Data shape (--output json)

```json
{
  "Code": "Role",
  "Data": {
    "Key": "a1b2c3d4-0000-0000-0000-000000000001",
    "ID": 1,
    "Name": "Administrator",
    "DisplayName": "Administrator",
    "Type": "Tenant",
    "IsStatic": true,
    "IsEditable": false,
    "Permissions": "Assets.View, Assets.Create, Jobs.View"
  }
}
```

## uip or roles create

Create a role with no permissions. After creation, grant permissions with `roles update --add-permissions`.

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| — | `--name` | text | **required** | Role name. |
| — | `--type` | `Tenant` \| `Folder` | **required** | `Tenant` applies across the tenant; `Folder` applies within folders. |

### Examples

```bash
uip or roles create --name "Read Only" --type Tenant
uip or roles create --name "Folder Viewer" --type Folder
uip or roles create --name "Read Only" --type Tenant \
    --output-filter 'Data.Key'
```

### Data shape (--output json)

```json
{
  "Code": "RoleCreated",
  "Data": {
    "Key": "a1b2c3d4-0000-0000-0000-000000000010",
    "ID": 10,
    "Name": "Read Only",
    "Type": "Tenant",
    "Status": "Created successfully"
  }
}
```

## uip or roles update

Add or remove permissions on a role. Reads current permissions, toggles `isGranted` for names in `--add-permissions` / `--remove-permissions`, and saves. New names (not yet on the role) are looked up in the tenant's full permission catalog and added.

`edit` is a registered alias for this verb — `uip or roles edit` works identically to `uip or roles update`.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<role-key>` | yes | Role key (GUID). |

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| — | `--add-permissions` | CSV of names | — | Permissions to grant. |
| — | `--remove-permissions` | CSV of names | — | Permissions to revoke. |

At least one of `--add-permissions` or `--remove-permissions` is required.

### Examples

```bash
uip or roles update a1b2c3d4-0000-0000-0000-000000000010 \
    --add-permissions Assets.View,Jobs.View

uip or roles update a1b2c3d4-0000-0000-0000-000000000010 \
    --remove-permissions Jobs.Edit

uip or roles update a1b2c3d4-0000-0000-0000-000000000010 \
    --add-permissions Assets.View --output-filter 'Data.Status'
```

### Data shape (--output json)

```json
{
  "Code": "RoleUpdated",
  "Data": { "Key": "a1b2c3d4-0000-0000-0000-000000000010", "Status": "Updated successfully" }
}
```

## uip or roles delete

Delete a user-created role. Built-in roles (where `IsStatic=true`) cannot be removed.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<role-key>` | yes | Role key (GUID). |

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-y` | `--yes` | flag | — | **Required.** Confirms this irreversible operation — the CLI never prompts. |

### Examples

```bash
uip or roles delete a1b2c3d4-0000-0000-0000-000000000010 --yes
uip or roles delete a1b2c3d4-0000-0000-0000-000000000010 --yes \
    --output-filter 'Data.Status'
```

### Data shape (--output json)

```json
{
  "Code": "RoleDeleted",
  "Data": { "Key": "a1b2c3d4-0000-0000-0000-000000000010", "Status": "Deleted successfully" }
}
```

## uip or roles users list

List users assigned to a role.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<role-key>` | yes | Role key (GUID). |

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-l` | `--limit` | number | `50` | Page size. |
| — | `--offset` | number | `0` | Skip count. |

### Examples

```bash
uip or roles users list a1b2c3d4-0000-0000-0000-000000000001
uip or roles users list a1b2c3d4-0000-0000-0000-000000000001 --limit 200
uip or roles users list a1b2c3d4-0000-0000-0000-000000000001 \
    --output-filter 'Data[].UserName'
```

### Data shape (--output json)

```json
{
  "Code": "RoleUserList",
  "Data": [
    {
      "Key": "d4e5f6a7-0000-0000-0000-000000000001",
      "ID": 101,
      "UserName": "admin@example.com",
      "FullName": "Admin User",
      "Type": "User"
    }
  ]
}
```

## uip or roles users set

Add or remove users on a role (bulk). Provide `--add-user-keys`, `--remove-user-keys`, or both. At least one is required. Additive/subtractive only — existing membership not named in either flag is left untouched (unlike `users assign-roles`, which replaces the full list).

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<role-key>` | yes | Role key (GUID). |

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| — | `--add-user-keys` | CSV of GUIDs | — | Users to add. |
| — | `--remove-user-keys` | CSV of GUIDs | — | Users to remove. |

### Examples

```bash
uip or roles users set a1b2c3d4-0000-0000-0000-000000000010 \
    --add-user-keys d4e5f6a7-0000-0000-0000-000000000001

uip or roles users set a1b2c3d4-0000-0000-0000-000000000010 \
    --add-user-keys d4e5f6a7-…-001,d4e5f6a7-…-002 \
    --remove-user-keys d4e5f6a7-…-099

uip or roles users set a1b2c3d4-0000-0000-0000-000000000010 \
    --add-user-keys d4e5f6a7-…-001 --output-filter 'Data.Added'
```

### Data shape (--output json)

```json
{
  "Code": "RoleUsersUpdated",
  "Data": {
    "RoleKey": "a1b2c3d4-0000-0000-0000-000000000010",
    "Added": 1,
    "Removed": 0,
    "Status": "Updated successfully"
  }
}
```

## uip or roles user-roles list

List all role assignments for a principal — a user, directory group, directory robot, machine, or external application — across the tenant and every folder. Useful for auditing a principal's full access profile.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<principal-name>` | yes | Username, group name, robot name, machine name, or external-app name to look up. |

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| — | `--type` | `User` \| `Group` \| `Robot` \| `Machine` \| `ExternalApplication` | `User` | Principal type. The `DirectoryUser`/`DirectoryGroup`/`DirectoryRobot`/`DirectoryExternalApplication` spellings are also accepted as aliases. |
| `-l` | `--limit` | number | `50` | Page size. |
| — | `--offset` | number | `0` | Skip count. |

### Examples

```bash
uip or roles user-roles list admin@example.com
uip or roles user-roles list "MRS Developers" --type Group
uip or roles user-roles list admin@example.com \
    --output-filter "Data[?Scope=='Folder']"
```

### Data shape (--output json)

```json
{
  "Code": "UserRoleList",
  "Data": [
    { "Scope": "Tenant", "FolderPath": "", "Role": "Administrator" },
    { "Scope": "Folder", "FolderPath": "Shared", "Role": "Folder Administrator" }
  ]
}
```

## uip or roles user-permissions list

List a user's effective permissions. Without a folder option, shows tenant-level roles and permissions; with `--folder-path`/`--folder-key`, shows the roles and permissions granted in that specific folder instead. Returns the deduplicated union of permissions granted by all matching roles.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<username>` | yes | Username to look up. |

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| — | `--folder-path` | path | — | Show folder-level permissions for this folder instead of tenant-level. |
| — | `--folder-key` | GUID | — | Folder alternative to `--folder-path`. |

### Examples

```bash
uip or roles user-permissions list admin@example.com

uip or roles user-permissions list admin@example.com --folder-path "Shared"
```

### Data shape (--output json)

Tenant-level:

```json
{
  "Code": "UserPermissionList",
  "Data": {
    "Roles": ["Administrator"],
    "Permissions": ["Jobs.View", "Assets.Create"]
  }
}
```

Folder-scoped:

```json
{
  "Code": "UserPermissionList",
  "Data": {
    "FolderPath": "Shared",
    "Roles": ["Folder User"],
    "Permissions": ["Jobs.View", "Assets.View"]
  }
}
```

## uip or roles assign

Assign folder-level roles to a user. Use Folder-type roles only. Requires `--folder-path` or `--folder-key`.

:::note
**CAUTION — destructive on roles.** The server replaces the user's **entire** folder-level role list for the target folder with the keys passed via `--role-keys`. Roles not in the payload are silently removed. To preserve existing folder roles, read them first with `roles user-roles list <principal-name> --type <type>` and pass the full desired union to `--role-keys`. For additive tenant-level role membership on a role, use `roles users set` instead.
:::

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| — | `--user-key` | GUID | **required** | User key. |
| — | `--role-keys` | CSV of GUIDs | **required** | Role GUIDs to assign in the folder. |
| — | `--folder-path` | path | — | Target folder. Provide this or `--folder-key`. |
| — | `--folder-key` | GUID | — | Target folder. |

### Examples

```bash
uip or roles assign --user-key d4e5f6a7-0000-0000-0000-000000000001 \
    --role-keys a1b2c3d4-0000-0000-0000-000000000002 \
    --folder-path "Shared"

uip or roles assign --user-key d4e5f6a7-0000-0000-0000-000000000001 \
    --role-keys a1b2c3d4-…-002,a1b2c3d4-…-003 \
    --folder-key b1c2d3e4-0000-0000-0000-000000000001

uip or roles assign --user-key d4e5f6a7-0000-0000-0000-000000000001 \
    --role-keys a1b2c3d4-0000-0000-0000-000000000002 \
    --folder-path "Shared" --output-filter 'Data.Status'
```

### Data shape (--output json)

```json
{
  "Code": "PermissionsAssigned",
  "Data": {
    "UserKey": "d4e5f6a7-0000-0000-0000-000000000001",
    "FolderPath": "Shared",
    "Status": "Assigned successfully"
  }
}
```

## Exit codes

See [Exit codes](./exit-codes.md). No verb-specific overrides.

## Related commands

- [`uip or users`](./uip-or-users.md) — find user keys; `users assign-roles` for tenant-level role assignments.
- [`uip or folders`](./uip-or-folders.md) — locate folder keys for `roles assign`.

## See also

- [Global options](./global-options.md).
- [Authentication](./authentication.md).