# create-role

> Create a new role using the Unkey CLI to group related permissions together. Simplify access management by assigning roles instead of permissions.

Create a new role to group related permissions for easier management. Roles enable consistent permission assignment across multiple API keys.

**Important:** Role names must be unique within the workspace. Once created, roles are immediately available for assignment.

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

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

## Usage

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

## Flags

<ParamField body="--name" type="string" required>
The unique name for this role. Must be unique within your workspace and clearly indicate the role's purpose. Use a descriptive name like `admin`, `content.editor`, or `Billing Manager`. Must be 1-128 characters.
</ParamField>

<ParamField body="--description" type="string">
Provides comprehensive documentation of what this role encompasses and what access it grants. Include information about the intended use case, what permissions should be assigned, and any important considerations. This internal documentation helps team members understand role boundaries and security implications. Not visible to end users. Maximum 512 characters.
</ParamField>

<ParamField body="--permissions" type="string[]">
Comma-separated permission slugs to attach to the role. Missing permissions are created automatically when the root key has permission to create them.
</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 create-role --name=content.editor \
  --description="Can read and write content" \
  --permissions=documents.read,documents.write
```
```bash Without description
unkey api permissions create-role --name=api.reader
```
```bash JSON output for scripting
unkey api permissions create-role --name=admin.billing --description="Full billing access" --output=json
```
```bash Pipe the role ID to another command
ROLE_ID=$(unkey api permissions create-role --name=support.readonly --output=json | jq -r '.data.roleId')
```
</CodeGroup>

## Output

Default output shows the request ID, followed by the created role:

```text
req_2c9a0jf23l4k567

{
  "roleId": "role_5678efgh9012wxyz"
}
```

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

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