Skip to main content
Booster Roles lets each member who is currently boosting the server create and maintain a personal cosmetic role. The module starts disabled; the first create command also enables it. These are guild-only prefix commands; there is no equivalent slash command group.
This module manages roles and announcements; it does not create level rewards or subscription benefits. Each personal role is stored in that server’s custom_roles configuration.

​
Requirements and hierarchy

The runtime requires an active boost (premium_since) to create or edit a personal role. A member manages their own role without a staff permission. Headless needs Manage Roles, and its highest role must be above the anchor, separator, and personal roles. When the separator is enabled, Headless creates or maintains it below the anchor and places personal roles below the separator. If the separator is disabled, personal roles are placed below the anchor. When creating a role, Headless assigns it to the booster and makes it mentionable; separating members with the role in the member list is enabled by default.
  • Headless’s highest role — Purpose: Must be above the roles the bot creates, moves, or assigns.
  • Configured anchor — Purpose: Reference point for the separator or, when no separator is used, personal roles.
  • Separator (optional) — Purpose: Headless creates/updates it and keeps personal roles below it.
  • Personal roles — Purpose: One per recorded owner; the bot creates, updates, and assigns them.
Discord blocks role changes above Headless’s role. Manage Roles without the correct hierarchy is not enough. If the role was created but a later step failed — for example, applying its icon or moving it — check the Booster Roles panel and last error before trying again.

​
Create and customize your role

Use create to create a role or update the one you already have. You can choose its name, color, and icon in one command, then change each property separately. Names can contain multiple words. Colors use hexadecimal notation, and Headless removes incompatible characters from role names.
  • .boosterrole create [name...] [#RRGGBB] [icon] — Result: Creates or updates your personal role. Name, color, and icon are optional.
  • .boosterrole name <name...> — Result: Changes only your role’s name.
  • .boosterrole color <#RRGGBB> — Result: Changes its color.
  • .boosterrole icon <source> — Result: Applies an emoji, custom emoji, compatible HTTPS image URL, sticker, or image attached to the command message.
  • .boosterrole icon clear — Result: Removes the role icon.
  • .boosterrole members [@member or @role] — Result: Lists members of your role; authorized staff can inspect other roles.
.boosterrole and .brole open the panel with the module state, template, position, and last recorded error. Aliases such as .boosterrole crear, .boosterrole nombre, .boosterrole colour, and .boosterrole icono are also accepted.

​
Share the role

When sharing is enabled, .boosterrole share @member sends the invitee a request with Accept and Reject. Only the invited member can accept; the request expires after 10 minutes. Acceptance assigns the role and saves the sharing access. The default limit is 10 people per role, configurable from 0 to 100 in Dashboard. .boosterrole unshare @member directly removes the role from that member and deletes their sharing record; it does not require the invitee to accept another request.
A shared role carries the permissions Discord has granted to it. Review both the role and the member before sending an invitation; turn off Sharing in Dashboard if server policy does not allow owners to share personal roles.

​
Announcements when someone boosts

Dashboard → Roles → Booster Roles can enable a separate announcement, choose its channel, and edit the mention, title, message, media, and up to three HTTPS link buttons. Headless publishes when it detects that Discord registered a new boost; it does not announce a boost being removed. If no announcement channel is configured, the runtime can use the configured display channel.
The built-in announcement and button defaults are in English. Headless migrates only old values that exactly match its previous defaults; server-authored custom text is preserved.
Dashboard’s Test announcement creates a preview without recording a real boost. Announcements are disabled by default, and Headless must be able to send messages in the selected channel.

​
Setup steps

1

Enable the module

In Dashboard, open Roles → Booster Roles and enable the module. The create command also enables it when creating the first role.
2

Set the hierarchy

Choose an anchor and, if needed, a separator. Place Headless’s highest role above the anchor, separator, and future personal roles.
3

Review access and appearance

Set the name/color template, icon, separator visibility, sharing option, and limit. Use cosmetic-only permissions for test roles.
4

Test with a booster

Verify create, name/color/icon edits, and the invitation flow with a member who is currently boosting the server.
5

Configure announcements if needed

Choose a channel, enable announcements, and check the preview. The test does not simulate or record a real boost event.

​
Access controls that need attention

Dashboard currently shows Booster only, Required role, and Automatic creation fields, but the active code does not let them bypass the boost requirement or create roles when a boost arrives: the runtime normalizes booster_only to enabled, validates premium_since, and does not consume required_role_id or auto_create for this decision. Effective eligibility remains: an active boost is required to create or edit.

​
.boosterrole name

​
.boosterrole color

​
.boosterrole icon

Also works: .brole icon clear

​
.boosterrole share

​
.boosterrole unshare

​
.boosterrole members

The current code does not automatically delete their personal role or revoke it from people who already received it. They no longer pass the booster check for creating/editing, but cleanup after a boost ends is not implemented. Manually remove roles that should no longer exist, and first review every member sharing them.
Confirm the module is enabled, the member is still boosting, and Headless has Manage Roles with sufficient hierarchy. Discord errors are saved in last_error and shown in the Booster Roles panel.
No. The visible Required role field is not consumed by the current validation. Creating or editing requires an active boost; do not use this field as a substitute for the actual rule.