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

# Roles

> Manage roles with the AX CLI

<Note>
  The `ax roles` commands are currently in **BETA**. The API may change without notice. A one-time warning is emitted on first use.
</Note>

The `ax roles` commands let you create, retrieve, update, and delete custom roles on the Arize platform. Predefined (system-managed) roles cannot be updated or deleted.

## `ax roles list`

List roles for the authenticated user's account.

```bash theme={null}
ax roles list [--is-predefined | --is-custom] [--limit <n>] [--cursor <cursor>]
```

| Option            | Description                                       |
| ----------------- | ------------------------------------------------- |
| `--is-predefined` | Return only system-defined predefined roles       |
| `--is-custom`     | Return only custom roles                          |
| `--limit`         | Maximum number of results to return (default: 15) |
| `--cursor`        | Pagination cursor for the next page               |

**Examples:**

```bash theme={null}
ax roles list
ax roles list --is-custom
ax roles list --is-predefined --output roles.json
```

## `ax roles get`

Get a role by name or ID.

```bash theme={null}
ax roles get <name-or-id>
```

**Examples:**

```bash theme={null}
ax roles get role_abc123
ax roles get "Project Viewer"
```

## `ax roles create`

Create a new custom role. At least one permission is required. Role names must be unique within the account.

```bash theme={null}
ax roles create --name <name> --permissions <perm1,perm2,...> [--description <text>]
```

| Option          | Description                                                                                                  |
| --------------- | ------------------------------------------------------------------------------------------------------------ |
| `--name`        | Role name (must be unique, max 255 characters)                                                               |
| `--permissions` | Comma-separated list of permissions to grant (e.g. `PROJECT_READ,DATASET_CREATE`). At least one is required. |
| `--description` | Optional description of the role's purpose (max 1000 characters)                                             |

**Example:**

```bash theme={null}
ax roles create \
  --name "Dataset Reader" \
  --permissions "PROJECT_READ,DATASET_READ" \
  --description "Read-only access to datasets"
```

## `ax roles update`

Update a custom role. At least one of `--name`, `--description`, or `--permissions` must be provided. When `--permissions` is given, it fully replaces the existing permission set. Predefined (system-managed) roles cannot be updated.

```bash theme={null}
ax roles update <name-or-id> [--name <name>] [--description <text>] [--permissions <perm1,perm2,...>]
```

| Option          | Description                                                                                 |
| --------------- | ------------------------------------------------------------------------------------------- |
| `--name`        | New role name (max 255 characters)                                                          |
| `--description` | New description (max 1000 characters)                                                       |
| `--permissions` | Comma-separated replacement permissions. Fully replaces existing permissions when provided. |

**Examples:**

```bash theme={null}
ax roles update role_abc123 --name "Dataset Admin"
ax roles update role_abc123 --permissions "PROJECT_READ,DATASET_READ,DATASET_CREATE"
```

## `ax roles delete`

Delete a custom role. Predefined (system-managed) roles cannot be deleted.

```bash theme={null}
ax roles delete <name-or-id> [--force]
```

| Option    | Description                  |
| --------- | ---------------------------- |
| `--force` | Skip the confirmation prompt |

**Examples:**

```bash theme={null}
ax roles delete role_abc123
ax roles delete role_abc123 --force
```