Skip to content

COMMANDS.md

Latest commit

 

History

History
2549 lines (1774 loc) · 60.5 KB

COMMANDS.md

File metadata and controls

2549 lines (1774 loc) · 60.5 KB

KoolBot Commands Reference

Complete reference for all KoolBot commands with examples and detailed explanations.

Note: All commands must be enabled through configuration before they appear in Discord.
Use /config set key:command.enabled value:true and then /config reload to enable commands.

📋 Table of Contents

👥 User Commands

Commands available to all server members.

/ping

Description: Check if the bot is responding and measure latency.

Configuration:

/config set key:ping.enabled value:true
/config reload

Usage:

/ping

Response:

Pong! 🏓
Bot Latency: 45ms
API Latency: 123ms

Use Cases:

  • Verify bot is online and responsive
  • Check connection quality
  • Troubleshoot lag issues

/help

Description: Get help with KoolBot commands. Lists all available commands or shows detailed information about a specific command.

Note: This is a core command that is always enabled and does not require configuration.

Usage:

/help                    # List all commands
/help command:ping       # Get detailed help for a specific command

Parameters:

  • command (optional) - Name of the command to get detailed help for

Example Responses:

# List all commands
📚 KoolBot Help
✅ Enabled Commands
/ping - Check if the bot is responding and measure latency.
/help - Get help with KoolBot commands.
...

# Specific command help
📖 Help: /ping
Check if the bot is responding and measure latency.
Usage: /ping
Status: ✅ Enabled

Use Cases:

  • Discover available commands
  • Learn command syntax
  • Check if a command is enabled
  • New user onboarding

/voicestats

Description: Voice channel statistics and leaderboards. This unified command combines leaderboard (top) and personal stats (user) functionality.

Configuration:

# Requires voice tracking to be enabled
/config set key:voicetracking.enabled value:true
/config reload

# Optional: Enable individual subcommands
/config set key:voicetracking.stats.top.enabled value:true
/config set key:voicetracking.stats.user.enabled value:true
/config reload

Subcommand: top

Description: View voice channel activity leaderboards showing top users by time spent.

Usage:

/voicestats top
/voicestats top limit:20
/voicestats top period:month
/voicestats top period:alltime limit:10

Parameters:

  • limit (optional) - Number of users to display (1-50, default: 10)
  • period (optional) - Time period: week, month, alltime (default: week)

Example Response:

Top Voice Channel Users (week):
🥇 Alice: 24h 15m
🥈 Bob: 18h 32m
🥉 Charlie: 12h 45m
4. David: 8h 20m
5. Emma: 6h 10m

Use Cases:

  • See who's most active in voice channels
  • Create friendly competition
  • Recognize community engagement

Subcommand: user

Description: View personal voice channel statistics and activity history for yourself or another user.

Usage:

/voicestats user
/voicestats user user:@Alice
/voicestats user period:month
/voicestats user user:@Alice period:alltime

Parameters:

  • user (optional) - The user to show statistics for (defaults to yourself)
  • period (optional) - Time period: week, month, alltime (default: week)

Example Response:

Voice Channel Statistics for Alice (week):
Total Time: 24h 15m
Last Seen: 2026-01-29 12:00:00

Recent Sessions:
• Gaming Room: 3h 45m
• Study Hall: 2h 15m
• Music Lounge: 1h 30m

Use Cases:

  • Track your own voice channel usage
  • View another user's activity
  • See activity trends
  • Check recent session history

/seen

Description: Check when a user was last active in voice channels.

Configuration:

/config set key:voicetracking.enabled value:true
/config set key:voicetracking.seen.enabled value:true
/config reload

Usage:

/seen user:@Username

Parameters:

  • user (required) - The user to look up

Example Response:

👤 Alice was last seen:
🕐 2 hours ago
📍 In: Gaming Room
⏱️ Duration: 3h 45m

Use Cases:

  • Check if someone has been online recently
  • See what channel they were in
  • Track member activity patterns

/achievements

Description: View earned badges and achievements from voice channel activity. Displays persistent accolades earned through milestones and participation.

Configuration:

# Enable achievements system
/config set key:achievements.enabled value:true
/config reload

Usage:

/achievements                    # View your own achievements
/achievements user:@Username     # View another user's achievements

Parameters:

  • user (optional) - The user to view achievements for (defaults to yourself)

Example Response:

🏆 Alice's Achievements

🎖️ Accolades (Permanent)

🎉 First Steps - 12 hrs
Spent your first hour in voice chat
Earned: 2026-01-10

🎖️ Voice Veteran - 150 hrs
Reached 100 hours in voice chat
Earned: 2026-01-15

🏃 Marathon Runner - 6 hrs
Completed a 4+ hour voice session
Earned: 2026-01-12

🦋 Social Butterfly - 15 users
Voiced with 10+ unique users
Earned: 2026-01-14

📊 Summary
Total Accolades: 4
Total Achievements: 0

Available Accolades:

  • 🎉 First Steps - Spent your first hour in voice chat
  • 🎖️ Voice Veteran - Reached 100 hours
  • 🏅 Voice Elite - Reached 500 hours
  • 🏆 Voice Master - Reached 1000 hours
  • 👑 Voice Legend - Reached 8765 hours (1 year!)
  • 🏃 Marathon Runner - Completed a 4+ hour session
  • 🦸 Ultra Marathoner - Completed an 8+ hour session
  • 🦋 Social Butterfly - Voiced with 10+ unique users
  • 🤝 Connector - Voiced with 25+ unique users
  • 🦉 Night Owl - 50+ hours late night (10 PM - 6 AM UTC)
  • 🐦 Early Bird - 50+ hours early morning (6 AM - 10 AM UTC)
  • 🎮 Weekend Warrior - 100+ hours on weekends
  • 💼 Weekday Warrior - 100+ hours on weekdays
  • 🔥 On a Roll - Connected for 7 consecutive days (5+ min/day)
  • ⚡ Dedicated AF - Connected for 14 consecutive days (5+ min/day)
  • 💀 No-Lifer - Connected for 30 consecutive days (5+ min/day)
  • 🗣️ Quotable - Been quoted for the first time
  • 📝 Quote Master - Added 10 quotes to the collection
  • 📚 Quote Collector - Added 50 quotes to the collection
  • 🏆 Quote Legend - Added 100 quotes to the collection
  • ⭐ Widely Quoted - Been quoted 25 times
  • 💫 Quote Icon - Been quoted 50 times
  • 🔥 Viral Quote - Have a quote with 10+ likes

Note on Time-Based Accolades:

  • Night Owl and Early Bird times are calculated in UTC timezone (the bot's server time)
  • These times may differ from your local timezone depending on your location
  • Weekend Warrior and Weekday Warrior use UTC for determining day of week
  • Calculate your local time offset from UTC to know when these periods occur in your timezone

Notification System:

When you earn a new accolade, you'll receive:

  • A DM from the bot with details about your achievement
  • Announcement in the weekly voice stats channel

Use Cases:

  • Track your voice activity milestones
  • View your collection of earned badges
  • Compare achievements with friends
  • Get motivated to participate more

/quote

Description: Add and manage memorable quotes in a dedicated bot-managed channel. All quotes are posted in a channel where users can react with 👍/👎.

Configuration:

# Enable quotes and set channel
/config set key:quotes.enabled value:true
/config set key:quotes.channel_id value:"YOUR_CHANNEL_ID"
/config set key:quotes.cooldown value:60
/config set key:quotes.max_length value:1000
/config reload

Subcommands:

/quote add

Add a new quote to the quote channel.

Usage:

/quote add text:"Great quote!" author:@Alice

Parameters:

  • text (required): The quote text to add
  • author (required): The user who said the quote (mention/select the user)

Example Response:

✅ Quote added successfully and posted to the quote channel!

/quote edit

Edit an existing quote that you added.

Usage:

/quote edit id:"697bdfe2808f7d245289392c" text:"Updated quote!"
/quote edit id:"697bdfe2808f7d245289392c" author:@Bob
/quote edit id:"697bdfe2808f7d245289392c" text:"New text" author:@Bob

Parameters:

  • id (required): The quote ID (found in the quote footer in the channel)
  • text (optional): The new quote text
  • author (optional): The new author (mention/select the user)

Notes:

  • You can only edit quotes that you added
  • At least one field (text or author) must be provided
  • The quote message in the channel will be updated automatically

Example Response:

✅ Quote updated successfully!

How It Works:

  1. User submits a quote using /quote add command
  2. Bot posts the quote as an embed in the configured quote channel
  3. Bot automatically adds 👍 and 👎 reactions to the message
  4. Users browse quotes by scrolling through the channel
  5. Users react with 👍 or 👎 to vote on quotes
  6. Users can edit their own quotes using /quote edit with the quote ID
  7. Bot automatically cleans up any unauthorized messages (every 5 minutes)
  8. An informational header post explains the channel usage (auto-recreated if deleted)

Security Features:

  • Strict Permissions: Channel is automatically configured so only the bot can post messages
  • Auto-Cleanup: Removes any non-bot messages every 5 minutes (configurable)
  • User Access: Users can view, read history, and add reactions only
  • Informational Header: Pinned post explains how the quote channel works

Example Response:

✅ Quote added successfully and posted to the quote channel!

Quote Display in Channel:

Each quote appears as an embed with:

  • The quote text
  • Author (mentioned user)
  • Who added it
  • Quote ID (in footer)
  • 👍 and 👎 reactions for voting

Advanced Configuration:

# Restrict who can add quotes (role IDs)
/config set key:quotes.add_roles value:"123456789,987654321"

# Set maximum quote length
/config set key:quotes.max_length value:500

# Set cooldown between adding quotes (seconds)
/config set key:quotes.cooldown value:120

# Set cleanup interval (minutes, default: 5)
/config set key:quotes.cleanup_interval value:10

# Disable header post (default: enabled)
/config set key:quotes.header_enabled value:false

# Disable header pinning (default: enabled)
/config set key:quotes.header_pin_enabled value:false

Use Cases:

  • Preserve memorable server moments
  • Create a community quote wall
  • Natural browsing via channel scroll
  • Engage through Discord reactions
  • Simple, streamlined quote management
  • Protected channel prevents spam/abuse

Setup Steps:

  1. Create a dedicated text channel for quotes (e.g., #quotes)
  2. Get the channel ID (right-click channel → Copy ID)
  3. Configure: /config set key:quotes.channel_id value:"CHANNEL_ID"
  4. Enable: /config set key:quotes.enabled value:true
  5. Reload: /config reload
  6. Bot will automatically set strict permissions on the channel

/notice

Description: Manage server notices in a protected bot-controlled channel. Perfect for server rules, game server info, bot feature help, and important announcements.

Configuration:

# Enable notices and set channel
/config set key:notices.enabled value:true
/config set key:notices.channel_id value:"YOUR_CHANNEL_ID"
/config reload

Subcommands:

/notice add

Add a new notice to the channel.

Parameters:

  • title (required) - Notice title (max 256 characters)
  • content (required) - Notice content (max 4000 characters)
  • category (required) - Category: General, Rules, Information, Help, or Game Servers
  • order (optional) - Display order (lower numbers appear first, default: 0)

Usage:

/notice add title:"Server Rules" content:"1. Be respectful\n2. No spam..." category:"Rules" order:1
/notice add title:"Minecraft Server" content:"IP: mc.example.com\nPort: 25565" category:"Game Servers" order:10
/notice add title:"Bot Commands Help" content:"Use /help to see available commands" category:"Help" order:20

/notice edit

Edit an existing notice.

Parameters:

  • id (required) - Notice ID (visible in notice channel footer)
  • title (optional) - New title
  • content (optional) - New content
  • category (optional) - New category
  • order (optional) - New display order

Usage:

/notice edit id:"abc123" title:"Updated Rules" content:"New rules text..."
/notice edit id:"abc123" order:5

/notice delete

Delete a notice.

Parameters:

  • id (required) - Notice ID (visible in notice channel footer)

Usage:

/notice delete id:"abc123"

Note: You can find notice IDs by viewing the notices in the channel - each notice shows its ID in the footer.

/notice sync

Recreate all notices in the channel (useful after cleanup or channel issues).

Usage:

/notice sync

How It Works:

  1. Admin creates notices using /notice add with title, content, and category
  2. Bot posts each notice as a rich embed in the configured notices channel
  3. Bot automatically creates a "Bot Features" notice listing enabled features
  4. Notices are displayed in order by category, then by custom order number
  5. Channel is read-only for regular users (only bot can post)
  6. Bot automatically removes any unauthorized messages every 5 minutes
  7. An informational header post explains the channel purpose (auto-recreated if deleted)
  8. Notices persist in database and survive bot restarts
  9. Notice IDs are visible in each notice's footer for editing/deletion

Security Features:

  • Strict Permissions: Channel is automatically configured so only the bot can post messages
  • Auto-Cleanup: Removes any non-bot messages every 5 minutes (configurable)
  • User Access: Users can view, read history, and add reactions only
  • Persistent: Notices stored in MongoDB, auto-repost on bot restart
  • Informational Header: Pinned post explains the channel's purpose

Notice Categories:

  • 📋 General - General server information
  • 📜 Rules - Server rules and guidelines
  • ℹ️ Information - Important server info
  • ❓ Help - Bot feature help and guides
  • 🎮 Game Servers - Game server connection information

Advanced Configuration:

# Set cleanup interval (minutes, default: 5)
/config set key:notices.cleanup_interval value:10

# Disable header post (default: enabled)
/config set key:notices.header_enabled value:false

# Disable header pinning (default: enabled)
/config set key:notices.header_pin_enabled value:false

Use Cases:

  • Post server rules that can't be deleted/modified by users
  • Share game server connection info that stays up-to-date
  • Provide bot feature help and usage guides
  • Important announcements that need to stay visible
  • Protected information channel that prevents spam

Setup Steps:

  1. Create a dedicated text channel for notices (e.g., #notices or #info)
  2. Get the channel ID (right-click channel → Copy ID)
  3. Configure: /config set key:notices.channel_id value:"CHANNEL_ID"
  4. Enable: /config set key:notices.enabled value:true
  5. Reload: /config reload
  6. Bot will automatically set strict permissions on the channel
  7. Add your first notice: /notice add title:"Welcome" content:"Welcome to our server!" category:"General"

Permissions:

  • Everyone can view quotes in the channel
  • Everyone can add reactions to quotes
  • Only bot can post messages (auto-configured)
  • Adding quotes via command respects quotes.add_roles configuration (empty = everyone can add)

/amikool

Description: Check if you have a specific role (for role verification).

Configuration:

/config set key:amikool.enabled value:true
/config set key:amikool.role.name value:"Kool Members"
/config reload

Usage:

/amikool

Example Responses:

✅ Yes, you are kool! You have the "Kool Members" role.

❌ Sorry, you don't have the "Kool Members" role.

Use Cases:

  • Fun role verification
  • Check membership status
  • Confirm permissions

🔧 Admin Commands

Commands that require Administrator permission in Discord.

/config

Description: Comprehensive configuration management for all bot settings.

Usage:

/config list                              # List all settings
/config get key:ping.enabled              # Get specific setting
/config set key:ping.enabled value:true   # Set a value
/config reset key:ping.enabled            # Reset to default
/config reload                            # Reload commands to Discord
/config export                            # Export config to YAML
/config import                            # Import config from YAML (attach file)

Subcommands:

/config list

Displays all configuration settings organized by category.

Example Response:

📋 Configuration Settings

Commands:
  ping.enabled: true
  quotes.enabled: false
  amikool.enabled: true

Voice Channels:
  voicechannels.enabled: true
  voicechannels.category.name: "Voice Channels"
  ...

/config get

Get the value of a specific setting.

Parameters:

  • key (required) - The setting key (e.g., ping.enabled)

Example:

/config get key:voicetracking.enabled
→ voicetracking.enabled: true

/config set

Update a configuration value.

Parameters:

  • key (required) - The setting key
  • value (required) - The new value

Examples:

# Enable a feature
/config set key:ping.enabled value:true

# Set a string value
/config set key:voicechannels.lobby.name value:"🟢 Join Here"

# Set a number
/config set key:quotes.cooldown value:120

# Set comma-separated list
/config set key:voicetracking.excluded_channels value:"123,456,789"

/config reset

Reset a setting to its default value.

Parameters:

  • key (required) - The setting key to reset

Example:

/config reset key:ping.enabled
→ ✅ Reset ping.enabled to default value: false

/config reload

Reload all commands to Discord API. Required after enabling/disabling commands.

Example:

/config reload
→ ✅ Commands reloaded successfully!

When to use:

  • After enabling/disabling any command
  • After changing command-related settings
  • If commands don't appear in Discord

/config export

Export current configuration to a YAML file.

Example:

/config export
→ 📄 config-2026-01-15.yaml (attached file)

Use Cases:

  • Backup configuration
  • Transfer settings between instances
  • Version control settings

/config import

Import configuration from a YAML file.

Usage:

/config import (attach YAML file)

Use Cases:

  • Restore from backup
  • Clone settings to new instance
  • Bulk configuration updates

/permissions

Description: Manage role-based command access control. This feature allows admins to restrict which commands can be used by specific Discord roles.

Command Name Format: Command names are used directly (e.g., quote, voicestats)

Key Features:

  • Multi-role support - Assign multiple roles to a single command
  • OR logic - Users need ANY of the assigned roles to execute the command
  • Admin bypass - Administrators always have access to all commands
  • Default open - Commands without permissions are accessible to everyone

Subcommands:

/permissions set

Set command permissions (replaces any existing permissions).

Note: In Discord's slash command UI, command and role are option names. Select quote for the command option and @Moderator, @VIP, etc. for the role options. The command:value notation in examples below represents the option structure, not literal text you type.

Usage:

/permissions set command:quote role:@Moderator
/permissions set command:quote role:@Moderator role:@VIP role:@Admin
/permissions set command:voicestats role:@Member

Parameters:

  • command (required) - Command name (autocomplete available)
  • role1 (required) - First role that can use this command
  • role2-5 (optional) - Additional roles (up to 5 total)

Example Response:

✅ Set permissions for `/quote` to: @Moderator, @VIP, @Admin

Use Cases:

  • Restrict powerful commands to trusted roles
  • Limit access to resource-intensive commands
  • Create role-specific command sets

/permissions add

Add roles to existing command permissions without removing current ones.

Usage:

/permissions add command:quote role:@Contributor
/permissions add command:quote role:@VIP role:@Premium

Parameters:

  • command (required) - Command name
  • role1 (required) - First role to add
  • role2-5 (optional) - Additional roles to add

Example Response:

✅ Added roles to `/quote`: @Contributor

Use Cases:

  • Incrementally expand access
  • Grant access to new roles without reconfiguring

/permissions remove

Remove specific roles from command permissions.

Usage:

/permissions remove command:quote role:@VIP
/permissions remove command:quote role:@Moderator role:@VIP

Parameters:

  • command (required) - Command name
  • role1 (required) - First role to remove
  • role2-5 (optional) - Additional roles to remove

Example Response:

✅ Removed roles from `/quote`: @VIP

Note: If all roles are removed, the permission entry is deleted automatically (command becomes accessible to everyone).

Use Cases:

  • Revoke access from specific roles
  • Clean up outdated permissions

/permissions clear

Remove all permissions for a command, or remove all commands from a role/user.

Usage:

# Clear permissions for a specific command
/permissions clear command:quote

# Clear all commands that have a specific role
/permissions clear role:@Moderator

# Clear all commands accessible via a user's roles
/permissions clear user:@username

Parameters:

  • command (optional) - Command name to clear permissions for
  • role (optional) - Remove this role from all commands
  • user (optional) - Remove all of this user's roles from all commands

Note: You must specify at least one parameter (command, role, or user).

Example Responses:

# Clearing a command
✅ Cleared all permissions for `/quote`. It is now accessible to everyone.

# Clearing a role from all commands
✅ Removed @Moderator from 3 command(s).

# Clearing a user's roles from all commands
✅ Removed @username's roles from 5 command(s).

Use Cases:

  • Reset command to default open access
  • Remove all restrictions for a command
  • Remove a role from all commands when role is being deleted
  • Clean up permissions when removing a user's access

/permissions list

View the permission matrix showing all commands with role restrictions, or filter by a specific command.

Usage:

# List all command permissions
/permissions list

# View permissions for a specific command
/permissions list command:quote

Parameters:

  • command (optional) - Filter by specific command name

Example Responses:

# Listing all permissions
Command Permissions

Commands with role restrictions:

/quote
@Moderator, @VIP

/voicestats
@Member

Commands not listed are accessible to everyone.
Admins bypass all restrictions.

# Listing a specific command
Permissions for /quote

Roles that can use this command:
@Moderator, @VIP

Admins bypass all restrictions.

# When command has no permissions
ℹ️ No permissions configured for `/quote`. It is accessible to everyone.

Use Cases:

  • Audit current permissions
  • Review access control setup
  • Documentation and planning
  • Check permissions for a specific command

/permissions view

Check what commands a specific user or role can access.

Usage:

/permissions view user:@username
/permissions view role:@Moderator

Parameters:

  • user (optional) - User to check
  • role (optional) - Role to check

Note: Must specify either user OR role, not both.

Example Responses:

# View user permissions
Permissions for username#1234
Can access 12 command(s):
`/ping`, `/help`, `/quote`, `/voicestats`, ...

# View role permissions
Permissions for Moderator
Can access 15 command(s):
`/ping`, `/help`, `/quote`, `/voicestats`, `/config`, ...

Use Cases:

  • Troubleshoot access issues
  • Verify role permissions
  • User support

Important Notes:

  • Always enabled - Permissions are a core feature, no configuration needed
  • Admin commands - Commands like /config, /vc, /dbtrunk automatically require Administrator permission
  • Permission inheritance - Users inherit permissions from all their roles (OR logic)
  • Default behavior - When no permissions are set, everyone has access (except admin-only commands)
  • Cache - Permissions are cached for performance; changes take effect immediately

Examples:

# Restrict quote command to moderators and VIPs
/permissions set command:quote role:@Moderator role:@VIP

# Add contributors to the allowed list
/permissions add command:quote role:@Contributor

# Check what @user123 can access
/permissions view user:@user123

# See all permission rules
/permissions list

# Make quote accessible to everyone again
/permissions clear command:quote

/reactrole

Description: Manage reaction-based roles. Allows users to self-assign roles by reacting to a message. Automatically creates Discord roles, categories, and channels with proper permissions.

Configuration:

# Enable reaction roles feature
/config set key:reactionroles.enabled value:true

# Set channel for reaction role messages
/config set key:reactionroles.message_channel_id value:"CHANNEL_ID"

# Reload commands
/config reload

Permissions: Requires Administrator permission

Subcommands:

/reactrole create

Create a new reaction role with associated Discord role, category, and channel.

Usage:

/reactrole create name:"Gaming" emoji:🎮
/reactrole create name:"Movie Night" emoji:🎬
/reactrole create name:"Music Lovers" emoji:🎵

Parameters:

  • name (required) - Name for the role, category, and channel
  • emoji (required) - Emoji users will react with to get the role

What it creates:

  1. A Discord role with the specified name
  2. A category channel (visible only to role members)
  3. A text channel inside the category
  4. A reaction message in the configured message channel

Example Response:

✅ Reaction Role Created
Successfully created reaction role Gaming!
Role: @Gaming
Category: #Gaming
Channel: #gaming
Users can now react to get this role!

Use Cases:

  • Create opt-in interest groups (gaming, movies, music)
  • Organize by game/activity with private channels
  • Event-based roles (tournament participants)
  • Community segmentation

/reactrole archive

Archive a reaction role. Disables reactions but keeps the role, category, and channels.

Usage:

/reactrole archive name:"Gaming"

Parameters:

  • name (required) - Name of the reaction role to archive

What it does:

  • Marks the role as archived
  • Removes the reaction message
  • Keeps the Discord role intact
  • Preserves the category and channels
  • Users can no longer get the role via reactions
  • Existing role members keep their access

Example Response:

📦 Reaction Role Archived
Successfully archived reaction role Gaming. Role and channels are preserved but reactions are disabled.
The reaction message has been removed

Use Cases:

  • Temporarily disable new sign-ups
  • Preserve channels for existing members
  • Archive inactive communities without deletion

/reactrole unarchive

Unarchive a reaction role to re-enable reactions.

Usage:

/reactrole unarchive name:"Gaming"

Parameters:

  • name (required) - Name of the reaction role to unarchive

What it does:

  • Marks the role as active again
  • Creates a new reaction message in the configured channel
  • Users can now react to get the role again
  • All existing channels and permissions remain unchanged

Example Response:

📤 Reaction Role Unarchived
Successfully unarchived reaction role Gaming. Users can now react to get this role again!

Use Cases:

  • Re-enable sign-ups after a temporary pause
  • Reactivate seasonal communities
  • Resume role assignment after maintenance

/reactrole delete

Completely delete a reaction role and all associated resources.

Usage:

/reactrole delete name:"Gaming"

Parameters:

  • name (required) - Name of the reaction role to delete

What it deletes:

  • The Discord role
  • The category and all channels inside it
  • The reaction message
  • The database configuration

Example Response:

🗑️ Reaction Role Deleted
Successfully deleted reaction role Gaming and all associated resources.
All resources have been permanently removed

Warning: This action is permanent and cannot be undone!

Use Cases:

  • Remove obsolete reaction roles
  • Clean up old communities
  • Free up Discord server space

/reactrole list

List all configured reaction roles.

Usage:

/reactrole list

Example Response:

📋 Reaction Roles
Found 3 reaction role(s)

🎮 Gaming
Status: ✅ Active
Role: @Gaming
Category: #Gaming
Channel: #gaming
Created: 1/15/2026

🎬 Movie Night
Status: 📦 Archived
Role: @Movie Night
Category: #Movie Night
Channel: #movie-night
Created: 1/10/2026

Use Cases:

  • View all reaction roles at a glance
  • Check which roles are active vs archived
  • Audit reaction role configuration

/reactrole status

Check detailed status of a specific reaction role.

Usage:

/reactrole status name:"Gaming"

Parameters:

  • name (required) - Name of the reaction role to check

Example Response:

🎮 Gaming
Status: ✅ Active
Role ID: 123456789
Category ID: 987654321
Channel ID: 111222333
Created: 1/15/2026, 3:30:00 PM
Last Updated: 1/15/2026, 3:30:00 PM
Message ID: 444555666

Use Cases:

  • Get IDs for advanced configuration
  • Debug permission issues
  • Verify role configuration

Setup Guide:

  1. Create a dedicated channel for reaction role messages (e.g., #get-roles)
  2. Get the channel ID (right-click channel → Copy ID)
  3. Configure the bot:
/config set key:reactionroles.enabled value:true
/config set key:reactionroles.message_channel_id value:"YOUR_CHANNEL_ID"
/config reload
  1. Create your first reaction role:
/reactrole create name:"Gaming" emoji:🎮
  1. Users can now react in the configured channel to get roles!

How it works:

  • Users react to the message with the specified emoji
  • Bot automatically assigns the role
  • Users gain access to the private category and channels
  • Removing the reaction removes the role and access
  • Category permissions are automatically maintained

Best Practices:

  • Use clear, descriptive names for roles
  • Choose easily recognizable emojis
  • Pin the reaction message in the channel
  • Organize reaction messages with category separators
  • Archive roles instead of deleting to preserve data and allow reactivation
  • Use unarchive to re-enable roles after maintenance or seasonal breaks
  • Use archived roles for seasonal/temporary communities

/vc

Description: Voice channel management, cleanup tools, and user customization.

Configuration:

/config set key:voicechannels.enabled value:true
/config reload

Subcommands:

/vc reload

Clean up empty dynamically created voice channels.

Usage:

/vc reload

What it does:

  • Removes empty user-created channels
  • Keeps channels with active users
  • Preserves the lobby channel

Example Response:

🧹 Cleaned up 3 empty voice channels

Use Cases:

  • Manual cleanup of abandoned channels
  • Server organization
  • Free up channel slots

/vc force-reload

Force cleanup of ALL unmanaged channels in the voice category.

Usage:

/vc force-reload

Warning: This is destructive! It removes ALL channels except the lobby, even if they have users.

What it does:

  • Removes ALL unmanaged channels in category
  • Keeps only the lobby channel
  • Does not remove manually created channels outside the category

Example Response:

⚠️ Force cleanup completed
Removed 8 channels from Voice Channels category

Use Cases:

  • Reset voice channel setup
  • Fix corrupted channel states
  • Emergency cleanup

Voice Channel Control Panel

Description: When you create a voice channel, an interactive control panel is automatically sent to the channel's text chat (if available). This provides quick access to customization options.

Configuration:

/config set key:voicechannels.controlpanel.enabled value:true  # Default: true
/config reload

Control Panel Buttons (Row 1):

  • ✏️ Rename - Opens a modal to rename your channel
  • 🔒 Make Private / 🌐 Make Public - Toggle privacy mode
  • 👥 Invite - Invite users to your private channel
  • 👑 Transfer - Shows how to transfer ownership

Control Panel Buttons (Row 2):

  • 🔴 Go Live / ⬜ Go Offline - Mark your channel as live (streaming disclaimer)
  • ⏳ Waiting Room / 🗑️ Remove Waiting Room - Toggle a companion waiting room channel

Features:

  • Only visible to channel owner
  • Updates dynamically when privacy mode, live status, or waiting room changes
  • Persists until channel is deleted
  • Posted every time a new channel is created

Requirements:

  • Server must have text channels associated with voice channels (community servers)
  • voicechannels.controlpanel.enabled must be true

Example Control Panel:

🎮 Voice Channel Controls

Manage your voice channel: **Your Channel Name**

Privacy: 🌐 Public
🔴 LIVE

[✏️ Rename] [🔒 Make Private] [👥 Invite] [👑 Transfer]
[⬜ Go Offline] [🗑️ Remove Waiting Room]

Only you can see and use these controls

Available Actions:

Rename Channel

Click the ✏️ Rename button to open a modal where you can enter a new name for your channel. No placeholder requirements - use any name you want!

Toggle Privacy

Click the 🔒 Make Private button to make your channel invite-only. Only you and invited users will be able to join. Click 🌐 Make Public to allow anyone to join again.

Invite Users

When your channel is private, click the 👥 Invite button to see instructions on inviting users. Select a user to grant them permission to join your channel. They'll receive a DM notification.

Transfer Ownership

Click the 👑 Transfer button to select a user from a dropdown menu. Only users currently in the channel will appear. Transfer ownership instantly.

Go Live

Click 🔴 Go Live to mark your channel as live. This will:

  • Add a 🔴 prefix to your channel name (auto-removed when you go offline)
  • Post a disclaimer in the channel text chat about platform Terms of Service
  • Notify anyone who joins the channel that it is live

Click ⬜ Go Offline to remove the live indicator.

Waiting Room

Click ⏳ Waiting Room to create a companion waiting room channel for your voice channel. Users can join the waiting room and you (the owner) will receive a notification in the channel with a 🚪 Let In button to move them into your channel.

  • Waiting room users cannot speak (mic muted)
  • When deleted or when you remove it, remaining users are automatically moved into your channel
  • Click 🗑️ Remove Waiting Room to delete it
  • Return to default settings
  • Fix misconfigured preferences
  • Start fresh with new preferences

/dbtrunk

Description: Database cleanup management for voice tracking data.

Configuration:

/config set key:voicetracking.cleanup.enabled value:true
/config reload

Subcommands:

/dbtrunk status

Show cleanup service status and statistics.

Usage:

/dbtrunk status

Example Response:

📊 Cleanup Service Status

Status: ✅ Running
Database: ✅ Connected
Schedule: Daily at 00:00

Last Cleanup: 2026-01-14 00:00:15
Sessions Removed: 1,247
Data Aggregated: 89 records

Retention Policy:
  Detailed Sessions: 30 days
  Monthly Summaries: 6 months
  Yearly Summaries: 1 year

Use Cases:

  • Check cleanup status
  • Verify database health
  • Monitor data retention

/dbtrunk run

Manually trigger database cleanup now.

Usage:

/dbtrunk run

What it does:

  • Removes old detailed sessions (older than retention period)
  • Removes old monthly summaries
  • Removes old yearly summaries
  • Preserves aggregated statistics

Example Response:

🧹 Cleanup completed successfully!

Detailed sessions removed: 1,247
Monthly summaries removed: 12
Yearly summaries removed: 1
Total space freed: 15.4 MB
Duration: 3.2 seconds

Use Cases:

  • Manual cleanup between scheduled runs
  • Free up database space immediately
  • Test cleanup configuration

/announce-vc-stats

Description: Manually trigger the weekly voice channel statistics announcement.

Configuration:

/config set key:voicetracking.enabled value:true
/config set key:voicetracking.announcements.enabled value:true
/config set key:voicetracking.announcements.channel value:"voice-stats"
/config reload

Usage:

/announce-vc-stats

What it does:

  • Posts top voice channel users to configured channel
  • Shows weekly statistics
  • Includes medals for top 3 users

Example Response (in configured channel):

📊 Weekly Voice Channel Stats

🥇 Alice: 45h 30m
🥈 Bob: 38h 15m
🥉 Charlie: 32h 20m
4. David: 28h 10m
5. Emma: 24h 45m
...

Total server voice time: 324h 15m
Active users: 47

Use Cases:

  • Post stats on-demand
  • Test announcement format
  • Share stats outside regular schedule

Automatic Announcements:

# Configure automatic weekly announcements
/config set key:voicetracking.announcements.schedule value:"0 16 * * 5"
# Every Friday at 4 PM

/announce

Description: Manage scheduled announcements to automatically send messages to channels on a schedule.

Configuration:

/config set key:announcements.enabled value:true
/config reload

Subcommands:

Create a scheduled announcement

/announce create cron:"0 9 * * *" channel:#general message:"Good morning!" placeholders:true

Parameters:

  • cron (required) - Cron schedule expression
    • 0 9 * * * - Daily at 9 AM
    • 0 12 * * 1 - Every Monday at noon
    • 0 0 * * 0 - Every Sunday at midnight
    • */30 * * * * - Every 30 minutes
  • channel (required) - Channel to send announcements to
  • message (required) - Message content
  • placeholders (optional) - Enable dynamic placeholders (default: false)
  • embed_title (optional) - Add an embed with title
  • embed_description (optional) - Embed description
  • embed_color (optional) - Embed color (hex code, e.g., #FF0000)

Supported Placeholders:

When placeholders is enabled, you can use:

  • {server_name} - Server name
  • {member_count} - Current member count
  • {date} - Current date
  • {time} - Current time
  • {day} - Day of week (e.g., Monday)
  • {month} - Month name (e.g., January)
  • {year} - Current year

Examples:

# Daily morning announcement
/announce create cron:"0 9 * * *" channel:#general \
  message:"Good morning, {server_name}! We have {member_count} members!" \
  placeholders:true

# Weekly event reminder with embed
/announce create cron:"0 18 * * 5" channel:#events \
  message:"Weekly game night starting soon!" \
  embed_title:"🎮 Game Night" \
  embed_description:"Join us for games this Friday evening!" \
  embed_color:#5865F2

# Monthly server stats
/announce create cron:"0 0 1 * *" channel:#announcements \
  message:"Monthly server update for {month} {year}" \
  placeholders:true

List scheduled announcements

/announce list

Shows all scheduled announcements with their:

  • ID
  • Status (enabled/disabled)
  • Channel
  • Cron schedule
  • Message preview

Delete an announcement

/announce delete id:123abc456def

Parameters:

  • id (required) - Announcement ID from /announce list

Example Response:

✅ Announcement Created

Announcement ID: `65f4a3b2c1d9e8f7a6b5c4d3`
Channel: #general
Schedule: `0 9 * * *`
Placeholders: Enabled
Message: Good morning, {server_name}!

Use Cases:

  • Daily/weekly automated announcements
  • Event reminders
  • Server updates
  • Community engagement messages
  • Rule reminders
  • Automated status updates

/poll

Description: Manage periodic polls for icebreaker discussions and community engagement. Posts Discord native polls on a schedule with questions from URL sources or database storage.

Configuration:

/config set key:polls.enabled value:true
/config set key:polls.default_duration_hours value:24    # Default poll duration
/config set key:polls.cooldown_days value:7              # Days before reusing poll
/config reload

Features:

  • 🗳️ Native Discord Polls - Uses Discord's built-in poll feature
  • 📅 Scheduled Posting - Automatic polls via cron schedules
  • 📥 URL Import - Fetch poll questions from YAML/JSON files
  • 🔄 Smart Rotation - Avoid repeating polls within cooldown period
  • 💾 Database Storage - Store and manage poll questions locally
  • 🔔 Role Pinging - Optional role mentions when posting
  • 🎲 Multi-Select - Support for multiple answer selections

Subcommands:

Create a poll schedule

/poll create channel:#daily-questions schedule:"0 12 * * *" duration:24 ping_role:@Everyone

Parameters:

  • channel (required) - Channel to post polls in
  • schedule (required) - Cron schedule expression
    • 0 12 * * * - Daily at noon
    • 0 9 * * 1 - Every Monday at 9 AM
    • 0 18 * * 5 - Every Friday at 6 PM
  • duration (optional) - Poll duration in hours (1-768, default: 24)
  • ping_role (optional) - Role to mention when posting polls

Example:

/poll create channel:#icebreakers schedule:"0 14 * * *" duration:48 ping_role:@Community

Import poll questions from URL

/poll import-url url:https://example.com/polls.yaml

Imports poll questions from a remote YAML or JSON file and saves them to the database.

Supported URL Formats:

YAML:

polls:
  - question: "What's your favorite programming language?"
    answers:
      - "JavaScript"
      - "Python"
      - "Go"
      - "Rust"
    multiselect: false
    tags: ["tech", "icebreaker"]
  
  - question: "Would you rather fight 100 duck-sized horses or 1 horse-sized duck?"
    answers:
      - "100 duck-sized horses"
      - "1 horse-sized duck"
      - "Neither, I'm out!"
    multiselect: false
    tags: ["funny", "absurd"]

JSON:

{
  "polls": [
    {
      "question": "What's your favorite season?",
      "answers": ["Spring", "Summer", "Fall", "Winter"],
      "multiselect": false,
      "tags": ["general"]
    }
  ]
}

Import Result:

📥 Import Results

Imported: 15
Skipped: 3
Errors: 0

Add a poll question manually

/poll add-item question:"What's your favorite food?" \
  answers:"Pizza, Tacos, Sushi, Burgers" \
  multiselect:false \
  tags:"food,icebreaker"

Parameters:

  • question (required) - Poll question (max 300 characters)
  • answers (required) - Comma-separated list of 2-10 answers
  • multiselect (optional) - Allow multiple selections (default: false)
  • tags (optional) - Comma-separated tags for categorization

List poll schedules

/poll list

Shows all configured poll schedules with:

  • Schedule ID
  • Status (enabled/disabled)
  • Target channel
  • Cron schedule
  • Poll duration
  • Ping role
  • Last run time

Example Response:

📊 Poll Schedules
Total: 2 schedule(s)

✅ 65f8a9b3c2d1e4f6a7b8c5d4
Channel: #daily-questions
Schedule: `0 12 * * *`
Duration: 24h
Ping Role: @Everyone
Last Run: 2/14/2026, 12:00:00 PM

✅ 65f8b2c4d3e5f7a8b9c6d5e4
Channel: #friday-fun
Schedule: `0 18 * * 5`
Duration: 48h
Ping Role: None
Last Run: Never

List poll questions

/poll list-items

Shows all stored poll questions with:

  • Poll ID
  • Status (enabled/disabled)
  • Question text (truncated)
  • Number of answers
  • Usage count
  • Last used date

Example Response:

📊 Poll Questions
Total: 25 question(s)

✅ 65f8c3d4e5f6a7b8c9d6e5f6
Q: What's your favorite programming language?
Answers: 4
Used: 3 times
Last: 2/10/2026, 2:00:00 PM

✅ 65f8d4e5f6a7b8c9d6e5f7a8
Q: Would you rather fight 100 duck-sized horses...
Answers: 3
Used: 1 times
Last: 1/28/2026, 12:00:00 PM

Delete a poll schedule

/poll delete id:65f8a9b3c2d1e4f6a7b8c5d4

Parameters:

  • id (required) - Schedule ID from /poll list

Delete a poll question

/poll delete-item id:65f8c3d4e5f6a7b8c9d6e5f6

Parameters:

  • id (required) - Poll item ID from /poll list-items

Test a poll schedule

/poll test schedule_id:65f8a9b3c2d1e4f6a7b8c5d4

Posts a poll immediately from the specified schedule for testing purposes.

Parameters:

  • schedule_id (required) - Schedule ID to test

Poll Selection Logic:

The bot intelligently selects polls to avoid repetition:

  1. Cooldown Period - Polls used within the cooldown period (default 7 days) are skipped
  2. Usage Count - Prioritizes less-used polls
  3. Randomization - Randomly selects from the top 20% least-used eligible polls
  4. Fallback - If all polls are within cooldown, uses the oldest-used poll

Example Workflow:

# 1. Enable the feature
/config set key:polls.enabled value:true
/config reload

# 2. Import poll questions from a URL
/poll import-url url:https://mysite.com/icebreaker-polls.yaml
→ Imported: 20 polls

# 3. Or add polls manually
/poll add-item question:"Cats or dogs?" answers:"Cats, Dogs, Both!, Neither" multiselect:false

# 4. Create a schedule
/poll create channel:#daily-questions schedule:"0 12 * * *" duration:24 ping_role:@Community

# 5. Test it immediately
/poll test schedule_id:65f8a9b3c2d1e4f6a7b8c5d4
→ ✅ Test poll posted successfully

# 6. View schedules
/poll list

# 7. View all poll questions
/poll list-items

Use Cases:

  • Daily icebreaker questions to spark conversations
  • Weekly "Would You Rather" discussions
  • Team building and getting-to-know-you activities
  • Community engagement and feedback polls
  • Fun hypothetical scenarios
  • Topic voting for events or discussions

Tips:

  • Start Small - Import 10-15 polls initially to test the rotation
  • Diversify - Mix serious and funny questions for variety
  • Tag Wisely - Use tags to organize polls by theme
  • Monitor Usage - Check /poll list-items to see which polls are popular
  • Update Regularly - Add new polls monthly to keep content fresh
  • Cooldown Balance - Adjust cooldown period based on pool size (more polls = longer cooldown works better)

Notes:

  • Announcements persist across bot restarts
  • All times use the server's timezone
  • Invalid cron expressions are rejected
  • Only administrators can manage announcements

/setup

Description: Interactive setup wizard to guide you through configuring KoolBot features. This is the recommended way to set up your server for the first time or configure new features.

Note: This command is always available to administrators as a core feature.

Usage:

/setup wizard                       # Start full setup wizard
/setup wizard feature:voicechannels # Configure specific feature

Subcommands:

/setup wizard [feature]

Start the interactive configuration wizard. Optionally specify a feature to configure directly.

Parameters:

  • feature (optional) - Choose a specific feature to configure:
    • voicechannels - Dynamic voice channel management
    • voicetracking - Voice activity tracking
    • quotes - Quote system
    • gamification - Achievement badges
    • logging - Core event logging

What it does:

The wizard provides a guided, step-by-step setup experience:

  1. Auto-detects existing resources - Finds existing categories, channels, and suggests using them
  2. Feature selection - Choose which features to enable (full wizard) or configure a specific feature
  3. Interactive configuration - Uses buttons, select menus, and modals to collect settings
  4. Validates input - Ensures channels exist and settings are valid
  5. Applies configuration - Automatically sets all related config keys
  6. Shows summary - Displays what was configured

Example Flow (Full Wizard):

Step 1: Feature Selection
┌────────────────────────────────┐
│ Select features to configure:  │
│ ☑ Voice Channels              │
│ ☑ Voice Tracking              │
│ ☐ Quote System                │
│ ☐ Achievements                │
│ ☐ Core Logging                │
│                                │
│ [Continue] [Cancel]            │
└────────────────────────────────┘

Step 2: Voice Channels Setup
┌────────────────────────────────┐
│ Voice Channels Configuration   │
│                                │
│ Category: Voice Channels       │
│ Lobby Name: 🟢 Lobby          │
│                                │
│ [Next] [Back] [Cancel]         │
└────────────────────────────────┘

Step 3: Confirmation
✅ Configuration Complete!
Voice Channels: Enabled
Voice Tracking: Enabled
Quote System: Disabled
Achievements: Disabled
Core Logging: Disabled

Run /config reload to apply changes.

Example: Specific Feature Setup

/setup wizard feature:voicetracking

This will:

  • Skip feature selection
  • Go directly to voice tracking configuration
  • Configure tracking settings, excluded channels, and admin roles
  • Enable the feature upon completion

Benefits over manual configuration

  • Beginner-friendly - No need to know exact config keys
  • Auto-detection - Suggests existing channels and categories
  • Guided workflow - Step-by-step with explanations
  • Error prevention - Validates all inputs before applying
  • Bulk configuration - Sets multiple related settings at once
  • Interactive - Uses Discord's UI components for better UX

When to use:

  • First-time setup - Easiest way to get started
  • New features - Enable and configure additional features
  • Troubleshooting - Reconfigure features that aren't working
  • Channel changes - Update channel references after reorganization

Use Cases:

  • Initial server setup
  • Onboarding new administrators
  • Enabling new features
  • Reconfiguring after channel reorganization
  • Troubleshooting misconfigured features

Notes:

  • Sessions expire after 15 minutes of inactivity
  • All interactions are ephemeral (only visible to you)
  • Requires Administrator permission
  • Changes take effect after /config reload
  • Wizard validates that channels exist before applying

/botstats

Description: View bot performance and usage statistics.

Usage:

/botstats

Example Response:

🤖 KoolBot Statistics

Uptime: 7 days, 14 hours, 23 minutes
Version: 1.0.0

Performance:
  Memory Usage: 245 MB
  CPU Usage: 3.2%
  Database: Connected
  Latency: 45ms

Activity:
  Guilds: 1
  Users Tracked: 347
  Voice Sessions Today: 89
  Commands Executed: 2,451

Most Used Commands:
  1. /voicestats - 1,526 times
  2. /ping - 421 times
  3. /quote - 315 times

Use Cases:

  • Monitor bot health
  • Check resource usage
  • View usage statistics
  • Troubleshoot performance issues

🔒 Permission Requirements

User Command Permissions

Command Permission Level Additional Requirements
/ping Everyone Command must be enabled
/voicestats Everyone Voice tracking enabled
/achievements Everyone Achievements enabled
/seen Everyone Voice tracking + seen enabled
/quote Everyone* Quotes enabled (*may be role-restricted)
/amikool Everyone Command enabled + role configured

Admin Command Permissions

All admin commands require Administrator permission in Discord.

Command Additional Requirements
/setup Administrator permission
/config Administrator permission
/permissions Administrator permission
/vc Administrator + voice channels enabled
/dbtrunk Administrator + cleanup enabled
/announce-vc-stats Administrator + tracking & announcements enabled
/botstats Administrator permission

Bot Permissions Required

The bot needs these Discord permissions to function:

Essential:

  • Read Messages/View Channels
  • Send Messages
  • Use Slash Commands

For Voice Features:

  • Manage Channels (create/delete voice channels)
  • Move Members (move users to created channels)
  • View Channel (see voice channels)
  • Connect (for voice state updates)

For Configuration:

  • Embed Links (for rich responses)
  • Attach Files (for config export/import)

📚 Quick Command Reference

User Commands Summary

/ping                               # Check bot status
/help [command]                     # Get help on commands
/voicestats top [period] [limit]   # Voice leaderboards
/voicestats user [user] [period]   # Voice channel stats
/achievements [user]               # View earned badges
/seen user:@User                   # Last seen info
/quote text:"..." author:"@User"   # Add quote to channel
/amikool                           # Role verification

Admin Commands Summary

# Initial Setup (Recommended)
/setup wizard                      # Interactive setup wizard
/setup wizard feature:...          # Configure specific feature

# Configuration
/config list                       # List all settings
/config get key:...                # Get setting value
/config set key:... value:...      # Set setting value
/config reset key:...              # Reset to default
/config reload                     # Reload commands
/config export                     # Export config
/config import                     # Import config

# Permissions
/permissions set command:... role:...   # Set command permissions
/permissions add command:... role:...   # Add role to command
/permissions remove command:... role:...# Remove role from command
/permissions list                       # View all permissions
/permissions list command:...           # View permissions for a command
/permissions view user:...              # Check user access
/permissions view role:...              # Check role access
/permissions clear command:...          # Clear command restrictions
/permissions clear role:...             # Remove role from all commands
/permissions clear user:...             # Remove user's roles from all commands

# Voice Management
/vc reload                         # Clean empty channels
/vc force-reload                   # Force cleanup all

# Database Management
/dbtrunk status                    # Cleanup status
/dbtrunk run                       # Run cleanup now

# Other Admin
/announce-vc-stats                 # Post stats now
/announce create                   # Schedule announcement
/announce list                     # View announcements
/announce delete                   # Remove announcement
/reactrole create                  # Create reaction role
/reactrole list                    # View reaction roles
/reactrole archive                 # Archive reaction role
/reactrole unarchive               # Unarchive reaction role
/reactrole delete                  # Delete reaction role
/reactrole status                  # Check role status
/botstats                          # Bot statistics

🎯 Common Workflows

Initial Bot Setup

Option 1: Using Setup Wizard (Recommended for beginners)

# Use the interactive setup wizard for guided configuration
/setup wizard

# Or configure specific features
/setup wizard feature:voicechannels
/setup wizard feature:voicetracking

The wizard will:

  • Auto-detect existing channels
  • Guide you through each feature
  • Validate all settings
  • Apply configuration automatically

Option 2: Manual Configuration (Advanced users)

# 1. Enable basic commands
/config set key:ping.enabled value:true
/config reload

# 2. Setup voice channels (use wizard)
/setup wizard feature:voicechannels
/config reload

# 3. Enable tracking
/config set key:voicetracking.enabled value:true
/config set key:voicetracking.seen.enabled value:true
/config reload

# 4. Enable weekly announcements
/config set key:voicetracking.announcements.enabled value:true
/config set key:voicetracking.announcements.channel value:"voice-stats"
/config reload

# 5. Enable achievements system
/config set key:achievements.enabled value:true
/config reload

# 6. Setup data cleanup
/config set key:voicetracking.cleanup.enabled value:true
/config reload

# 7. Setup quote channel (optional)
/config set key:quotes.enabled value:true
/config set key:quotes.channel_id value:"YOUR_QUOTE_CHANNEL_ID"
/config reload

Enable Quote Channel

# 1. Create a dedicated text channel in Discord (e.g., #quotes)
# 2. Right-click the channel → Copy ID
# 3. Configure the bot:
/config set key:quotes.enabled value:true
/config set key:quotes.channel_id value:"YOUR_CHANNEL_ID"
/config reload

# 4. Test it
/quote text:"Hello World!" author:"@YourName"

Enable Logging

# Create channels in Discord first, then:
/config set key:core.startup.enabled value:true
/config set key:core.startup.channel_id value:YOUR_CHANNEL_ID

/config set key:core.errors.enabled value:true
/config set key:core.errors.channel_id value:YOUR_CHANNEL_ID

/config set key:core.cleanup.enabled value:true
/config set key:core.cleanup.channel_id value:YOUR_CHANNEL_ID

Troubleshooting Commands Not Appearing

# 1. Check if command is enabled
/config get key:ping.enabled

# 2. Enable if needed
/config set key:ping.enabled value:true

# 3. MUST reload commands
/config reload

# 4. Wait a few minutes for Discord to sync

Backup and Restore Configuration

# Backup
/config export
# Save the file somewhere safe

# Restore
/config import
# Attach the saved YAML file

🚨 Troubleshooting

"Command not found" or command doesn't appear

Solutions:

  1. Check if enabled: /config get key:commandname.enabled
  2. Enable it: /config set key:commandname.enabled value:true
  3. Reload commands: /config reload (Required!)
  4. Wait 2-5 minutes for Discord to sync

"Permission denied" errors

Check:

  • Do you have Administrator permission?
  • Is the bot role high enough in the hierarchy?
  • Is the feature enabled in configuration?

Voice commands not working

Verify:

/config get key:voicechannels.enabled
/config get key:voicetracking.enabled

Both should be true. If not:

/config set key:voicechannels.enabled value:true
/config set key:voicetracking.enabled value:true
/config reload

Stats showing as empty

Possible causes:

  • Tracking recently enabled (give it time)
  • Channels are excluded
  • Users not in voice channels yet

Check excluded channels:

/config get key:voicetracking.excluded_channels

📖 Related Documentation

Need help? Check the troubleshooting guide or open an issue