Configuration

Configure Egg Shen Bot for your Discord server with powerful administrative controls and customization options.

Server Configuration

Use the /eggshen-config command to configure bot behavior for your server. Only administrators can modify these settings.

Basic Settings

View Current Configuration

See all current settings for your server:

/eggshen-config settings view

Toggle Services

Enable or disable rating/streaming services in search results:

/eggshen-config settings toggle service:<service> enabled:<true/false>

Available services: IMDb, Letterboxd, Trakt, Rotten Tomatoes, JustWatch

Custom Service Emojis

Set custom emojis for rating services:

/eggshen-config settings emoji service:<service> emoji:<emoji>

Leave emoji blank to clear and use default.

Streaming Region

Set the region for streaming availability results:

/eggshen-config settings region code:<XX>

Uses ISO 3166-1 country codes (US, CA, GB, AU, etc.)

Maximum Search Results

Control how many results appear in selection menus (1-50):

/eggshen-config settings max-results count:<number>

Statistics Tracking

Toggle Statistics

Enable or disable statistics tracking:

/eggshen-config stats toggle setting:<setting> enabled:<true/false>

Options:

• All Stats Tracking - Master switch for all statistics
• Movie Tracking - Track movie searches only
• TV Show Tracking - Track TV show searches only
• Episode Tracking - Track episode searches only

Clear Statistics

Remove all collected statistics for your server:

/eggshen-config stats clear

⚠️ Warning: This action cannot be undone.

Command Permissions

Control whether regular users can access specific commands:

/eggshen-config commands toggle setting:<setting> enabled:<true/false>

Options:

• All Commands - Master switch disables/enables everything
• Movie Command - Toggle /movie access
• TV Command - Toggle /tv access
• Episode Command - Toggle /episode access

Note: Administrators and moderators can always use commands.

Notifications

Control bot notification behavior:

/eggshen-config notifications toggle setting:<setting> enabled:<true/false>

Currently supports:

• Restart Announcements - Notify channels when bot restarts and restores timers

Watch Party Configuration

Configure channels where timer auto-detection works. When a timer starts in these channels, the bot automatically detects active Discord events and uses the event name as the timer label.

Add Watch Party Channel

/eggshen-config-watch-party watch-party add channel:<#channel>

Remove Watch Party Channel

/eggshen-config-watch-party watch-party remove channel:<#channel>

List Configured Channels

/eggshen-config-watch-party watch-party list

AI Announcement Text

/announce can write your announcement for you, drawing on the title's real plot and streaming availability. It's optional, and enabled by default.

Turning it off doesn't limit /announce — supplying your own message always posts exactly what you wrote, whatever this is set to. It only controls what happens when you don't write one: with AI on, the bot writes it; with AI off, it uses a plain template.

Enable or Disable

/eggshen-config-ai ai-text feature-toggle enabled:false

Check the Current State

/eggshen-config-ai ai-text view

This reports two separate things, because both have to be true for AI text to run:

• This server — the setting above, which a server admin controls
• API key on this bot — whether whoever hosts the bot has set OPENAI_API_KEY

If you're self-hosting and the key isn't configured, announcements fall back to the plain template no matter what this is set to. See the API Keys Guide for how to get one.

AI Answers for /eggshen-ask

/eggshen-ask can write its answers with AI, from the docs and the bot's real commands. It has its own switch, separate from announcement text, and is enabled by default. With it off, /eggshen-ask shows the best-matching section of the docs as written.

/eggshen-config-ai ai-ask feature-toggle enabled:false
/eggshen-config-ai ai-ask view

Like announcement text, it also needs the bot to have an OpenAI API key; view shows both.

Separate from AI images

This is independent of /eggshen-config-ai ai-images feature-toggle. Text costs a tiny fraction of what an image does, so you can run one without the other.

Rate Limiting

Protect your server from spam and abuse with comprehensive rate limiting.

Enable/Disable Rate Limiting

/eggshen-config-watch-party rate-limit toggle enabled:<true/false>

Global Rate Limits

Set default rate limits for all commands:

/eggshen-config-watch-party rate-limit global max-requests:<number> window-seconds:<number>

Example: Allow 10 requests per 60 seconds

Command-Specific Limits

Set custom rate limits for specific commands:

/eggshen-config-watch-party rate-limit command command:<command> max-requests:<number> window-seconds:<number>

Available commands: movie, tv, episode, episode-list, timer, stats

Set max-requests to 0 to remove custom limit and use global default.

Guild-Wide Rate Limiting

Prevent multi-account flooding by limiting total server activity:

/eggshen-config-watch-party rate-limit guild-wide enabled:<true/false> max-requests:<number> window-seconds:<number>

Pattern Detection

Detect suspicious coordinated activity patterns:

/eggshen-config-watch-party rate-limit pattern-detection enabled:<true/false> min-users:<number>

Flags suspicious activity when multiple users exhibit similar spam patterns.

Moderator Bypass

Allow moderators to bypass rate limits:

/eggshen-config-watch-party rate-limit bypass enabled:<true/false>

View Rate Limits

See current rate limit configuration:

/eggshen-config-watch-party rate-limit view

Clear User Rate Limits

Admin override to clear rate limits for a specific user:

/eggshen-config-watch-party rate-limit clear user:<@user>

View Suspicious Activity

See recent patterns flagged by pattern detection:

/eggshen-config-watch-party rate-limit suspicious-activity

View Abuse Log

Track individual user violations:

/eggshen-config-watch-party rate-limit abuse-log

Moderation Features

Advanced moderation tools for managing user behavior.

Enable/Disable Moderation

/eggshen-config-moderation moderation toggle enabled:<true/false>

User Cooldowns

Temporarily prevent a user from using bot commands:

/eggshen-config-moderation moderation user-cooldown user:<@user> duration:<minutes> reason:<text>

Maximum duration: 10,080 minutes (1 week)

Remove Cooldown

/eggshen-config-moderation moderation user-cooldown-remove user:<@user>

List Active Cooldowns

/eggshen-config-moderation moderation user-cooldown-list

Whitelist Mode

When enabled, only whitelisted roles and users can use commands:

/eggshen-config-moderation moderation whitelist-toggle enabled:<true/false>

Manage Whitelist

Add/remove roles:

/eggshen-config-moderation moderation whitelist-add-role role:<@role>
/eggshen-config-moderation moderation whitelist-remove-role role:<@role>

Add/remove users:

/eggshen-config-moderation moderation whitelist-add-user user:<@user>
/eggshen-config-moderation moderation whitelist-remove-user user:<@user>

View whitelist:

/eggshen-config-moderation moderation whitelist-list

Auto-Ban Threshold

Track users who break rate limits too often. Someone who goes over the threshold is warned in their reply, and shows up in /eggshen-config-moderation moderation auto-ban-list. Nobody is banned automatically, and moderators aren't sent a message; check the list.

/eggshen-config-moderation moderation auto-ban-toggle enabled:<true/false>

Configuration Best Practices

Small Servers (< 100 members)

• Moderate rate limits (10 requests/60 seconds)
• Disable pattern detection (low user count may cause false positives)
• Keep whitelist mode off unless needed

Medium Servers (100-1,000 members)

• Stricter rate limits (5 requests/60 seconds)
• Enable pattern detection with min-users: 3
• Consider guild-wide rate limits
• Enable restart announcements for active watch party channels

Large Servers (1,000+ members)

• Maximum protection (3 requests/60 seconds)
• Enable all rate limiting features
• Pattern detection with min-users: 5+
• Guild-wide limits required
• Whitelist mode for emergency spam situations

Environment Variables

Bot administrators should configure these environment variables in .env:

Required

• DISCORD_TOKEN - Your Discord bot token
• DISCORD_CLIENT_ID - Your Discord application client ID
• TMDB_API_KEY - The Movie Database API key (required for movie/TV data)

Optional

• OMDB_API_KEY - Open Movie Database API key (additional metadata)
• TRAKT_CLIENT_ID - Trakt.tv API key (trending data)
• RAWG_API_KEY - RAWG API key (game database access)
• BGG_CLIENT_ID - BoardGameGeek API key (board game data)
• GUILD_ID - For testing: Deploy commands instantly to one server

See the API Keys Guide and Installation Guide for detailed setup instructions.

Troubleshooting

Commands Not Working

• Verify bot has proper permissions in the channel
• Check if rate limiting is blocking commands with /eggshen-config-watch-party rate-limit view
• Ensure command isn't disabled with /eggshen-config commands toggle
• Verify you're not in a user cooldown with /eggshen-config-moderation moderation user-cooldown-list

Rate Limiting Too Strict

• View current limits: /eggshen-config-watch-party rate-limit view
• Adjust global or command-specific limits
• Enable moderator bypass for staff
• Use /eggshen-config-watch-party rate-limit clear user:@user to help specific users

Timer Auto-Detection Not Working

• Verify channel is added to watch-party list: /eggshen-config-watch-party watch-party list
• Ensure you have an ACTIVE Discord event in the server
• Check that the event location field mentions the channel (by name, ID, or mention)
• Event must be in "Active" status (not Scheduled or Completed)

Missing Features

• Ensure all required API keys are configured in .env
• Verify bot permissions include necessary intents
• Commands requiring optional APIs won't appear if keys aren't configured