Repository navigation
Commands Reference
Complete documentation for all JohnnyBot commands. Most commands require the Manage Messages permission; exceptions are noted below. Every command requires a server — none can be invoked in a DM.
- Permission Requirements
- Reminder Commands
- Moderation Commands
- Safety & Anti-Raid Commands
- Message Management Commands
- Autoreply Commands
- Role Management Commands
- Permission Management Commands
- Event Feed Commands
- Server Backup Commands
- Utility Commands
- PetBot Commands
| Permission Level | Commands Available | Who Can Use |
|---|---|---|
| Moderator (Manage Messages) | Most commands (moderation, message management, reminder set/delete, role assignment, permission management, autoreply add/remove/toggle, event feed add/remove/check, /voice_chaperone, /raid subcommands, /nuke_protection, /spam_protection, /log_tail, /list_users_without_roles) |
Anyone with the Manage Messages permission — the permission that lets someone delete other people's messages |
| Admin (Administrator) |
/server_backup, /server_restore, /auto_backup
|
Anyone with the Administrator permission |
| Everyone | PetBot commands, /list_reminders, /autoreply list, /dashboard, /list_event_feeds
|
All server members |
Note: Access is based on the Discord permission itself, not a role name — there's nothing to create or configure. Any role (or combination of roles) that grants a member Manage Messages or Administrator qualifies automatically, on any server the bot joins.
The check is resolved guild-wide: a permission granted only through a channel-specific overwrite (e.g. "let this person manage messages in #support") does not count. This is deliberate — it keeps a narrow, single-channel grant from turning into server-wide moderator access to every command here.
All commands require a server context. None can be invoked in a DM.
Manage recurring reminders sent to specific channels at regular intervals.
Description: Sets a reminder message to be sent to a specified channel at regular intervals.
Parameters:
-
channel(required) - The target channel for the reminder -
title(required) - Title of the reminder -
message(required) - The reminder content -
interval(required) - Interval in seconds between reminders (minimum 60)
Example:
/set_reminder channel:#general title:"Daily Standup" message:"Don't forget about the daily standup at 9 AM!" interval:86400
Description: Lists all current active reminders.
Parameters: None
Example:
/list_reminders
Description: Deletes a specific reminder by title.
Parameters:
-
title(required) - Title of the reminder to delete
Example:
/delete_reminder title:"Daily Standup"
Description: Deletes all active reminders.
Parameters: None
Example:
/delete_all_reminders
Commands for managing server members and enforcing rules.
Description: Enable or disable the voice channel chaperone functionality. Disabling it immediately releases any mutes it currently has in place, rather than leaving affected members muted until they next change voice channels.
Parameters:
-
enabled(required) -Trueto enable,Falseto disable voice chaperone
Example:
/voice_chaperone enabled:True
Description: Kicks up to 64 members from the server (Discord API limit).
Note: You cannot kick a member whose highest role is at or above your own (the server owner is exempt from this and can kick anyone the bot can). This is checked in addition to the existing rule that the bot cannot kick anyone at or above its own highest role — both must hold for a kick to proceed.
Parameters:
-
members(required) - Members to kick (separate multiple users with spaces) -
reason(optional) - Reason for the kick
Example:
/kick members:"@user1 @user2" reason:"Violation of server rules"
Description: Kicks up to 64 members with a specified role from the server (Discord API limit).
Note: The same role-hierarchy rule as
/kickapplies per member — anyone at or above your own highest role is skipped, and you can never kick yourself this way even if you hold the target role.
Parameters:
-
role(required) - Role whose members to kick -
reason(optional) - Reason for the kick
Example:
/kick_role role:@Spammers reason:"Mass cleanup of spam accounts"
Description: Timeouts a member for a specified duration.
Parameters:
-
member(required) - Member to timeout -
duration(required) - Timeout duration in seconds (1 second to 28 days / 2,419,200 seconds — Discord's own cap; Discord's client rejects anything outside that range before the command can even be run) -
reason(optional) - Reason for the timeout
Example:
/timeout member:@user duration:3600 reason:"Inappropriate behavior"
Runtime controls for the three automatic protection systems. The systems themselves run without being invoked — see Safety Systems for how detection works, what the thresholds mean, and how to tune them.
Note: All of these are Moderator-level (Manage Messages). Moderators are exempt from every automatic protection system, so these commands never act against the person running them.
The toggles do not persist across a restart —
config.pysets the value again on startup. Use them to react during an incident; editconfig.pyfor a permanent change.
Description: Shows the current raid-protection configuration, whether a lockdown is active (and until when), and how many joins have landed in the current detection window.
Parameters: None
Example:
/raid status
Description: Enable or disable automatic join-burst detection. Disabling it also lifts any lockdown currently in progress — turning the system off mid-incident means "stand down", not just "stop watching".
Parameters:
-
enabled(required) -Trueto enable,Falseto disable
Example:
/raid protection enabled:False
Description: Manually pause — or lift a pause on — server invites and member-to-member DMs, independent of automatic detection. Useful when you can see a raid coming from outside the join-rate signal, or to release a lockdown early.
Uses Discord's own incident actions, so the pause expires on its own even if the bot goes offline.
Parameters:
-
enabled(required) -Trueto lock down,Falseto lift an active lockdown -
minutes(optional) - How long to lock down for (1–10080). Defaults toRAID_LOCKDOWN_MINUTES
Examples:
/raid lockdown enabled:True minutes:120
/raid lockdown enabled:False
Requires the bot to have Manage Server. Without it the command reports that it cannot pause invites rather than failing silently.
Description: Lists members who joined within the given window, flagging any account younger than RAID_NEW_ACCOUNT_HOURS, and follows up with an avatar-cluster breakdown grouping accounts that share an identical profile picture.
The clustering is what distinguishes a raid from a legitimate surge: "12 of 14 share only 1 distinct avatar" is coordinated; fourteen distinct avatars is probably a real event.
Parameters:
-
minutes(optional) - How far back to look (1–1440). Default:30
Example:
/raid recent_joins minutes:60
The cluster analysis arrives as a second message, because the combined output can exceed Discord's 2000-character limit on a large raid.
Description: Kicks recently-joined members whose accounts are also flagged as new (younger than RAID_NEW_ACCOUNT_HOURS).
Defaults to a dry run. The first invocation shows you exactly who would be removed and changes nothing; you must re-run with dry_run:False to actually kick. A real moderator can have joined five minutes ago too, which is why this never fires blind.
Always excluded: moderators (anyone with Manage Messages), the server owner, the bot itself, and anyone whose highest role is at or above your own.
Parameters:
-
minutes(required) - How far back to look for joins (1–1440) -
dry_run(optional) - Preview without kicking. Default:True
Examples:
/raid kick_recent minutes:30
/raid kick_recent minutes:30 dry_run:False
Requires the bot to have Kick Members.
Description: Enable or disable anti-nuke monitoring — the audit-log watcher that catches a compromised moderator account, a member prune, or a permission escalation.
The response mode itself (strip_roles vs alert) is set in config.py, not here; the command reports which mode is currently active.
Parameters:
-
enabled(required) -Trueto enable,Falseto disable
Example:
/nuke_protection enabled:True
Requires the bot to have Manage Roles to strip a compromised account's roles or revert a permission grant. Note the bot can never act on someone whose highest role outranks its own — which frequently includes Administrators. The alert says so explicitly when that happens.
Description: Enable or disable message spam protection: cross-channel link spam and mass-mention filtering.
Parameters:
-
enabled(required) -Trueto enable,Falseto disable
Example:
/spam_protection enabled:False
Requires Moderate Members (timeouts) and Kick Members (new-account offenders).
Commands for managing and cleaning up messages in channels.
Description: Deletes a specified number of recent messages from a channel.
Parameters:
-
channel(required) - The channel to purge messages from -
limit(required) - Number of messages to delete (1–1000)
Example:
/purge_last_messages channel:#general limit:10
Description: Deletes messages containing a specific string from a channel.
Note:
limitcontrols how many recent messages are scanned for the string, not how many are deleted. Earlier versions of this command scanned only the last 100 messages regardless of what you asked for, and silently reported "Deleted 0 message(s)" if the match was further back — that's fixed; the scan depth is now explicit and defaults to 1000.
Parameters:
-
channel(required) - The channel to purge messages from -
search_string(required) - String to search for in messages -
limit(optional) - How many recent messages to scan (1–10,000, default 1000)
Example:
/purge_string channel:#general search_string:"spam"
/purge_string channel:#general search_string:"spam" limit:5000
Description: Deletes messages sent by webhooks or apps from a channel.
Note:
limitis the scan depth, not the delete count — see/purge_stringabove for why this matters.
Parameters:
-
channel(required) - The channel to purge messages from -
limit(optional) - How many recent messages to scan (1–10,000, default 1000)
Example:
/purge_webhooks channel:#general
/purge_webhooks channel:#general limit:5000
Description: Makes the bot send a message to a specified channel.
Parameters:
-
channel(required) - Target channel -
message(required) - Message to send
Example:
/botsay channel:#announcements message:"Server maintenance will begin in 30 minutes."
Description: Dumps a user's messages from a specified channel into a zipped archive and DMs it to you as a file attachment.
Important: Discord caps DM attachments at 25 MB. If the archive exceeds the cap, reduce the
limitor use a laterstart_date.
Parameters:
-
user(required) - User whose messages to dump -
channel(required) - Channel to dump messages from -
start_date(required) - Start date in YYYY-MM-DD format (e.g., 2025-01-01) -
limit(optional) - Maximum number of messages to fetch (1–100,000, default: 1000)
Features:
- Retrieves messages with proper pagination
- Handles Discord API rate limits
- Automatically cleans up orphaned dump files
- Delivers the zipped archive via DM
Example:
/message_dump user:@username channel:#general start_date:"2025-01-01" limit:500
Manage automatic reply rules that trigger when users send messages containing specific strings.
Description: Creates a new autoreply rule that automatically responds when a trigger string is found in messages.
Parameters:
-
trigger(required) - The string to watch for in messages (max 500 characters) -
reply(required) - The message to send when the trigger is found (max 2000 characters) -
case_sensitive(optional) - Whether trigger matching should be case sensitive (default: False)
Features:
- Rules are isolated per Discord server
- Only the first matching rule will trigger per message
- Bot messages are ignored to prevent loops
- Rules persist across bot restarts
Example:
/autoreply add trigger:"thanks bot" reply:"You're welcome! 😊" case_sensitive:False
Description: Lists all autoreply rules for the current server.
Parameters: None
Features:
- Shows rule ID, status, trigger, reply, and case sensitivity settings
- Displays up to 10 rules per page
- Available to all users (not just moderators)
- Truncates long strings for better display
Example:
/autoreply list
Description: Removes an autoreply rule by its unique ID.
Parameters:
-
rule_id(required) - The ID of the autoreply rule to remove (shown in/autoreply list)
Example:
/autoreply remove rule_id:123456789_abcd1234
Description: Enables or disables an existing autoreply rule without removing it.
Parameters:
-
rule_id(required) - The ID of the autoreply rule to toggle
Features:
- Disabled rules remain in the system but won't trigger responses
- Useful for temporarily disabling rules without losing them
- Status is shown in
/autoreply list
Example:
/autoreply toggle rule_id:123456789_abcd1234
- Message Processing: When any user sends a message, the bot checks it against all enabled autoreply rules for that server
- Trigger Matching: The bot searches for trigger strings within the message content
- Case Sensitivity: Matching respects the case_sensitive setting for each rule
- Response: If a trigger is found, the bot replies to the message with the configured response
- Single Response: Only the first matching rule will trigger a response per message
-
Rule IDs: Each rule gets a unique ID in the format
{guild_id}_{8_character_hash} -
Storage: Rules are stored in
autoreplies.jsonand loaded into memory for fast processing - Thread Safety: Rule modifications are thread-safe using locks
- Error Handling: Failed replies are logged but don't crash the system
Commands for managing user roles efficiently.
Description: Assigns a role to up to 64 users at once (Discord API limit).
Parameters:
-
role(required) - Role to assign to the users -
members(required) - Members to assign the role to
Features:
- Accepts user mentions, user IDs, usernames, or display names
- Supports both spaces and newlines as separators for user lists
Example:
/assign_role role:@Member members:"@user1 @user2 @user3"
Description: Removes a role from up to 64 users at once (Discord API limit).
Parameters:
-
role(required) - Role to remove from the users -
members(required) - Members to remove the role from
Example:
/remove_role role:@Temporary members:"@user1 @user2"
Access: Moderator only.
Description: Lists all users that do not have any server role assigned (excluding bots). On very large servers the list is truncated to fit Discord's embed limits, and the footer says how many of the total are shown.
Parameters: None
Example:
/list_users_without_roles
Mass clone or clear permissions for categories, channels, and roles.
Important Notes:
- All copy commands remove existing permissions from the destination before copying new ones
- The bot cannot manage roles which are at the same level or above any roles the bot has
- Discord blocks bots from managing permissions for roles that have moderator capabilities
- You will have to manage these manually
Description: Clone permissions from a source category to a destination category.
Parameters:
-
source_category(required) - Source category to copy permissions from -
destination_category(required) - Destination category to copy permissions to
Example:
/clone_category_permissions source_category:"Public Channels" destination_category:"New Category"
Description: Clone permissions from a source channel to a destination channel.
Parameters:
-
source_channel(required) - Source channel to copy permissions from -
destination_channel(required) - Destination channel to copy permissions to
Example:
/clone_channel_permissions source_channel:#general destination_channel:#new-channel
Description: Clear permissions from a category.
Parameters:
-
category(required) - Category to clear permissions from
Example:
/clear_category_permissions category:"Old Category"
Description: Clear permissions from a channel.
Parameters:
-
channel(required) - Channel to clear permissions from
Example:
/clear_channel_permissions channel:#old-channel
Description: Sync permissions for all channels in a category with the category's permissions.
Parameters:
-
source_category(required) - Category whose permissions will be synced to all its channels
Example:
/sync_channel_perms source_category:"Public Channels"
Description: Clone permissions from a source role to a destination role.
Moderation permissions are excluded. Administrator,
ban_members,kick_members,manage_roles,manage_guild,manage_channels,manage_messagesandmoderate_membersare never copied — otherwise this command would let a moderator grant permissions they do not hold themselves, since the bot performs the edit. The reply lists which permissions were skipped; grant those manually in Server Settings if you intend to.
Parameters:
-
source_role(required) - Source role to copy permissions from -
destination_role(required) - Destination role to copy permissions to
Example:
/clone_role_permissions source_role:@Moderator destination_role:@Junior-Mod
In this example the moderation permissions that make @Moderator a moderator are not transferred; @Junior-Mod receives only the everyday permissions.
Description: Clear permissions from a role.
Parameters:
-
role(required) - Role to clear permissions from
Example:
/clear_role_permissions role:@Old-Role
Subscribe to iCal or RSS feeds to automatically create Discord Events and announce them.
Feeds are checked weekly (Monday 9am) and on-demand. Events in the next 30 days are created as Discord Scheduled Events (duplicates detected by name + start time). For RSS feeds (e.g. Meetup), the bot follows each entry's link and extracts JSON-LD Event data from the page for accurate dates, locations, and descriptions.
Adding a feed also enables automatic event announcements to the channel you choose — no separate setup command needed:
- Weekly preview — every Monday at 10am, the bot posts one message per event starting that week, headed "📢 This Week"
- Day-of reminders — every day at 10am, the bot posts one message per event starting that day, headed "📢 Today"
- Each message is the heading followed by the event's Discord URL; Discord auto-unfurls that URL into its own native event card (date, time, location, RSVP), so no custom embed is sent alongside it
- Announcements read the guild's Discord Scheduled Events directly, so manually created events are announced too
All scheduled jobs use the timezone set by BOT_TIMEZONE in config.py (default America/Chicago). Feed subscriptions persist across bot restarts in event_feeds.json; the announcement channel persists in event_announce.json.
Description: Adds a calendar (iCal) or RSS feed URL. The feed type is auto-detected. Immediately performs an initial check after adding and enables weekly/day-of announcements to the given channel.
Parameters:
-
feed_name(required) - A short name to identify this feed (e.g. "Monthly Meetup") -
calendar_url(required) - URL of the iCal or RSS feed -
channel(required) - Discord channel to post weekly and day-of event announcements
Example:
/add_event_feed feed_name:"Monthly Meetup" calendar_url:"https://www.meetup.com/your-group/events/ical/" channel:#local-events
Meetup groups expose an iCal feed at https://www.meetup.com/<group-slug>/events/ical/. Any standard iCal or RSS feed works.
Description: Lists all registered event feeds with their name, URL, type, channel, and display options.
Parameters: None
Example:
/list_event_feeds
Description: Removes an event feed by name. If it was the guild's last feed, automatic announcements are disabled too.
Parameters:
-
feed_name(required) - Name of the feed to remove (shown in/list_event_feeds)
Example:
/remove_event_feed feed_name:"Monthly Meetup"
Description: Manually check this server's event feeds for new events now. Reports how many feeds were checked, events found, and any errors. On a bot that serves more than one server, this only checks and acts on the server you run it in — it never touches another server's feeds or creates events there.
Parameters: None
Example:
/check_event_feeds
-
iCal feeds — Parsed directly for
VEVENTcomponents with dates, locations, descriptions, and URLs. An event's end time comes fromDTENDif present, or is computed fromDURATIONif that's what the feed provides instead — both are valid per the iCal spec, and a feed that only setsDURATIONno longer gets truncated to a flat one-hour event. -
RSS feeds — Each RSS
<item>link is followed; the page is scraped for<script type="application/ld+json">containing a@type: "Event"object (schema.org); this provides accurate start/end dates, locations, and descriptions - 30-day filter — Only events starting within the next 30 days are processed
- Discord Events — Created as external scheduled events with duplicate detection (same name + start time)
-
Persistence —
posted_eventsUIDs are tracked to avoid re-posting; feed configs saved toevent_feeds.json -
Fetch safety — Feed URLs (and the event-page URLs found inside RSS feeds) are checked before fetching: only
http(s)://is accepted, and a URL that resolves to a private, loopback, or link-local address is refused. Every response is size-capped, so a misbehaving or malicious feed can't exhaust memory or reach internal services.
Access: Administrator only — stricter than the Manage Messages gate on other moderation commands, since these can rewrite the server's entire structure.
Backs up and restores server structure — roles, categories, channels, permission overwrites, and emoji. It does not back up message history, member role assignments for people not currently in the server, invites, audit logs, or boost state; none of those are restorable via Discord's API, and a backup that implied otherwise would be misleading.
Description: Serializes the current server's roles, categories, channels, permission overwrites, and emoji into a JSON file and DMs it to you. If the bot can't DM you (privacy settings), the file path on the bot host is reported instead.
Parameters: None
Example:
/server_backup
Description: Restores server structure from a /server_backup JSON file.
- Shows a preview: what will be created, what will be updated, and (if the backup is from a different server) a loud warning that this is a cross-server clone.
- Requires an explicit Confirm button click from the same person who ran the command before anything changes.
- Automatically takes a safety snapshot of the current state first and DMs it to you — but restore only creates and updates, it never deletes, so that snapshot can restore names/permissions/overwrites afterward but can't remove anything the restore newly created.
- Matches existing roles/categories/channels by name, so running it twice updates in place instead of duplicating everything.
- Never touches a role (or overwrite targeting a role) that is Administrator, managed (bot/booster roles), above the bot's own role, or already carries moderation permissions — and strips moderation-level permission bits from anything it does create or edit. A hand-edited backup file can't be used to grant a role Administrator or ban/kick permissions through this command.
Parameters:
-
backup_file(required) - The.jsonfile produced by/server_backup
Example:
/server_restore backup_file:<attach the .json file>
Description: Enables or disables automatic backups on a recurring interval for this server. A new backup is only actually created — and posted to the moderators channel — when the server's structure has changed since the last one, so it won't spam the channel with identical backups.
Parameters:
-
enabled(required) -Trueto enable,Falseto disable -
interval_hours(optional) - Hours between checks (default 24, 1–720 range). Only used when enabling.
Example:
/auto_backup enabled:True interval_hours:24
General utility commands for bot management and information.
Access: Moderator only.
Description: Sends the last specified number of lines from the bot's log file to the user via DM.
Note: The log records deleted message content from protected channels, member names and IDs, and moderation actions, which is why the command is restricted to moderators.
Parameters:
-
lines(required) - Number of lines to retrieve (1–200). That upper bound is enforced before the command can even run; in practice you'll rarely reach it, since Discord caps a message at 2000 characters and the output is sent in one block — roughly 15 lines is the practical maximum per invocation regardless of what you request.
Example:
/log_tail lines:50
Update checking has no slash command — it's controlled entirely by config.py. With UPDATE_CHECKING_ENABLED, the bot checks the GitHub repository daily and notifies moderators when updates are available.
If AUTO_UPDATE_ENABLED is also set, the bot goes further: updates whose CI checks passed and which don't modify config_example.py are pulled automatically (git pull --ff-only, plus pip install if requirements.txt changed) and the bot restarts itself, announcing the update in the moderators channel. Updates that touch config_example.py, lack green CI, or fail to pull fall back to a manual-update notification.
Notifications show a git tag (e.g. v1.0.0) as the version label whenever the relevant commit is tagged on GitHub, falling back to a short commit SHA otherwise. This is display-only — whether an update exists is still decided by comparing commits directly, so an untagged commit is never missed or skipped.
Description: Display a dashboard of all available commands grouped by category. Posts the dashboard to the current channel for all users to see. The full listing exceeds Discord's 2000-character message limit, so it's posted as two or more consecutive messages, split cleanly between categories.
Parameters: None
Example:
/dashboard
Fun interaction commands available to all users (not just moderators).
Description: Check on what the PetBot is up to.
Parameters: None
Example:
/bot_mood
Description: Pet JohnnyBot.
Parameters: None
Example:
/pet_bot
Description: See who JohnnyBot prefers today.
Parameters:
-
user1(required) - First potential favorite -
user2(required) - Second potential favorite
Example:
/bot_pick_fav user1:@Alice user2:@Bob
-
Parameter Formatting:
- Use quotes around parameters that contain spaces
- User mentions can be done with
@usernameor user IDs - Channel references use
#channel-nameformat
-
Batch Operations:
- Many commands support multiple users (up to 64, a Discord API limit)
- Separate multiple users with spaces or newlines (mentions, user IDs, usernames, or display names all work)
- Use consistent formatting for better results
-
Permission Considerations:
- Most commands require the Manage Messages permission; server backup/restore require Administrator
- The bot cannot manage roles higher than its own
- Some Discord limitations apply to permission management
-
Error Handling:
- Check the bot's response for error messages
- Use
/log_tailto get detailed error information - Ensure proper permissions are set for the bot
- Test commands in a safe environment before using in production
- Use descriptive reasons for moderation actions
- Regular cleanup of old reminders and event feeds
- Monitor logs regularly for any issues
- Keep backups of important configurations