Manage server roles using automation, temporary assignments, join rules, and bulk operations — all with built-in hierarchy and safety checks.

Table of Contents

1. Auto-Roles System
2. Persistent Roles
3. Temporary Roles
4. Bulk Role Operations (Mass Role)
5. Date-Based Role Targeting (Join Range)
6. Troubleshooting
7. Permissions Required
8. Command Reference
9. Need Help?

Auto-Roles System

Automatically assign roles to new members and bots when they join your server.

Configuration

Set up auto-roles:

/autorole set member: @Member @Verified bot: @Bot-Role

/autorole set member: @Member @Active @Verified

/autorole set bot: @Bot-Role @Music-Bot

Manage configuration:

/autorole view

/autorole remove member: @Member bot: @Bot-Role

How It Works

Instant Assignment:

• Roles assigned immediately when members join
• Separate configurations for members and bots
• Up to 5 roles per category

Auto-Sync Feature:

• Syncs every 5 minutes automatically
• Ensures all existing members have configured roles
• Catches members who joined while bot was offline

Smart Validation:

• Checks role hierarchy before saving
• Prevents managed/integration roles
• Validates bot permissions

Persistent Roles

Roles that automatically restore when members rejoin after leaving.

Usage

Enable persistence for a user:

/persistrole toggle action: Enable Persistence users: @User role: @VIP reason: Purchased VIP

/persistrole toggle action: Enable Persistence users: @User1 @User2 @User3 role: @Supporter

Disable persistence:

/persistrole toggle action: Disable Persistence users: @User role: @VIP

View persistent roles:

/persistrole view user: @User

/persistrole view

How It Works

Automatic Restoration:

1. User leaves the server
2. Persistent role data stays in database
3. User rejoins the server
4. Role automatically restored within seconds

Use Cases:

• Donator/VIP roles - Reward supporters permanently
• Punishment roles - Muted users can't escape by leaving
• Special access - Beta testers, verified members
• Staff positions - Preserve roles for returning staff

Limitations:

• 1 persistent role per user maximum
• Cannot make managed/bot roles persistent
• Role must exist when user rejoins
• Requires proper role hierarchy

Temporary Roles

Assign roles that automatically expire after a specified duration.

Commands

Add temporary role:

/temprole add user: @User role: @Trial duration: 7d

/temprole add user: @User role: @Event-Access duration: 3h reason: Special event access

Remove temporary role early:

/temprole remove user: @User role: @Trial

List active temporary roles:

/temprole list

/temprole list user: @User

Duration Formats

Supports flexible time formats:

Valid durations: Minimum 1m, Maximum 1 year

Notes:

• Supports multiple units in a single string (1h30m, 2d12h).
• Case-insensitive and whitespace-tolerant (1H 30M works).
• Custom units can be added (e.g., y = 365 days).
• Duplicate units are summed up (e.g., 2m2m will be 4m).

How It Works

Automatic Expiration:

• Role assigned immediately
• Saved to database with expiration time
• Task scheduled for automatic removal
• Role removed precisely when time expires

Persistent Across Restarts:

• Temp roles survive bot restarts
• Tasks rescheduled automatically on startup
• No roles lost due to downtime

Smart Cleanup:

• Role removed when user leaves server
• Database cleaned if role is deleted
• No orphaned entries

Use Cases:

• Trial periods - Give temporary access
• Event roles - Limited-time event access
• Timed mutes - Alternative to timeout feature
• Beta access - Time-limited testing roles
• Temporary permissions - Short-term moderator

Bulk Role Operations (Mass Role)

Assign or remove roles from multiple members simultaneously with safety checks and progress tracking.

Commands

Assign roles:

/massrole assign role: @Role target: Members

/massrole assign role: @Bot-Role target: Bots

/massrole assign role: @Role target: All

Remove roles:

/massrole unassign role: @Role target: Members

/massrole unassign role: @Bot-Role target: Bots

/massrole unassign role: @Role target: All

Safety Features

Built-in Protections:

1. Dangerous Permission Check
   • Blocks roles with Administrator
   • Blocks roles with Ban/Kick/Manage permissions
   • Prevents accidental privilege escalation
2. Role Hierarchy Validation
   • Cannot assign roles above bot's position
   • Cannot assign roles above your position
   • Respects Discord's role hierarchy
3. Confirmation Required
   • Shows number of affected members
   • Requires explicit confirmation
   • 60-second timeout if no response
4. Real-time Progress
   • Live progress bar during operation
   • Success/failure tracking
   • Automatic rate limit protection

Date-Based Role Targeting (Join Range)

Assign roles to members who joined within a specific date range - perfect for campaigns, events, or targeting specific member cohorts.

Usage

Basic command:

/joinrange role: @Role start: 2024-01-01 end: 2024-12-31

Include bots:

/joinrange role: @Role start: 2024-06-01 end: 2024-12-31 bots: true

Date Format

Required format: YYYY-MM-DD

Valid examples:

• 2024-01-15 - January 15, 2024
• 2024-12-31 - December 31, 2024
• 2023-06-01 - June 1, 2023

Invalid examples:

• ❌ 01/15/2024 - Wrong format
• ❌ 2024-1-15 - Missing leading zero
• ❌ 15-01-2024 - Wrong order

Troubleshooting

Auto-Roles Not Assigning

Check these:

1. Role hierarchy - Run /troubleshoot to verify
2. Managed roles - Cannot assign integration/bot roles
3. Role deleted - Reconfigure if role was removed
4. Bot offline - Roles assign on join and during 5-min sync
5. Permissions - Bot needs "Manage Roles" permission

Fix:

# Verify configuration
/autorole view

# Remove and reconfigure if needed
/autorole remove member: @BadRole
/autorole set member: @CorrectRole

Persistent Roles Not Restoring

Common causes:

• Role deleted - Role must exist to restore
• Role hierarchy - Role must be below bot's position
• Not configured - User must have persistence enabled
• Managed role - Cannot make bot/integration roles persistent

Check configuration:

/persistrole view user: @User

Temporary Role Won't Assign

Validation errors:

• Duration too long - Maximum 1 year
• Invalid format - Use 1d, 30m, 2h format
• Role hierarchy - Role above bot or your position
• Managed role - Cannot make managed roles temporary
• Already has temp role - Remove existing first

Bulk Operation Failed

If operation fails:

1. Check progress summary - See success vs. failure counts
2. Role hierarchy issue - Most common cause
3. Permission denied - Bot lost permissions mid-operation
4. Rate limited - Bot will retry automatically
5. Role deleted - Role may have been deleted during operation

Join Range No Matches

Why no eligible members:

• Date range too narrow - Expand your date range
• Everyone has role - Members already assigned
• Wrong date format - Must be YYYY-MM-DD
• Bots excluded - Set bots: true to include
• No one joined then - Verify dates are correct

Permissions Required

For Bot (Lumière)

Essential:

• ✅ Manage Roles (all role operations)
• ✅ View Members (see member list)
• ✅ Read Message History (process commands)

Role Hierarchy:

• Lumière's role must be above all managed roles
• Cannot manage roles above its position
• Position determines what can be managed

For Users

Command permissions:

• /autorole - Manage Roles Permission
• /massrole - Manage Roles Permission
• /joinrange - Manage Roles Permission
• /persistrole - Manage Roles Permission
• /temprole - Manage Roles Permission

Hierarchy rules:

• Cannot assign roles above your position
• Cannot assign roles above bot's position
• Server owner bypasses user hierarchy check

Command Reference

Auto-Roles

Persistent Roles

Temporary Roles

Bulk Operations

Date Targeting