Skip to content

Commands

Jump to bottom
Adixqa edited this page Nov 3, 2025 · 13 revisions

PerfectionBot — Commands (slash / tree commands)

Notes (general)

  • Commands use Discord slash commands (/command) instead of text-prefix (!command).
  • Many moderation commands require Discord guild permissions (the code checks interaction.user.guild_permissions) or the Bot Manager role (ID in config: roles.bot_manager_ID).
  • Most moderation actions are logged with log_to_channel() for audit.
  • Examples below show usage and the permission checks enforced in the code.

/flags [user]

What does it do: Shows flags for a specific user, or lists all flagged members in the guild.
Requires: Ban Members (the bot checks interaction.user.guild_permissions.ban_members).
Usage:
/flags
/flags user:123456789012345678
Notes:

  • Omit user or use all to list all flagged members and totals.
  • The command accepts mentions or numeric IDs. If given a mention the code extracts the numeric ID.

/modflags

What does it do: Adds or removes flags for a user (positive to add, negative to subtract).
Requires: Ban Members.
Usage:
/modflags user:@User amount:1
/modflags user:123456789012345678 amount:-1
Notes:

  • user may be a mention or numeric ID; the code extracts the ID with a regex.
  • The stored flag count will never go below 0.

/confirm

What does it do: Confirms a pending punishment created by the lockdown flow.
Requires: Ban Members.
Usage:
/confirm
Notes: Calls handle_confirm from PerfectionBot.scripts.lockdown.

/revoke

What does it do: Cancels a pending punishment / cancels lockdown.
Requires: Ban Members.
Usage:
/revoke
Notes: Calls handle_revoke from PerfectionBot.scripts.lockdown.

/clear

What does it do: Bulk-deletes recent messages in the channel.
Requires: Manage Messages.
Usage:
/clear amount:10
Notes: The code purges amount + 1 messages (to remove the command invocation as well) and logs the action.

/ping

What does it do: Simple bot health/response check. (Legacy; playful response.)
Requires: None.
Usage:
/ping
Response: Pong! 🏓

/resetver

What does it do: Removes the verified role from everyone and re-sends the verification prompt/message. Useful after rule changes.
Requires: Administrator.
Usage:
/resetver
Notes: Uses verify.ResetVerification() and updates verify_msg_ids.

/mute [duration] [reason]

What does it do: Timeouts (mutes) a member via Discord's timeout API.
Requires: Moderate Members.
Usage:
/mute member:@User duration:600 reason:Spamming
Notes:

  • duration is in seconds (default in code: 180 seconds).
  • reason is optional (default: No reason provided).
  • The bot will refuse to timeout members whose top role is >= the bot's top role.

/unmute

What does it do: Removes an active timeout from a member.
Requires: Moderate Members.
Usage:
/unmute member:@User
Notes: The bot edits the member to set timed_out_until=None, sends a DM if possible, and logs the action.

/kick [reason]

What does it do: Kicks a member from the guild.
Requires: Kick Members.
Usage:
/kick member:@User reason:Rule violation
Notes: The bot attempts to DM the member before kicking. It will fail if role hierarchy prevents the kick.

/ban [reason]

What does it do: Bans a member from the guild.
Requires: Ban Members.
Usage:
/ban member:@User reason:Severe rule violation
Notes: The bot attempts to DM the member before banning. It will fail if role hierarchy prevents the ban.

/synclevels

What does it do: Recalculates XP and reapplies level roles to all members. Use after changes to level-role mappings or after bot downtime.
Requires: Bot Manager role (configured in roles.bot_manager_ID). If roles.bot_manager_ID is not set the command enforces nothing extra beyond the check in code.
Usage:
/synclevels
Notes: The command iterates guild members, reads XP (leveling.read_xp), computes level, and calls leveling.check_level_reward. This operation may take some time.

/lvl [user]

What does it do: Shows level and XP for a user.
Requires: None.
Usage:
/lvl
/lvl user:@User
Notes: If user is given it shows the user's current level.

/stop

What does it do: Shuts down the bot process on the host. (Host must restart the process.)
Requires: Administrator or Bot Manager.
Usage:
/stop

/senddm

What does it do: Opens a modal that sends a DM to a single member or broadcasts to all non-bot members.
Requires: Administrator.
Usage:
/senddm
(fill modal: Target (optional user ID), Message text)
Notes:

  • Leave Target empty to DM everyone (non-bot members). The bot spaces sends by ~0.35s to avoid rate limits.
  • A summary/log entry is created after the broadcast.

Watchdog commands (watchdog.py)

These commands live under the /watchdog group.

/watchdog status

What does it do: Shows system metrics for the bot host (RAM, CPU, Disk, OS, Python, gateway latency).
Requires: None (view-only).
Usage:
/watchdog status
Notes: Uses collect_status() and builds an embed with _make_status_embed().

/watchdog reboot

What does it do: Reboots the bot process remotely (runs PerfectionBot.scripts.reboot).
Requires: Bot Manager role (ID from roles.bot_manager_ID) or bot owner.
Usage:
/watchdog reboot
Notes: The command spawns python3 -m PerfectionBot.scripts.reboot in the project root; failure is logged.

Config keys referenced

  • roles.bot_manager_ID — ID for the Bot Manager role (used by /synclevels and /watchdog reboot checks).
  • LOG_ID — channel ID used by watchdog for alerts (if provided).
  • behaviour.flags.review_channel — channel ID where appeals are posted for moderator review.
  • VERIFY_ID / verify-related config — used by verification/reset flows.
  • LEVELING.CHANNEL_ID — optional channel ID where leveling-up embeds are sent.

Quick summary

/flags [user]              — show flags for a user or all flagged members (Ban Members)
/modflags <user> <amount>  — modify flags (Ban Members)
/confirm                   — confirm a lockdown punishment (Ban Members)
/revoke                    — revoke a lockdown punishment (Ban Members)
/clear <amount>            — bulk-delete messages (Manage Messages)
/ping                      — health check (public)
/resetver                  — reset verification and re-post message (Administrator)
/mute <member> [d] [r]     — timeout a member (Moderate Members)
/unmute <member>           — remove timeout (Moderate Members)
/kick <member> [reason]    — kick a member (Kick Members)
/ban <member> [reason]     — ban a member (Ban Members)
/synclevels                — recalculate & reapply level roles (Bot Manager role)
/lvl [user]                — show level & XP (public)
/stop                      — stop the bot process (Administrator or Bot Manager)
/senddm                    — modal to DM single user or broadcast (Administrator)
/watchdog status           — show host/system status (public)
/watchdog reboot           — restart the bot (Bot Manager / owner)

Clone this wiki locally