Skip to content

Commands Reference

Jump to bottom
Johnny Xmas edited this page Jun 10, 2026 · 11 revisions

Commands Reference

Complete documentation for all JohnnyBot commands. Most commands require the moderator role; exceptions are noted below.

Navigation

Table of Contents

  1. Permission Requirements
  2. Reminder Commands
  3. Moderation Commands
  4. Message Management Commands
  5. Autoreply Commands
  6. Role Management Commands
  7. Permission Management Commands
  8. Event Feed Commands
  9. Utility Commands
  10. PetBot Commands

Permission Requirements

Permission Level Commands Available Who Can Use
Moderator Most commands (moderation, message management, reminder set/delete, role assignment, permission management, autoreply add/remove/toggle, event feed add/remove/check, /voice_chaperone) Users with the MODERATOR_ROLE_NAME role
Everyone PetBot commands, /log_tail, /list_reminders, /autoreply list, /dashboard, /list_users_without_roles, /list_event_feeds All server members

Note: The moderator role name is configured in your config.py as MODERATOR_ROLE_NAME.

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.

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

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

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
  • reason (optional) - Reason for the timeout

Example:

/timeout member:@user duration:3600 reason:"Inappropriate behavior"

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

Example:

/purge_last_messages channel:#general limit:10

/purge_string

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

Parameters:

  • channel (required) - The channel to purge messages from
  • search_string (required) - String to search for in messages

Example:

/purge_string channel:#general search_string:"spam"

/purge_webhooks

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

Parameters:

  • channel (required) - The channel to purge messages from

Example:

/purge_webhooks channel:#general

/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 (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

Description: Lists all users that do not have any server role assigned (excluding bots).

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.

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

/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 "This Week" embeds for the server's Discord Scheduled Events starting that week
  • Day-of reminders — every day at 10am, the bot posts "Today" embeds for events starting that day
  • 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. "BurbSec")
  • 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:"BurbSec" calendar_url:"https://www.meetup.com/burbsec/events/ical/" channel:#local-events

/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:"BurbSec"

/check_event_feeds

Description: Manually check all event feeds for new events now. Reports how many feeds were checked, events found, and any errors.

Parameters: None

Example:

/check_event_feeds

How Feed Checking Works

  1. iCal feeds — Parsed directly for VEVENT components with dates, locations, descriptions, and URLs
  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

Utility Commands

General utility commands for bot management and information.

/log_tail

Description: Sends the last specified number of lines from the bot's log file to the user via DM.

Parameters:

  • lines (required) - Number of lines to retrieve

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.

/dashboard

Description: Display a dashboard of all available commands grouped by category. Posts the dashboard to the current channel for all users to see.

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 moderator role
    • 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