📋 CSV,Roles — Documentation
Full command reference, CSV format guide, and setup instructions.
¶ How Does It Work?
1
Prepare your CSV file
Create a .csv file with a header row, then add your member names or IDs. Make sure it is saved as UTF-8 encoded.
Create a .csv file with a header row, then add your member names or IDs. Make sure it is saved as UTF-8 encoded.
2
Run the command in Discord
Use
Use
/assign-role, /remove-role, or another command, select your role, and attach the CSV file.3
Wait for processing
The bot works through your list. Due to Discord rate limits, larger lists take longer. Expect up to 75 seconds per 60 members.
The bot works through your list. Due to Discord rate limits, larger lists take longer. Expect up to 75 seconds per 60 members.
4
Review the results
You'll receive a "Process complete" message with an attached log file detailing any errors or skipped entries.
You'll receive a "Process complete" message with an attached log file detailing any errors or skipped entries.
¶ Before You Start
File Requirements
✓
Must be encoded as UTF-8.
✓
Must include a header row as the first line. The header name doesn't matter, but it is always skipped. Omit it and your first member will be missed.
✓
Maximum 1000 data rows, not including the header.
✓
Member identifiers are read from the first column by default. Use the optional
column-name parameter to specify a different column. You can mix IDs and names in the same file.
Member Identifiers
The bot accepts any of the following to identify a member, falling back in this order:
1.Server nickname
2.Global nickname
3.Username (append
#xxxx for old-style usernames)4.Unique ID (recommended, most reliable)
If no match is found, a FAILURE is logged for that member. If multiple members share an identifier, only the first match is used.
Minimum example CSV:
user
173105961442082816
nickname1
member2#1234
⚠ Using Excel to prepare your CSV? Expand for gotchas and tips.
Discord IDs convert to scientific notation
Discord user IDs are 18-digit numbers. Excel treats them as numeric and rewrites them as something like
1.73106E+17. The bot cannot match a truncated or scientific-notation ID, so those members will all fail.Fix: Before entering or pasting IDs, select the column, right-click, choose Format Cells, and set the type to Text. Do this before pasting data. Reformatting after the fact does not restore the lost digits.
Tip: Use
/export-users to get your member list directly from the bot. The exported file is already correctly formatted and safe to edit and re-upload.Save as "CSV UTF-8", not plain "CSV"
Excel's default CSV (Comma delimited) option uses your system's regional encoding (typically Windows-1252 on Windows). This can corrupt names that include accented characters, non-ASCII letters, or emoji. The bot requires UTF-8.
Fix: When saving, use File > Save As > Browse and in the Save as type dropdown choose CSV UTF-8 (Comma delimited) (.csv). It is the option with "UTF-8" in the label.
Opening an existing CSV in Excel auto-formats it
Double-clicking a .csv file and letting Excel open it applies auto-formatting immediately, before you change anything. ID columns can be converted to scientific notation on load. If you save after that, the damage is permanent.
Better approach: Use Data > Get Data > From Text/CSV instead of opening the file directly. The import wizard lets you set column data types before Excel loads the data, so mark the ID column as Text during import.
Verify your file before uploading
Open your saved .csv in a plain text editor (Notepad, VS Code, Notepad++) to confirm IDs look like full 18-digit numbers and the file starts with your header row. If IDs appear as scientific notation or the first line contains garbled characters, fix the file before uploading.
¶ Action Outcomes
✅ Success
Role assigned to (or removed from) the member.
❌ Failed
Member not found (likely left the server).
⏭ Skipped
Member already has (or doesn't have) the role.
¶ Command Overview
⚠ All role management and kick commands also require View Channel, Send Messages, and Attach Files in the channel where commands are used. Progress and completion messages are sent as regular channel messages, not ephemeral responses.
| Command | Permissions | Required | Optional | Description |
|---|---|---|---|---|
/assign-role |
Manage Roles | role file |
column-name |
Bulk assign a role via CSV upload. |
/remove-role |
Manage Roles | role file |
column-name |
Bulk remove a role via CSV upload. |
/replace-role |
Manage Roles | old-role new-role file |
column-name |
Swap one role for another via CSV upload. |
/kick-members |
Kick Members | file |
column-name reason kick-message |
Kick members via CSV upload. |
/role permissions |
None | role |
none | View a role's permissions. |
/role members |
None | role |
none | View a role's members. |
/export-users |
Manage Roles | none | filter_role include_bots |
Export server members to a CSV file. |
/invite |
None | none | none | Display an invite link for the bot. |
/help |
None | none | command |
View command help and descriptions. |
/links |
None | none | none | View support, documentation, and invite links. |
¶ Command Details
¶ /assign-role
Assigns a selected role to every member in your CSV file.
Required permissions
Manage Roles, View Channel, Send Messages, Attach Files
Manage Roles, View Channel, Send Messages, Attach Files
Parameters
role— The role to assign. Required.file— Your UTF-8 encoded CSV file. Required.column-name— Column header containing member identifiers. Optional, defaults to the first column.
How it works
The bot reads each row, looks up the member, and attempts to assign the role. Each member is logged as Success, Skipped (already has the role), or Failed (not found). When processing is complete, a summary message and log file are sent to the channel.
The bot reads each row, looks up the member, and attempts to assign the role. Each member is logged as Success, Skipped (already has the role), or Failed (not found). When processing is complete, a summary message and log file are sent to the channel.
Examples
/assign-role role: @Members file: members.csv /assign-role role: @Members file: affiliates.csv column-name: discord user
¶ /remove-role
Removes a selected role from every member in your CSV file.
Required permissions
Manage Roles, View Channel, Send Messages, Attach Files
Manage Roles, View Channel, Send Messages, Attach Files
Parameters
role— The role to remove. Required.file— Your UTF-8 encoded CSV file. Required.column-name— Column header containing member identifiers. Optional, defaults to the first column.
How it works
Works identically to
Works identically to
/assign-role but removes the role instead of adding it. Members who don't currently have the role are logged as Skipped rather than Failed.Example
/remove-role role: @Members file: members.csv
¶ /replace-role
Swaps one role for another across every member in your CSV file in a single operation.
⚠ This command guarantees end state: members end up with the New Role and without the Old Role, regardless of their current state. Members who are already correct are skipped.
Required permissions
Manage Roles, View Channel, Send Messages, Attach Files
Manage Roles, View Channel, Send Messages, Attach Files
Parameters
old-role— The role to remove. Required.new-role— The role to assign. Required.file— Your UTF-8 encoded CSV file. Required.column-name— Column header containing member identifiers. Optional, defaults to the first column.
How it works
For each member in the file, the bot checks their current roles and makes whatever changes are needed to ensure they have
For each member in the file, the bot checks their current roles and makes whatever changes are needed to ensure they have
new-role and don't have old-role. It may only add, only remove, do both, or do nothing at all, depending on each member's current state.Example
/replace-role old-role: @Bronze new-role: @Silver file: promotions.csv
¶ /kick-members
Kicks every member in your CSV file, with optional audit log reason and DM message.
Required permissions
Kick Members, View Channel, Send Messages, Attach Files
Kick Members, View Channel, Send Messages, Attach Files
Parameters
file— Your UTF-8 encoded CSV file. Required.column-name— Column header containing member identifiers. Optional, defaults to the first column.reason— Reason shown in the server audit log. Optional, max 100 characters.kick-message— Custom DM sent to the member before removal. Optional, max 500 characters.
How it works
The bot looks up each member in the file and kicks them from the server. Use
The bot looks up each member in the file and kicks them from the server. Use
reason to keep your audit log clean and kick-message to let members know why they were removed.Example
/kick-members file: inactive.csv reason: Removed for inactivity kick-message: You've been removed due to inactivity. Feel free to rejoin anytime.
¶ /role permissions
Displays all permissions granted to a selected role.
Required permissions
None
None
Parameters
role— The role to inspect. Required.
How it works
Useful for quickly auditing what a role can do without digging through Server Settings.
Useful for quickly auditing what a role can do without digging through Server Settings.
Example
/role permissions role: @Moderator
¶ /role members
Displays an alphabetized list of all members currently holding a selected role.
Required permissions
None
None
Parameters
role— The role to inspect. Required.
How it works
The bot looks at the selected role and returns an alphabetized list of every member currently holding it. Handy for a quick headcount or to verify role assignments without digging through Server Settings.
The bot looks at the selected role and returns an alphabetized list of every member currently holding it. Handy for a quick headcount or to verify role assignments without digging through Server Settings.
Example
/role members role: @Members
¶ /export-users
Exports your server's member list as a CSV file.
Required permissions
Manage Roles
Manage Roles
Parameters
filter_role— Export only members who have this role. Optional.include_bots— Whether to include bot accounts. Optional, bots are included by default.
How it works
Useful for building lists to use with the other commands, auditing your membership, or keeping records. The exported file includes ID, Username, Display Name, Roles, User Type, and Join Date (UTC).
Useful for building lists to use with the other commands, auditing your membership, or keeping records. The exported file includes ID, Username, Display Name, Roles, User Type, and Join Date (UTC).
Output example
ID,Username,Display Name,Roles,User Type,Join Date 173105961442082816,dlchamp,DLCHAMP,"[Contributor,Support,Developer]",Human,2022-02-27 17:20:32.198000+00:00
Export Configuration
When you run
When you run
/export-users you'll be presented with a configuration screen.
From here you can include or exclude up to 25 roles each, toggle bots in or out, and switch between Mode: All Members and Mode: No Roles Only. No Roles Only ignores all role filters and exports only members who have no roles at all.
ℹ By default the export includes ALL members, humans and bots.
ℹ A role can only appear in one list (include or exclude), not both.
ℹ If a member has any excluded role they will not be exported, even if they also have an included role.
ℹ When Mode: No Roles Only is active, all role filters are ignored.
ℹ A role can only appear in one list (include or exclude), not both.
ℹ If a member has any excluded role they will not be exported, even if they also have an included role.
ℹ When Mode: No Roles Only is active, all role filters are ignored.
¶ /invite
Displays a Discord invite link for the bot.
Required permissions
None
None
Parameters
None
None
How it works
Useful for sharing the bot with others or quickly grabbing the invite link without leaving Discord.
Useful for sharing the bot with others or quickly grabbing the invite link without leaving Discord.
¶ /help
Displays command list and descriptions. Pass a command name for focused help.
Required permissions
None
None
Parameters
command— A specific command to get detailed help for. Optional.
Examples
/help /help command: assign-role
¶ /links
Displays quick-access links for support, docs, invites, and feature requests.
Required permissions
None
None
Parameters
None
None