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

# Managing roles

> Assignment, mass operations, temporary roles, linked roles, and restoring roles on rejoin.

Everything here requires **Manage Roles**, and mira's own role has to sit **above** any role you're asking it to assign.

## Assigning

<CodeGroup>
  ```javascript Toggle a role theme={null}
  !role @someone Member
  ```

  ```javascript Several at once theme={null}
  !role @someone Member Verified Level5
  ```

  ```javascript Explicit add or remove theme={null}
  !role add @someone Member
  !role remove @someone Member
  ```
</CodeGroup>

The bare `role` command **toggles** — it adds the role if they don't have it and removes it if they do. `add` and `remove` are explicit when you need certainty.

`role multiple` (aliases `multi`, `m`, `x`) is the same as passing several roles to `role`.

Role names don't need to be exact. `!role @someone mod` matches "Moderator" as long as nothing else is closer.

## Mass assignment

<CodeGroup>
  ```javascript Everyone theme={null}
  !role all @Member
  !role all remove @Member
  ```

  ```javascript Only humans theme={null}
  !role humans @Member
  ```

  ```javascript Only bots theme={null}
  !role bots @Bots
  ```

  ```javascript Everyone with another role theme={null}
  !role has @Verified @Member
  !role has remove @Verified @Member
  ```
</CodeGroup>

These run in the background and report progress. Cancel one mid-run with:

```javascript theme={null}
!role cancel
```

<Warning>
  Mass role operations on a large server take a while — Discord's rate limits, not the bot. A 50,000 member server is minutes, not seconds. Leave it running; `!role cancel` stops it cleanly if you need to.
</Warning>

## Creating and editing

<CodeGroup>
  ```javascript Create theme={null}
  !role create Moderator
  !role create #ff0000 Moderator
  ```

  ```javascript Duplicate an existing one theme={null}
  !role duplicate @Moderator Senior Moderator
  ```

  ```javascript Rename theme={null}
  !role rename @Mod Moderator
  ```

  ```javascript Recolour theme={null}
  !role color @Moderator #5cacec
  ```

  ```javascript Delete theme={null}
  !role delete @OldRole
  ```
</CodeGroup>

| Command                                        | Aliases         | Effect                                         |
| ---------------------------------------------- | --------------- | ---------------------------------------------- |
| `role create [color] [hoist] <name>`           | `make`          | Create a role                                  |
| `role duplicate <role> [color] [hoist] <name>` | `copy`, `clone` | Copy permissions to a new role                 |
| `role rename <role> <name>`                    | `name`          | Rename                                         |
| `role color <role> <colors>`                   | `colour`        | Change colour — supports gradients             |
| `role icon <role> [icon]`                      | `image`, `img`  | Set an image or emoji icon                     |
| `role hoist <role>`                            | —               | Toggle showing separately in the sidebar       |
| `role mentionable <role>`                      | —               | Toggle mentionability (needs Mention Everyone) |
| `role delete <role>`                           | `del`           | Delete                                         |

## Inspecting

<CodeGroup>
  ```javascript Role details theme={null}
  !role info @Moderator
  ```

  ```javascript Its permissions theme={null}
  !role permissions @Moderator
  ```

  ```javascript Who has it theme={null}
  !inrole @Moderator
  ```

  ```javascript Who doesn't theme={null}
  !notinrole @Verified
  ```

  ```javascript Export the member list theme={null}
  !role dump @Moderator
  ```
</CodeGroup>

`roleinfo` and `ri` are shortcuts for `role info`. `role dump` writes every member with the role to a text file — useful for audits or migrating a role between servers.

## Positioning

```javascript theme={null}
!role position @Moderator above @Helper
!role position @Moderator below @Admin
```

Aliases: `pos`, `move`.

## Temporary roles

```javascript theme={null}
!temprole @someone @VIP 7d
!temprole list
!temprole cancel 47
```

The role is removed automatically when the duration elapses. `temprole list` shows every active grant with its ID and expiry; `temprole cancel <id>` ends one early and removes the role immediately.

Aliases: `tempr`, `trole`, `tmprole`, `tmpr`.

## Linked roles

Link two roles so gaining either one grants the other:

<CodeGroup>
  ```javascript Link them theme={null}
  !role link @Booster @VIP
  ```

  ```javascript View links theme={null}
  !role links
  ```

  ```javascript Unlink theme={null}
  !role unlink @Booster @VIP
  ```

  ```javascript Clear all theme={null}
  !role links clear
  ```
</CodeGroup>

Links are **bidirectional by default** — losing one removes the other too. Useful for keeping a cosmetic role in sync with a functional one, or mirroring a role granted by another bot.

## Restoring roles

<CodeGroup>
  ```javascript Restore one person's roles theme={null}
  !role restore @someone
  ```

  ```javascript Do it automatically on rejoin theme={null}
  !role restore reassign on
  ```

  ```javascript Never restore a specific role theme={null}
  !role restore reassign exclude @Moderator
  !role restore reassign exclude list
  ```
</CodeGroup>

mira caches every member's roles. `role restore` re-applies them, which fixes the common "they left and came back and lost everything" problem.

With `reassign on`, it happens automatically the moment they rejoin.

<Warning>
  Exclude your staff roles before turning `reassign` on. Otherwise a moderator you removed and who rejoins gets their permissions back automatically.

  ```javascript theme={null}
  !role restore reassign exclude @Moderator
  !role restore reassign exclude @Admin
  ```

  Muted and jailed members are handled separately — those roles persist across rejoins regardless.
</Warning>

## Syncing permissions

```javascript theme={null}
!role sync @OldRole @NewRole
```

Copies every channel permission overwrite from one role to another. Requires **Manage Channels** and **Manage Roles**. Handy when replacing a role — set the new one up, sync the overwrites, then delete the old one.

## Command reference

| Command                                        | Description                        |
| ---------------------------------------------- | ---------------------------------- |
| `role <member> <roles>`                        | Toggle one or more roles           |
| `role add <member> <role>`                     | Add a role                         |
| `role remove <member> <role>`                  | Remove a role                      |
| `role multiple <member> <roles>`               | Toggle several                     |
| `role all <role>`                              | Give to everyone                   |
| `role all remove <role>`                       | Take from everyone                 |
| `role humans <role>`                           | Give to all humans                 |
| `role bots <role>`                             | Give to all bots                   |
| `role has <role> <assign_role>`                | Give to everyone with another role |
| `role cancel`                                  | Cancel a running mass operation    |
| `role create [color] [hoist] <name>`           | Create a role                      |
| `role duplicate <role> [color] [hoist] <name>` | Clone a role                       |
| `role rename <role> <name>`                    | Rename                             |
| `role color <role> <colors>`                   | Recolour                           |
| `role icon <role> [icon]`                      | Set an icon                        |
| `role hoist <role>`                            | Toggle sidebar display             |
| `role mentionable <role>`                      | Toggle mentionability              |
| `role position <role> <above/below> <role>`    | Reposition                         |
| `role delete <role>`                           | Delete                             |
| `role info [role]`                             | Role details                       |
| `role permissions <role>`                      | List permissions                   |
| `role dump <role>`                             | Export members to a file           |
| `role sync <old_role> <new_role>`              | Copy channel overwrites            |
| `role restore <member>`                        | Restore cached roles               |
| `role restore reassign (on/off)`               | Auto-restore on rejoin             |
| `role restore reassign exclude <role>`         | Never auto-restore this role       |
| `role link <role_a> <role_b>`                  | Link two roles                     |
| `role unlink <role_a> <role_b>`                | Unlink                             |
| `role links`                                   | View linked pairs                  |
| `temprole <member> <role> <when>`              | Timed role grant                   |
| `temprole list`                                | Active temporary roles             |
| `temprole cancel <id>`                         | End one early                      |
| `inrole <role>`                                | Members with a role                |
| `notinrole <role>`                             | Members without it                 |

<Note>
  For roles members assign themselves — reaction roles, button roles, dropdowns, autoroles, booster colours — see [Self-assignable roles](/setup/self-roles) and [Automatic roles](/setup/automatic-roles).
</Note>