Skip to content

Commands Reference

Johnny Xmas edited this page Sep 22, 2026 · 16 revisions

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.

Navigation

Table of Contents

  1. Permission Requirements
  2. Reminder Commands
  3. Moderation Commands
  4. Safety & Anti-Raid Commands
  5. Message Management Commands
  6. Autoreply Commands
  7. Role Management Commands
  8. Permission Management Commands
  9. Event Feed Commands
  10. Server Backup Commands
  11. Utility Commands
  12. PetBot Commands

Permission Requirements

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.


Reminder Commands

Manage recurring reminders sent to specific channels at regular intervals.

/set_reminder

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

/list_reminders

Description: Lists all current active reminders.

Parameters: None

Example:

/list_reminders

/delete_reminder

Description: Deletes a specific reminder by title.

Parameters:

  • title (required) - Title of the reminder to delete

Example:

/delete_reminder title:"Daily Standup"

/delete_all_reminders

Description: Deletes all active reminders.

Parameters: None

Example:

/delete_all_reminders

Moderation Commands

Commands for managing server members and enforcing rules.

/voice_chaperone

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) - True to enable, False to disable voice chaperone

Example:

/voice_chaperone enabled:True

/kick

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"

/kick_role

Description: Kicks up to 64 members with a specified role from the server (Discord API limit).

Note: The same role-hierarchy rule as /kick applies 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"

/timeout

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"

Safety & Anti-Raid Commands

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.py sets the value again on startup. Use them to react during an incident; edit config.py for a permanent change.

/raid status

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

/raid protection

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) - True to enable, False to disable

Example:

/raid protection enabled:False

/raid lockdown

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) - True to lock down, False to lift an active lockdown
  • minutes (optional) - How long to lock down for (1–10080). Defaults to RAID_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.

/raid recent_joins

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.

/raid kick_recent

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.

/nuke_protection

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) - True to enable, False to 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.

/spam_protection

Description: Enable or disable message spam protection: cross-channel link spam and mass-mention filtering.

Parameters:

  • enabled (required) - True to enable, False to disable

Example:

/spam_protection enabled:False

Requires Moderate Members (timeouts) and Kick Members (new-account offenders).


Message Management Commands

Commands for managing and cleaning up messages in channels.

/purge_last_messages

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

/purge_string

Description: Deletes messages containing a specific string from a channel.

Note: limit controls 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

/purge_webhooks

Description: Deletes messages sent by webhooks or apps from a channel.

Note: limit is the scan depth, not the delete count — see /purge_string above 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

/botsay

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."

/message_dump

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 limit or use a later start_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

Autoreply Commands

Manage automatic reply rules that trigger when users send messages containing specific strings.

/autoreply add

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

/autoreply list

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

/autoreply remove

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

/autoreply toggle

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

How Autoreplies Work

  1. Message Processing: When any user sends a message, the bot checks it against all enabled autoreply rules for that server
  2. Trigger Matching: The bot searches for trigger strings within the message content
  3. Case Sensitivity: Matching respects the case_sensitive setting for each rule
  4. Response: If a trigger is found, the bot replies to the message with the configured response
  5. Single Response: Only the first matching rule will trigger a response per message

Technical Details

  • Rule IDs: Each rule gets a unique ID in the format {guild_id}_{8_character_hash}
  • Storage: Rules are stored in autoreplies.json and 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

Role Management Commands

Commands for managing user roles efficiently.

/assign_role

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"

/remove_role

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"

/list_users_without_roles

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

Permission Management Commands

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

Channel & Category Permission Commands

/clone_category_permissions

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"

/clone_channel_permissions

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

/clear_category_permissions

Description: Clear permissions from a category.

Parameters:

  • category (required) - Category to clear permissions from

Example:

/clear_category_permissions category:"Old Category"

/clear_channel_permissions

Description: Clear permissions from a channel.

Parameters:

  • channel (required) - Channel to clear permissions from

Example:

/clear_channel_permissions channel:#old-channel

/sync_channel_perms

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"

Role Permission Commands

/clone_role_permissions

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_messages and moderate_members are 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.

/clear_role_permissions

Description: Clear permissions from a role.

Parameters:

  • role (required) - Role to clear permissions from

Example:

/clear_role_permissions role:@Old-Role

Event Feed Commands

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.

/add_event_feed

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.

/list_event_feeds

Description: Lists all registered event feeds with their name, URL, type, channel, and display options.

Parameters: None

Example:

/list_event_feeds

/remove_event_feed

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"

/check_event_feeds

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

How Feed Checking Works

  1. iCal feeds — Parsed directly for VEVENT components with dates, locations, descriptions, and URLs. An event's end time comes from DTEND if present, or is computed from DURATION if that's what the feed provides instead — both are valid per the iCal spec, and a feed that only sets DURATION no longer gets truncated to a flat one-hour event.
  2. 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
  3. 30-day filter — Only events starting within the next 30 days are processed
  4. Discord Events — Created as external scheduled events with duplicate detection (same name + start time)
  5. Persistence — posted_events UIDs are tracked to avoid re-posting; feed configs saved to event_feeds.json
  6. 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.

Server Backup Commands

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.

/server_backup

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

/server_restore

Description: Restores server structure from a /server_backup JSON file.

  1. 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.
  2. Requires an explicit Confirm button click from the same person who ran the command before anything changes.
  3. 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.
  4. Matches existing roles/categories/channels by name, so running it twice updates in place instead of duplicating everything.
  5. 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 .json file produced by /server_backup

Example:

/server_restore backup_file:<attach the .json file>

/auto_backup

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) - True to enable, False to disable
  • interval_hours (optional) - Hours between checks (default 24, 1–720 range). Only used when enabling.

Example:

/auto_backup enabled:True interval_hours:24

Utility Commands

General utility commands for bot management and information.

/log_tail

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 (config-only)

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.

/dashboard

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

PetBot Commands

Fun interaction commands available to all users (not just moderators).

/bot_mood

Description: Check on what the PetBot is up to.

Parameters: None

Example:

/bot_mood

/pet_bot

Description: Pet JohnnyBot.

Parameters: None

Example:

/pet_bot

/bot_pick_fav

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

Command Usage Tips

General Guidelines

  1. Parameter Formatting:

    • Use quotes around parameters that contain spaces
    • User mentions can be done with @username or user IDs
    • Channel references use #channel-name format
  2. 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
  3. 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
  4. Error Handling:

    • Check the bot's response for error messages
    • Use /log_tail to get detailed error information
    • Ensure proper permissions are set for the bot

Best Practices

  • 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

← Back to Home | ← Setup Guide

Clone this wiki locally