Bulk Role Manager — /roles

The /roles command lets you add or remove a Discord role from a large group of members at once. Instead of manually clicking every member’s profile, you point the bot at either a role (everyone who already has it) or a list of @mentions and it handles all the changes for you — respecting Discord’s limits along the way.

Table of Contents

What is it?

Two common scenarios where this command saves time:

  1. Promote a group: Every member with the “ZvZ Team” role also needs the “Veteran” role. Instead of doing it one by one, run /roles add source-role: @ZvZ Team target-role: @Veteran.
  2. Clean up after an event: Remove a temporary event role from a hand-picked list of people by mentioning them directly in the command.
Safe by default: If a member already has the role you’re adding (or doesn’t have the role you’re removing), the bot silently skips them — no errors, no duplicates.

Who Can Use It

RequirementDetails
Discord permission Manage Roles — only server managers and admins typically have this.
Bot permission The bot also needs Manage Roles and its highest role must be above the role you want to apply or remove in the server’s role list.
Role hierarchy matters: Discord does not allow a bot to manage roles that are equal to or higher than its own top role. If you see a hierarchy error, move the bot’s role higher in Server Settings → Roles.

How to Use

Add a role to everyone with a specific role

/roles add target-role: @Veteran source-role: @ZvZ Team

Every member currently holding @ZvZ Team will receive @Veteran.

Add a role to specific people (manual mentions)

/roles add target-role: @Veteran members: @Alice @Bob @Charlie

Only the three mentioned members receive @Veteran. You can mention as many people as you need.

Remove a role from everyone with a specific role

/roles remove target-role: @EventGuest source-role: @ZvZ Team

Remove a role from specific people

/roles remove target-role: @EventGuest members: @Alice @Bob
You must use one or the other: Either fill in source-role or members — at least one is required. If you provide neither, the bot will return an error.

Options Reference

/roles add

OptionRequiredDescription
target-role ✅ Yes The role that will be added to the selected members.
source-role ❌ No* Apply target-role to every member who currently holds this role. *Required if members is not provided.
members ❌ No* A space-separated list of @mentions. The role will be added only to these people. *Required if source-role is not provided.

/roles remove

OptionRequiredDescription
target-role ✅ Yes The role that will be removed from the selected members.
source-role ❌ No* Remove target-role from every member who currently holds this role. *Required if members is not provided.
members ❌ No* A space-separated list of @mentions. The role will be removed only from these people. *Required if source-role is not provided.

What You’ll See After

Once all members have been processed the bot replies with a summary embed visible only to you:

FieldMeaning
Target Role The role that was applied or removed.
Source Whether the members came from a role or from manual mentions.
✅ Added / ✅ Removed How many members were successfully changed.
⏭️ Skipped Members whose role state was already correct — nothing to do for them.
❌ Failed Members the bot tried to update but could not (usually a permission or hierarchy issue). Up to 5 individual error details are shown below the summary.
Tip: The reply is private — only you can see it. No one else in the server will be notified that the bot changed their roles.

Skip & Error Behavior

Skipping members

The bot checks each member’s current roles before making any change:

Skipped members count is shown in the summary but no error is raised for them.

Rate limiting

Discord limits how many role changes can happen in a short period. The bot automatically waits a short moment between each change so it never gets blocked mid-operation. This means processing a large group of members may take a few seconds — the bot will only reply once every single member has been processed.

Large groups: For a group of 100 members, expect the bot to take roughly 30 seconds before replying. This is normal — just wait for the summary.

Partial failures

If the bot can’t update a specific member (e.g. their account left the server mid-operation or Discord returned an error), that member counts as Failed and the bot continues processing everyone else. The summary will list the first 5 failures with details.

Troubleshooting

ProblemWhat to do
“I do not have the Manage Roles permission” Go to Server Settings → Roles, find the bot’s role and enable Manage Roles.
“I cannot manage that role because it is at or above my highest role” Drag the bot’s role above the role you want to assign in Server Settings → Roles.
“No members found with that role” The source role has no members at the moment. Check that the correct role was selected.
“No valid user mentions found” Make sure you @mentioned real users in the members field — plain names like Alice won’t work, you must use actual mentions.
The command says nothing happened (0 added / 0 removed) All members were already in the correct state. No changes were necessary.
The bot takes a long time to reply Normal for large groups. The bot is working through each member one at a time to stay within Discord’s limits. Wait for the summary embed to appear.