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

# tai roles

> Manage access-control roles.

Manage access-control roles.

```console theme={null}
$ tai roles [OPTIONS] COMMAND [ARGS]...
```

## `tai roles create`

Create a role over a base tier with a per-tag grant map.

Example: `tai roles create ops --base-tier editor --grant presets=write --grant hooks=read`

```console theme={null}
$ tai roles create [OPTIONS] NAME
```

| Argument | Description                 |
| -------- | --------------------------- |
| `NAME`   | New role name. *(required)* |

| Option                 | Description                             |
| ---------------------- | --------------------------------------- |
| `--base-tier` `TEXT`   | Base tier: editor or viewer.            |
| `--grant` `TEXT`       | Repeatable tag=level (none/read/write). |
| `--description` `TEXT` | Role description. *(default: \`)*       |
| `--json` / `--no-json` | Emit raw JSON instead of human tables.  |

## `tai roles delete`

Delete a role (rejected while any principal still holds it).

Example: `tai roles delete ops`

```console theme={null}
$ tai roles delete [OPTIONS] NAME
```

| Argument | Description             |
| -------- | ----------------------- |
| `NAME`   | Role name. *(required)* |

| Option                 | Description                            |
| ---------------------- | -------------------------------------- |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai roles edit`

Edit a role's per-tag grant map (and optionally its description). LIVE — every
holder's reach changes on their next request.

Example: `tai roles edit ops --grant hooks=write`

```console theme={null}
$ tai roles edit [OPTIONS] NAME
```

| Argument | Description             |
| -------- | ----------------------- |
| `NAME`   | Role name. *(required)* |

| Option                 | Description                             |
| ---------------------- | --------------------------------------- |
| `--grant` `TEXT`       | Repeatable tag=level (none/read/write). |
| `--description` `TEXT` | New description.                        |
| `--json` / `--no-json` | Emit raw JSON instead of human tables.  |

## `tai roles list`

List every role with its base tier, grant map, and allow\_all flag.

Example: `tai roles list`

```console theme={null}
$ tai roles list [OPTIONS]
```

| Option                 | Description                            |
| ---------------------- | -------------------------------------- |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai roles rollback`

Roll a role back to a prior version (LIVE — holders follow on their next request).

Example: `tai roles rollback ops 2`

```console theme={null}
$ tai roles rollback [OPTIONS] NAME VERSION
```

| Argument  | Description                                  |
| --------- | -------------------------------------------- |
| `NAME`    | Role name. *(required)*                      |
| `VERSION` | Version number to roll back to. *(required)* |

| Option                 | Description                            |
| ---------------------- | -------------------------------------- |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai roles show`

Show one role's full definition (filtered from the roles listing).

Example: `tai roles show editor`

```console theme={null}
$ tai roles show [OPTIONS] NAME
```

| Argument | Description             |
| -------- | ----------------------- |
| `NAME`   | Role name. *(required)* |

| Option                 | Description                            |
| ---------------------- | -------------------------------------- |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai roles versions`

Show a role's version history and its who/when/before→after audit trail.

Example: `tai roles versions ops`

```console theme={null}
$ tai roles versions [OPTIONS] NAME
```

| Argument | Description             |
| -------- | ----------------------- |
| `NAME`   | Role name. *(required)* |

| Option                 | Description                            |
| ---------------------- | -------------------------------------- |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |