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

# Managing roles

> Give and take roles by command, create and edit roles, and check who has what.

`role` is the staff command for everything to do with roles: handing them out, creating and editing them, and applying one to a whole group at once. A set of open commands lets any member check what a role does and who has it.

<Info>
  `role` needs **Manage Roles**, and both you and Bloom must rank above the role you are touching.
</Info>

## Giving and taking roles

<ParamField path="role <user> <role>" type="Manage Roles">
  Toggles a role: the member gets it if they do not have it, and loses it if they do. Alias: `r`.

  * Separate several roles with commas: `!role @Someone Member, Verified`.
  * `!role add @Someone Member` and `!role remove @Someone Member` force one direction.
  * Names do not have to be exact. Type at least three letters and Bloom picks the closest match, telling you what it chose. When two roles are equally close it offers up to three buttons.
</ParamField>

<ParamField path="role restore <user>" type="Manage Roles">
  Gives a returning member back the roles they had. Bloom keeps a snapshot for **24 hours** after someone leaves.
</ParamField>

## Creating and editing roles

| Command                             | What it does                                                                                                                   |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `role create <name> [#hex] [#hex2]` | Makes a role. A second hex code gives it a gradient.                                                                           |
| `role delete <role>`                | Deletes a role.                                                                                                                |
| `role name <old> <new>`             | Renames a role.                                                                                                                |
| `role color <role> <color>`         | Recolors a role. Takes a hex code or a plain description such as `"light blue"`, and two colors joined by `to` for a gradient. |
| `role move <role> <position>`       | Moves a role, where `1` is the top.                                                                                            |
| `role position <role>`              | Shows where a role sits.                                                                                                       |
| `role hoisted <role> <on\|off>`     | Controls whether holders are listed separately in the member list.                                                             |
| `role mentionable <role> <on\|off>` | Controls whether anyone can ping the role.                                                                                     |

<ParamField path="roleicon <emoji|image URL> <role>" type="Manage Roles">
  Sets the small icon shown next to a role. Your server must be at **boost level 2** or higher, which is Discord's requirement for role icons.
</ParamField>

## Acting on many members at once

| Command                       | What it does                                                            |
| ----------------------------- | ----------------------------------------------------------------------- |
| `role humans <role>`          | Gives a role to every member who is not a bot.                          |
| `role bots <role>`            | Gives a role to every bot.                                              |
| `role has <role1> <role2>`    | Gives `role2` to everyone who already has `role1`.                      |
| `role remove everyone <role>` | Takes a role away from everyone who has it, after you confirm.          |
| `role transfer @from @to`     | Moves every role Bloom is allowed to manage from one member to another. |

<Warning>
  These act on the whole server in one go and cannot be reversed in bulk. Check the role name in Bloom's confirmation before agreeing, since name matching is forgiving.
</Warning>

## Checking roles

Open to every member, so people can look before asking staff.

| Command            | Shows                                                                                                                     |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `roles`            | Every role in the server.                                                                                                 |
| `roles dangerous`  | Only roles holding a sensitive permission such as Administrator, Ban Members, or Manage Roles, with the permission named. |
| `roleinfo <role>`  | One role's color, position, member count, and settings. Aliases: `rinfo`, `ri`.                                           |
| `perms <role>`     | The permissions a role grants. `perms denied <role>` shows what it lacks.                                                 |
| `inrole <role>`    | Everyone who has the role. Aliases: `rolemembers`, `ir`.                                                                  |
| `userroles [user]` | Every role one member holds. Aliases: `uroles`, `mroles`.                                                                 |

<Tip>
  Run `!roles dangerous` after any permission change. It is the quickest way to spot a role that grants more than you intended.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="I cannot manage this role as it is higher than or equal to my highest role">
    Bloom is talking about itself. Move Bloom's role above the role you are managing. Discord never lets a bot touch a role at or above its own.
  </Accordion>

  <Accordion title="You cannot modify a role that is higher than or equal to your highest role">
    Your own top role is not above the one you are changing. Someone ranked higher has to make the change.
  </Accordion>

  <Accordion title="Input too short, please type at least 3 letters of the role">
    Give more of the name, or use a mention or the role ID.
  </Accordion>

  <Accordion title="Bloom picked the wrong role">
    Matching is deliberately forgiving, and Bloom always says which role it settled on. Use a mention or the role ID when two names look alike.
  </Accordion>
</AccordionGroup>

## Related pages

<CardGroup cols={2}>
  <Card title="Autoroles" icon="user-plus" href="/configuration/roles/autoroles">
    Give roles automatically when someone joins.
  </Card>

  <Card title="Reaction roles" icon="face-smile" href="/configuration/roles/reaction-roles">
    Let members assign roles to themselves.
  </Card>

  <Card title="Booster and custom roles" icon="paintbrush" href="/configuration/roles/personal-roles">
    Roles members create and style for themselves.
  </Card>

  <Card title="Permissions and hierarchy" icon="user-lock" href="/getting-started/permissions">
    Why role position decides what is possible.
  </Card>

  <Card title="Event logging" icon="scroll" href="/configuration/logging">
    Record every role change in a staff channel.
  </Card>
</CardGroup>