> ## Documentation Index
> Fetch the complete documentation index at: https://arize-ax.mintlify.site/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>] [--output <fmt>] [--verbose]
```

| Option            | Description                                                    |
| ----------------- | -------------------------------------------------------------- |
| `--is-predefined` | Return only system-defined predefined roles                    |
| `--is-custom`     | Return only custom roles                                       |
| `--limit`, `-l`   | Maximum number of results to return (default: 15)              |
| `--cursor`, `-c`  | Pagination cursor for the next page                            |
| `--output`, `-o`  | Output format (`table`, `json`, `csv`, `parquet`) or file path |
| `--verbose`, `-v` | Enable verbose logs                                            |

**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> [--output <fmt>] [--verbose]
```

| Argument / Option | Description                                                    |
| ----------------- | -------------------------------------------------------------- |
| `<name-or-id>`    | Role name or ID (required)                                     |
| `--output`, `-o`  | Output format (`table`, `json`, `csv`, `parquet`) or file path |
| `--verbose`, `-v` | Enable verbose logs                                            |

**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>] [--output <fmt>] [--verbose]
```

| Option            | Description                                                                                                             |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `--name`, `-n`    | Role name (must be unique, max 255 characters) (required)                                                               |
| `--permissions`   | Comma-separated list of permissions to grant (e.g. `PROJECT_READ,DATASET_CREATE`). At least one is required. (required) |
| `--description`   | Optional description of the role's purpose (max 1000 characters)                                                        |
| `--output`, `-o`  | Output format (`table`, `json`, `csv`, `parquet`) or file path                                                          |
| `--verbose`, `-v` | Enable verbose logs                                                                                                     |

**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,...>] [--output <fmt>] [--verbose]
```

| Argument / Option | Description                                                                                 |
| ----------------- | ------------------------------------------------------------------------------------------- |
| `<name-or-id>`    | Role name or ID (required)                                                                  |
| `--name`, `-n`    | New role name (max 255 characters)                                                          |
| `--description`   | New description (max 1000 characters)                                                       |
| `--permissions`   | Comma-separated replacement permissions. Fully replaces existing permissions when provided. |
| `--output`, `-o`  | Output format (`table`, `json`, `csv`, `parquet`) or file path                              |
| `--verbose`, `-v` | Enable verbose logs                                                                         |

**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] [--verbose]
```

| Argument / Option | Description                  |
| ----------------- | ---------------------------- |
| `<name-or-id>`    | Role name or ID (required)   |
| `--force`, `-f`   | Skip the confirmation prompt |
| `--verbose`, `-v` | Enable verbose logs          |

**Examples:**

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