Admin

The admin plugin covers "managing members and roles" - everything from !role add to persisting a member's roles across a rejoin.

plugins:
  admin:
    persist:
      roles: true
      nickname: true
      voice: true

Setup checklist

1. Open Setup > Welcome & Roles or add plugins.admin in Config.
2. Move the HepBoat role above every join, persisted, or command-managed role. Add sensitive roles to locked_roles to lock them completely (see Locked roles below); HepBoat must sit above a role to enforce its lock.
3. Choose persistence deliberately. persist.roles: true restores every eligible role; adding persist.role_ids limits restoration to the listed roles and is safer on a large server.
4. Add join roles and a delay if wanted. onjoin_role_delay: 0 is immediate; duration text such as 30s, 10m, or 1h delays the grant.
5. Add welcome destinations and messages. Use channel ID 0 only for a DM-only welcome.
6. Save, check Diagnostics, then join with a test account. Confirm the public welcome, DM, join roles, and any restored state separately.

A fuller starter block looks like this:

plugins:
  admin:
    locked_roles: [411175551308398592]  # never grant through role commands
    onjoin_roles: [669626417461289002]
    onjoin_role_delay: 30s
    persist:
      roles: true
      nickname: true
      voice: false
      role_ids: [669626417461289002]
    welcomes:
      674638168474915242:
        msg: "Welcome {mention} to {server}!"
        dm: false
      0:
        msg: "Please read the rules before posting."
        dm: true

The bot needs View Channel and Send Messages in public welcome channels. It needs permission to manage each join or restored role, and Discord requires those roles to sit below its highest role.

Highlights

• Persistence - put a member's roles, nickname, and voice state back when they rejoin. This is what makes mute roles rejoin-proof.
• Join roles - onjoin_roles grants roles automatically on join, with an optional onjoin_role_delay so lurker bots that leave instantly never get them.
• Role aliases - role_aliases gives friendly names to roles for the role commands.
• Locked roles - a full lock on your most dangerous roles. Nobody can grant, remove, or edit a locked role, and any change that happens anyway is put back automatically. See the section below.
• Welcomes - welcomes posts configurable welcome messages.
• Archives - purge-style commands produce a web archive of the removed messages; archives expire automatically after 7 days. clean and nuke archive what they delete and reply with the link, so a purge is never unreviewable.
• Big-red-button safety - nuke, role spray, role nuke, and role kick-none all show how many messages or members they are about to touch and wait for a button confirmation. A running nuke can be stopped mid-run with nuke cancel, and a running role op with role cancel.
• Nuke cleans out the channel - a bare !nuke deletes everything it can reach, up to 10,000 messages per run; run it again for the next 10,000. Pass a number to delete fewer. Discord only allows bulk deletion of messages younger than 14 days, so older history stays.
• Targeted sprays - role spray <role> [target-role] can hand a role to just the members of another role instead of the whole server.
• Role announcements - give a role an announce_channel plus announce_add_msg / announce_rmv_msg and the bot posts there whenever a member gains or loses it.
• Targeted persistence - persist.role_ids restores only the roles you list instead of everything a member had, which is the usual way to make persistence safe on a big server.

Troubleshooting

• A welcome posts but no role is granted: check Manage Roles and role order.
• Nothing restores after a rejoin: persistence can only restore state the bot observed before the member left. Confirm the plugin was enabled then.
• A delayed role never arrives: check the duration, confirm the member stayed in the server, and look for a deleted or reordered role in Diagnostics.
• A role command refuses a role: it may be listed in locked_roles, above the bot, or above the acting moderator.
• A locked role change keeps getting undone: that is the lock working. Run unlock {role} for a window, or take the role out of locked_roles.
• A locked role is not being protected: HepBoat must be ranked above it. Diagnostics and the mod log both say so when the lock cannot be enforced.

Locked roles

Put a role in locked_roles and it stops moving. While a role is locked:

• nobody can give it to a member or take it away, including administrators and other bots. The change is reverted within a second or two and logged;
• its name, colour, permissions, hoist, and mentionable settings cannot be edited. HepBoat restores the previous values;
• HepBoat itself will not grant it either. Join roles, role persistence, autolevel rewards, streak milestones, the games role shop, custom-command scripts, and the role commands all refuse while the lock is on.

plugins:
  admin:
    locked_roles: [411175551308398592]
    locked_roles_unlock_minutes: 10   # how long `unlock` lasts (1 to 60)

Moderation is the deliberate exception: mutes, mute expiry, infraction reversal, and the antiraid role still work on a locked role, so locking your mute role cannot leave you unable to moderate.

Two limits worth knowing. HepBoat has to be ranked above the role to enforce anything, and a deleted role cannot be brought back, because its id dies with it. Both cases are announced in the mod log rather than failing quietly.

Unlocking temporarily

Rather than editing the config every time, take the lock off for a few minutes:

• unlock {role} [duration] suspends the lock for everyone. The duration defaults to locked_roles_unlock_minutes and cannot exceed 60 minutes.
• relock {role} ends the window immediately.
• role locked lists every locked role, any window still running, and any role HepBoat cannot enforce.

The window relocks itself when it expires, and both the unlock and the relock are recorded in the mod log with who did it.

Commands

Arguments in {curly braces} are required. Arguments in [square brackets] are optional.

Command	What it does
/unlock {role} [duration]	Temporarily suspend the lock on a locked role, so it can be granted or edited.
/relock {role}	End a locked role's unlock window early.
/role locked	List this server's locked roles and any active unlock windows.
/blacklist add {user} [reason]	Blacklist a user from using the bot in this server (full ignore).
/blacklist remove {user}	Remove a user from the bot blacklist.
/blacklist list	List blacklisted users.
/archive here [size]	Archive the most recent N messages in this channel for later replay.
/archive all [size]	Archive every message in this channel up to N entries.
/archive user {user} [size]	Archive a single user's recent messages in this channel.
/archive channel {channel} [size]	Archive recent messages in a different channel.
/clean all [size]	Bulk-delete the most recent N messages in this channel.
/clean bots [size]	Bulk-delete the most recent N bot-author messages in this channel.
/clean user {user} [size]	Bulk-delete a specific user's most recent N messages in this channel.
/nick change {user} {nickname}	Set a user's nickname.
/nick remove {user}	Clear a user's nickname back to their username.
/role none	Show members with zero roles.
/role kick-none	Kick every member with zero roles (admin).
/nuke [size]	Clean out THIS channel - everything, up to 10,000 messages per run (bare form).
/nuke here [size]	Clean out THIS channel - everything, up to 10,000 messages per run.
/nuke channel {channel} [size]	Clean out a different channel (up to 10,000 messages per run).
/nuke cancel [channel]	Cancel an in-flight nuke (admin).
/invites prune [uses]	Delete invites with at most N uses created over an hour ago.
/reactions clean {user} [count] [emoji]	Strip a user's reactions off recent messages in this channel.
/role add {user} {role} [reason]	Grant a role to a user.
/role remove {user} {role} [reason]	Revoke a role from a user.
/role list {role}	List members who currently have a role.
/role spray {role} [target] [reason]	Bulk-add a role to every member in the guild (admin).
/role nuke {role} [reason]	Bulk-remove a role from every member who has it (admin).
/role cancel {role}	Cancel a running role spray/nuke.
/role search [pattern]	List roles whose names match a search pattern.
/role info {role}	Show a role's id, color, position, and member count.
/cease [location]	Lock send-messages for @everyone in this channel (or cease guild to lock the whole guild).
/uncease [location]	Undo a cease.
/shut	Revoke SPEAK + USE_VAD on your current voice channel.
/unshut	Undo a shut.
/mention {role} {message}	Temporarily flip a role mentionable, ping it with a message, flip it back.
/mention here {role} {message}	Ping an unmentionable role in this channel (explicit form of mention).
/mention channel {channel} {role} {message}	Ping an unmentionable role in another channel.
/mention enable {role}	Set a role permanently mentionable.
/mention disable {role}	Set a role permanently unmentionable.
/slowmode [cooldown] [reason]	Set this channel's slowmode cooldown.
/slowmode here [cooldown] [reason]	Set slowmode here (alias for slowmode).
/slowmode channel {channel} [cooldown] [reason]	Set slowmode on a different channel.
/stats {user}	Show a user's message stats.
/v-log {user}	Voice-activity log for a user (joins/leaves/duration).
/v-snap	Live roll call of everyone in your current voice channel.
/webconfig show [role]	Dump (or slice) the guild's web-access config block (admin).