# delete-role

> Remove a role from your Unkey workspace using the CLI. Delete unused roles and automatically unlink them from all associated API keys.

Remove a role from your workspace. This also removes the role from all assigned API keys.

**Important:** This operation cannot be undone and immediately affects all API keys that had this role assigned. All keys with this role will lose the associated permissions, and access to resources protected by this role's permissions will be denied.

**Required permissions:**
- `rbac.*.delete_role`

<Note>
See the [API reference](/api-reference/permissions/delete-role) for the full HTTP endpoint documentation.
</Note>

## Usage

```bash
unkey api permissions delete-role [flags]
```

## Flags

<ParamField body="--role" type="string" required>
The role ID or name to permanently delete. Must be 1-128 characters and either a valid role ID that begins with `role_` or a role name that exists within your workspace.
</ParamField>

## Global Flags

| Flag | Type | Description |
|------|------|-------------|
| `--root-key` | string | Override root key (`$UNKEY_ROOT_KEY`) |
| `--api-url` | string | Override API base URL (default: `https://api.unkey.com`) |
| `--config` | string | Path to config file (default: `~/.unkey/config.toml`) |
| `--output` | string | Output format. Use `json` for raw JSON |
| `--body` | string | Send this JSON string as the request body. You cannot combine it with request-building flags. |

## Examples

<CodeGroup>
```bash Basic
unkey api permissions delete-role --role=role_dns_manager
```
```bash Delete by name
unkey api permissions delete-role --role=admin
```
```bash JSON output for scripting
unkey api permissions delete-role --role=role_dns_manager --output=json
```
</CodeGroup>

## Output

Default output shows the request ID:

```text
req_2c9a0jf23l4k567

{}
```

With `--output=json`, the full response envelope is returned:

```json
{
  "meta": {
    "requestId": "req_2c9a0jf23l4k567"
  },
  "data": {}
}
```