How to Use RoleSync

Invite the bot

Click Add to Discord and pick your server. You'll need Manage Server permission to do this. Once it's in, open your server's role list and drag the bot's own role above any role you want it to manage — Discord won't let a bot touch a role positioned above itself.

Set up a role profile

Run /setup-role-sync with three things: a label (any short name you pick, like "members"), the sync_role to manage (picked from Discord's own role dropdown, no IDs needed), and optionally a protected_role that should never be removed by this bot no matter what.

Need more than one role? Just run it again with a different label — e.g. label:members once, then label:vip another time. Each one is tracked completely independently, including its own undo history.

Check what's configured

Run /list-role-syncs any time to see every profile set up in this server and which role each one points to. Handy since labels are easy to forget once you have a few. If a profile has ever been synced, it also shows who last ran it and when.

Prepare your file

A .txt file needs one Discord username per line. A .csv needs the username in the first column — anything else in the row is ignored, so it's fine if your export also has emails, tiers, join dates, whatever.

Matching is case-insensitive, checked in this order: server nickname, then Discord display name, then the @handle. Since handles rarely change, that's still the safest one to collect on your signup form if you have a choice, exports often have small case differences and those are no longer a problem.

kayra123
donk666
someuser

username,email,tier
kayra123,kayra@example.com,paid
donk666,donk@example.com,paid

Run the sync

Run /sync-roles with the label of the profile you're updating and the file attached. Nothing changes yet — you'll get a preview showing exactly how many people will have the role added, how many will have it removed, and any names that couldn't be matched to a member. A text file is attached with the complete lists, so nothing gets cut off at the first 20 names.

If a name doesn't match exactly, the bot also tries cleaned-up versions (a note or old #1234 tag removed, or each side of "name1 or name2"). Anything matched that way is flagged in the file so you can double check it.

Confirm or cancel

Review the preview, then click Proceed to apply it or Cancel to back out with nothing changed. This message is only visible to you, and only someone with Manage Roles permission can act on it.

Do this within 30 minutes of running the command. A preview left longer than that is discarded automatically instead of applied, since the server's membership may have changed since it was computed, just run /sync-roles again if that happens.

Watch it apply

Once confirmed, the message updates itself with a progress bar as it works through the list, so you always know it's still going rather than wondering if it froze. When it's done you get a report file: who was given the role, who had it removed, who wasn't found, and anything that failed.

Undo if needed

Uploaded the wrong file, or something looks off? Run /undo-sync with that same profile's label to revert exactly what the last sync for that label did. Only one level of undo is kept per profile, and running a new sync for that label overwrites its undo history — other profiles are unaffected either way.

Retire a profile

Discontinued a tier, or want to redo a mistyped label cleanly? Run /remove-role-sync with that label to delete the profile and its undo history for good. It stops showing up in /list-role-syncs, and the label is free to reuse afterwards. This doesn't touch anyone's actual roles, it just removes the bot's record of that profile.

If a role change fails

Individual add/remove failures during /sync-roles or /undo-sync are tagged with one of these codes in the result message, instead of just "something went wrong."