Moderation¶

Magikal's moderation tools are designed for quick staff action while keeping a proper audit trail behind the scenes.

Most moderation commands are prefix commands, so the examples below use !. If the server prefix changes, use the server's current prefix instead.

Staff-first design

Use the lightest command that solves the problem. A warning or short timeout is usually better than jumping straight to a ban.

Discord limits still apply

Discord has hard limits that the bot cannot bypass. Bulk deletes cannot reliably remove messages older than roughly 14 days, timeouts cannot be longer than 28 days, and the bot cannot act above its own role position.

🔎 Quick command map¶

Warnings

!warn · !warnings · !clearwarns
Member restrictions

!timeout · !untimeout · !quarantine · !unquarantine
Removal actions

!kick · !ban · !unban · !softban
Channel cleanup

!purge · !purge bots · !purge user · !purge me · !purge since
Channel control

!slowmode · !lock · !unlock

🧭 Recommended staff workflow¶

Warn first when the issue is minor or educational.
Timeout when someone needs to stop talking for a while.
Quarantine when someone needs isolating into the quarantine area.
Purge only the messages that actually need removing.
Kick, softban, or ban for serious or repeated problems.

Always include a reason

Reasons make the mod-log useful later. They also make it easier for another staff member to understand what happened without asking around.

🔐 Permissions and caps¶

Moderation commands check both the bot's internal caps and Discord permissions.

Command area	Internal cap	Discord permission usually needed
Warnings	Moderator	Kick Members for issuing/clearing warns
Timeout	Moderator	Moderate Members
Quarantine	Moderator	Manage Roles
Kick	Moderator	Kick Members
Ban / Unban	Admin	Ban Members
Purge	Moderator	Manage Messages
Slowmode / Lock / Unlock	Moderator	Manage Channels
Softban	Moderator	Ban Members

Role hierarchy matters

The bot can only manage members and roles below its highest role. If a command says it cannot act, check both Discord permissions and the bot's role position.

📝 Reasons, DMs, and flags¶

Several commands can DM the affected member with the reason.

Use --nodm at the end of the reason when you do not want the bot to DM the member.

!warn @Member Repeated spam after being asked to stop --nodm
!quarantine @Member 1h Investigation while staff review --nodm
!kick @Member Ignored staff instructions --nodm
!ban @Member 1 Severe harassment --nodm

DMs are best-effort

Users can block DMs or disable server DMs. A moderation action can still succeed even if the DM does not.

⏱️ Duration examples¶

Use short, clear durations.

Example	Meaning
`30s`	30 seconds
`15m`	15 minutes
`2h`	2 hours
`3d`	3 days
`1d2h30m`	1 day, 2 hours, 30 minutes

Use safe duration formats

!quarantine uses simple durations such as 30s, 15m, 2h, and 3d. For now, avoid 1w for quarantine because the live command parser does not handle weeks there.

🚨 Auto moderation from warns¶

Warnings are not just a counter. The live moderation cog can trigger automatic action once warning thresholds are reached.

Current behaviour:

Enough warns can trigger an automatic timeout, kick, or ban depending on the configured thresholds.
At 3 warnings, the bot currently attempts a 1 hour quarantine before lower mute-style thresholds are checked.
Automatic timeout expiry is detected and logged as an untimeout event.

Check thresholds before changing policy

Warning thresholds come from bot configuration. If the server policy changes, review the live config before telling staff a new threshold is active.

🧾 Logging and privacy¶

Moderation actions are recorded for accountability.

The moderation cog uses privacy-first internal records for user-related data. Warning records use pseudonymous IDs internally rather than storing raw Discord IDs in the warning count system.

Most direct enforcement actions are routed to the moderation action logs. Some channel-management actions still use the main/default mod-log route.

What staff should know

The visible Discord mod-log is the place staff should use for day-to-day review. The internal storage is there so the bot can keep a durable audit trail and warning state.

Command reference¶

Warn¶

Warn a member and increase their active warning count.

Usage

!warn @member <reason>

Examples

!warn @Member Spamming in general
!warn @Member Ignoring staff instructions --nodm

What it does

Requires a reason.
Adds one warning to the member's current warning count.
Sends a short confirmation to the moderator.
Attempts to DM the member unless --nodm is used.
Logs the action.
May trigger auto moderation if thresholds are reached.

Alias

There is no separate short alias for !warn in the live moderation cog.

Warnings¶

View a member's current active warning count.

Usage

!warnings
!warnings @member

Alias

!warns @member

What it shows

The current warning count.
It does not show the full warning history or old warning reasons.

Low-risk command

In the current live file, !warnings is not gated with the same moderator cap decorator as enforcement commands. Treat it as a visibility command unless policy changes.

Clearwarns¶

Clear a member's active warning count.

Usage

!clearwarns @member [reason]

Example

!clearwarns @Member Appeal accepted

What it does

Asks for confirmation before clearing.
Clears the active warning count.
Removes the related warning identity mapping where available.
Logs the clear action with the old warning count.

This does not erase accountability

Clearing active warns removes the current count. The clear action itself is still logged.

Timeout¶

Temporarily stop a member from sending messages or speaking.

Usage

!timeout @member <duration> [reason]

Aliases

!tm @member <duration> [reason]
!mute @member <duration> [reason]

Examples

!timeout @Member 15m Cool down period
!timeout @Member 1h30m Continued argument after warning

What it does

Checks role hierarchy.
Validates the duration and reason.
Applies a Discord timeout.
Tracks the timeout in memory while the bot is running.
Logs the action.
Attempts to DM the member.

Discord timeout limit

Discord timeouts cannot exceed 28 days.

Untimeout¶

Remove an active timeout early.

Usage

!untimeout @member [reason]

Alias

!unmute @member [reason]

Example

!untimeout @Member Issue resolved with staff

What it does

Removes the Discord timeout.
Removes the member from the bot's active timeout tracker.
Logs the action.
Sends a short confirmation.

Quarantine¶

Move a member into the configured quarantine flow.

Usage

!quarantine @member [duration] <reason>

Aliases

!qt @member [duration] <reason>
!iso @member [duration] <reason>

Examples

!quarantine @Member 30m Spam links
!quarantine @Member 2h Staff review needed --nodm
!qt @Member 1h Cooling off

What it does

Requires a quarantine channel and quarantine role to be configured.
Removes manageable roles from the member.
Adds the quarantine role.
Records removed roles for restoration where possible.
Logs the action.
Attempts to DM the member unless --nodm is used.
Schedules a best-effort automatic release after the duration.

Setup required

Quarantine must be configured first. The live command help points staff to !config quarantine set #channel.

Restart limitation

Some quarantine restore state is kept in memory. If the bot restarts during a quarantine, staff may need to manually review and restore roles.

Unquarantine¶

Remove a member from quarantine early.

Usage

!unquarantine @member [reason]

Aliases

!uq @member [reason]
!rel @member [reason]

Example

!unquarantine @Member Review complete

What it does

Removes the quarantine role if present.
Attempts to restore roles saved during this bot runtime.
Logs the result and restore count.
Sends a short confirmation to staff.

Role restore is best-effort

Roles can only be restored if the bot still has the saved runtime state and can manage those roles.

Kick¶

Remove a member from the server without banning them.

Usage

!kick @member <reason>

Example

!kick @Member Repeated spam after warning
!kick @Member Refused staff instruction --nodm

What it does

Requires a reason.
Checks role hierarchy.
Asks for confirmation.
Attempts to DM the member unless --nodm is used.
Kicks the member.
Logs the action.

Ban¶

Ban a member or user from the server.

Usage

!ban @member [delete_days] <reason>
!ban <user_id> [delete_days] <reason>

Examples

!ban @Member 1 Severe harassment
!ban 123456789012345678 0 Known raid account

What it does

Requires the Admin cap.
Requires a reason.
Accepts delete_days from 0 to 7.
Defaults to deleting 1 day of messages if not specified.
Asks for confirmation.
Attempts to DM the member unless --nodm is used.
Bans the user.
Logs the action.
Clears active warns for that user where possible.

Be careful with user IDs

Banning by ID is useful for users who already left, but double-check the ID before confirming.

Unban¶

Remove a server ban.

Usage

!unban <user_id> [reason]

Example

!unban 123456789012345678 Appeal accepted

What it does

Requires the Admin cap.
Fetches the user if an ID is provided.
Removes the ban.
Logs the action.
Sends a short confirmation.

Softban¶

Ban and immediately unban a member to remove recent messages.

Usage

!softban @member [reason]

Example

!softban @Member Cleaning up raid messages

What it does

Bans the member.
Deletes roughly 1 day of their recent messages.
Immediately unbans them.
Logs the action.
Records a role snapshot for restore-on-join support where available.

Use with care

Softban is mainly a cleanup tool. It removes the member from the server and relies on them rejoining afterwards.

Purge¶

Bulk delete recent non-pinned messages from the current channel.

Usage

!purge <count> [reason]

Alias

!pg <count> [reason]

Examples

!purge 25 Cleanup after spam
!pg 100 Raid cleanup

What it does

Deletes up to 200 recent messages.
Skips pinned messages.
Asks for confirmation when deleting 100 or more messages.
Logs the cleanup.

14 day Discord limit

Discord bulk delete cannot reliably remove messages older than roughly 14 days.

Purge bots¶

Delete recent bot messages from the current channel.

Usage

!purge bots <count> [reason]

Hidden shortcut

!pgb <count> [reason]

Example

!purge bots 50 Cleaning old bot replies

Purge user¶

Delete recent messages from one member in the current channel.

Usage

!purge user @member <count> [reason]

Hidden shortcut

!pgu @member <count> [reason]

Example

!purge user @Member 30 Removing spam burst

Purge me¶

Delete recent messages from the staff member running the command.

Usage

!purge me <count> [reason]

Hidden shortcut

!pgm <count> [reason]

Example

!purge me 10 Cleaning my command clutter

Purge since¶

Delete messages newer than a specific message ID in the current channel.

Usage

!purge since <message_id> <count> [reason]

Hidden shortcut

!pgs <message_id> <count> [reason]

Example

!purge since 123456789012345678 100 Cleaning everything after the raid started

Use this for incident cleanup

Grab the message ID from the first message you want to keep, then purge messages after it.

Slowmode¶

Set channel slowmode.

Usage

!slowmode <duration|off>
!slowmode #channel <duration|off>
!slowmode <duration> for <reset_after>

Alias

!sm <duration|off>

Examples

!slowmode 10
!slowmode off
!slowmode 5m
!slowmode #general 30s
!slowmode 30s for 10m

What it does

Sets slowmode on a text channel.
Supports off to disable slowmode.
Supports temporary slowmode with for <duration>.
Cancels any previous slowmode reset timer for that channel before scheduling a new one.

In-memory timer

Temporary slowmode reset timers are kept in memory. If the bot restarts, staff may need to turn slowmode off manually.

Slowmode range

Slowmode must be between 0 and 21600 seconds, which is 6 hours.

Lock¶

Lock a text channel, voice channel, or thread.

Usage

!lock [#channel] [reason]
!lock [#channel] for <duration> [reason]

Examples

!lock Raid cleanup
!lock #general for 15m Raid wave
!lock for 10m Short cleanup

What it does

Text channel: denies @everyone from sending messages.
Voice channel: denies @everyone from connecting.
Thread: sets the thread to locked.
Supports temporary locks with for <duration>.
Logs the lock action.

In-memory timer

Temporary auto-unlock timers are kept in memory. If the bot restarts, staff may need to unlock the channel manually.

Unlock¶

Unlock a text channel, voice channel, or thread.

Usage

!unlock [#channel] [reason]

Examples

!unlock
!unlock #general Cleanup complete

What it does

Text channel: clears the @everyone send message deny.
Voice channel: clears the @everyone connect deny.
Thread: unlocks the thread.
Logs the unlock action.

🧯 Troubleshooting¶

Problem	Check this first
Bot says it lacks permission	Check Discord permission and role hierarchy.
Quarantine does not work	Check quarantine setup, quarantine role position, and Manage Roles.
Timeout fails	Check the bot has Moderate Members and is above the target.
Purge deletes fewer messages than expected	Some messages may be pinned or older than Discord's bulk delete limit.
Auto-reset did not happen	The bot may have restarted while the timer was in memory.
Member was not DM'd	User may have DMs closed or blocked the bot.

✅ Staff reminders¶

Always include a clear reason.
Use --nodm only when a DM would make the situation worse or is unnecessary.
Prefer !timeout or !quarantine before removal actions where appropriate.
Use !purge since for raid cleanup when you know where the incident started.
Check the mod-log after serious actions.