Admin Configuration

Administrative commands for configuring and managing Egg Shen Bot in your server.

Configuration Commands

Configuration is split across 5 top-level commands (kept under Discord's per-command size limit — each covers a related set of settings):

/eggshen-config <group> <subcommand> [parameters]                 — settings, stats, commands, notifications
/eggshen-config-watch-party <group> <subcommand> [parameters]     — watch-party, rate-limit
/eggshen-config-ai <group> <subcommand> [parameters]               — ai-images
/eggshen-config-moderation <group> <subcommand> [parameters]       — moderation
/eggshen-config-events <group> <subcommand> [parameters]           — event-requests

Required Permissions (all 5 commands):

• Administrator
• OR Manage Server permission

Configuration Groups

Settings Group

Basic bot settings and configuration.

View Current Configuration

/eggshen-config settings view

Shows all current server settings.

Toggle Services

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

Available Services:

• imdb - IMDb ratings and links
• letterboxd - Letterboxd links
• trakt - Trakt.tv ratings and links
• rottenTomatoes - Rotten Tomatoes scores
• justWatch - JustWatch streaming availability

Example:

/eggshen-config settings toggle service:letterboxd enabled:true

Set Custom Emojis

/eggshen-config settings emoji service:<service> emoji:[custom emoji]

Available Services:

• imdb
• letterboxd
• trakt
• rtCritics
• justWatch

Example:

/eggshen-config settings emoji service:imdb emoji:🎬

Set Region

/eggshen-config settings region code:<country-code>

Set the region for streaming availability (2-letter ISO code).

Example:

/eggshen-config settings region code:US

Max Search Results

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

Set maximum number of search results to display (1-50).

Example:

/eggshen-config settings max-results count:10

---

Max Timer Duration

/eggshen-config settings max-timer-duration minutes:<1-1440> unlimited:<true/false>

Set the fallback duration used only when a /timer start has no real duration at all — no duration was typed, no label matched anything, or "Skip" was chosen from the title-selection menu. This does not affect timers with a real duration (typed manually, adjusted, or auto-detected from a movie/TV runtime) — those always run for their full length regardless of this setting. See Watch Party → Timer Durations & the Expiry Warning.

• minutes (optional) — the fallback duration in minutes (default 360, i.e. 6 hours), used when no real duration exists.
• unlimited (optional) — when true, a timer with no real duration just runs forever instead of using the fallback (same as /timer autostop disable). When false (or omitted), the minutes fallback applies normally.

At least one of minutes or unlimited must be provided; both can be set together.

Examples:

/eggshen-config settings max-timer-duration minutes:480
/eggshen-config settings max-timer-duration unlimited:true
/eggshen-config settings max-timer-duration minutes:360 unlimited:false

---

Timer Ceiling

/eggshen-config settings timer-ceiling minutes:<1-1440> enabled:<true/false>

Optionally cap real timer durations too — a duration that was explicitly typed, set via /timer adjust, or auto-detected from a movie/TV runtime. Off by default: timers can be started at any duration unless a server turns this on. This is separate from Max Timer Duration above, which only affects timers with no real duration at all.

• minutes (optional) — the ceiling in minutes. A duration request over this is reduced to the ceiling, with the response noting it.
• enabled (optional) — when true, the ceiling is enforced. When false (or omitted while off), timers can be any duration.

At least one of minutes or enabled must be provided; both can be set together.

Examples:

/eggshen-config settings timer-ceiling minutes:600 enabled:true
/eggshen-config settings timer-ceiling enabled:false

---

Timer Control

/eggshen-config settings timer-control anyone-can-pause-stop:<true/false>

Choose whether any member can pause, resume, or stop a timer in this server, instead of only the person who started it plus administrators/moderators (the default). Useful for servers where the timer starter isn't always available to react. This does not extend to /timer adjust or /timer autostop — those always require the starter or an admin/mod, regardless of this setting, since they change the timer's configuration rather than just starting/stopping it.

• anyone-can-pause-stop (required) — true to let any member pause/resume/stop timers, false to restrict it to the starter/admins/mods (the default).

Example:

/eggshen-config settings timer-control anyone-can-pause-stop:true

---

Stats Group

Statistics tracking configuration.

Toggle Stats Tracking

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

Available Settings:

• enabled - All Stats Tracking (master switch)
• trackMovies - Track movie searches
• trackShows - Track TV show searches
• trackEpisodes - Track episode searches

Example:

/eggshen-config stats toggle setting:enabled enabled:true

Clear Statistics

/eggshen-config stats clear

Clears all statistics for the server. Cannot be undone.

---

Commands Group

Enable or disable specific commands for regular users.

Toggle Commands

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

Available Settings:

• enabled - All Commands (master switch)
• movie - Movie search command
• tv - TV show search command
• episode - Episode search command
• game - Video game search command
• boardgame - Board game search command
• book - Book search command
• soundtrack - Soundtrack search command
• survey - Poll/survey command
• bracket - Tournament bracket command

Note: Admins and moderators can always use commands regardless of these settings. /eggshen-help automatically reflects these settings — a disabled command (and its whole category, if every command in it is disabled) won't appear in the help list for regular users.

Example:

/eggshen-config commands toggle setting:movie enabled:true

---

Notifications Group

Configure bot restart and system notifications.

Toggle Restart Announcements

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

When enabled, bot announces when it restarts to configured channels.

Example:

/eggshen-config notifications toggle setting:restartAnnouncements enabled:false

---

Watch Party Group

Configure channels for watch party auto-detection.

Add Watch Party Channel

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

Adds a channel where the bot will auto-detect Discord scheduled events for timer labels.

Example:

/eggshen-config-watch-party watch-party add channel:#movie-night

Remove Watch Party Channel

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

Removes a channel from watch party auto-detection.

Example:

/eggshen-config-watch-party watch-party remove channel:#movie-night

List Watch Party Channels

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

Shows all configured watch party channels.

Watch Party Auto-Detect

/eggshen-config-watch-party watch-party auto-detect mode:<ask|full|off>

Controls how much /timer start does on its own with a watch-party channel's active scheduled event.

Mode	Behavior
ask (default)	Looks the title up. When it's identified confidently — a single match, an exact title match, or an episode range it can resolve — the duration is set and the timer just starts. When it's ambiguous, offers two buttons: ▶️ Start Now or 🔎 Look Up Title.
full	Same, but an ambiguous title goes straight to the full list of matches. ▶️ Start Timer Without Title Selection is always its first option.
off	Scheduled events are ignored entirely; /timer start needs a label.

The setting governs what the bot does unprompted. A label you type yourself with label:/movie:/tv: always gets the full search, in every mode.

ask exists because a watch party shouldn't begin with a quiz. Most of the time the lookup succeeds silently and you get a correct duration for free; when it can't, one click starts the timer anyway.

---

Rate Limit Group

Advanced rate limiting configuration.

Toggle Rate Limiting

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

Master switch for rate limiting system.

Example:

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

Global Rate Limits

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

Set global rate limits for all users.

Parameters:

• max-requests - Maximum requests (1-100)
• window-seconds - Time window in seconds (1-3600)

Example:

/eggshen-config-watch-party rate-limit global max-requests:10 window-seconds:60

Per-Command Rate Limits

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

Set custom rate limits for specific commands.

Available Commands:

• movie
• tv
• episode
• episode-list
• timer
• stats

Example:

/eggshen-config-watch-party rate-limit command command:movie max-requests:5 window-seconds:60

Set max-requests to 0 to remove custom limit for that command.

Moderator Bypass

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

Allow moderators to bypass rate limits.

Example:

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

Clear User Rate Limits

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

Manually clear rate limits for a specific user.

Example:

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

View Rate Limit Config

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

Shows current rate limiting configuration.

Guild-Wide Rate Limiting

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

Enable server-wide rate limiting (total commands across all users).

Parameters:

• enabled - Enable/disable guild-wide limits
• max-requests - Maximum total commands (default: 10, range: 1-100)
• window-seconds - Time window in seconds (default: 60, range: 10-600)

Example:

/eggshen-config-watch-party rate-limit guild-wide enabled:true max-requests:20 window-seconds:60

---

AI Images Group

Configure AI image generation limits and whitelist. Cost control is critical!

View AI Image Settings & Stats

/eggshen-config-ai ai-images view

Shows:

• Current settings (cooldown, limits, toggles)
• Server stats (usage today, cost, remaining quota)
• Your personal stats (usage, cooldown status)

Toggle AI Image Rate Limiting

/eggshen-config-ai ai-images toggle enabled:<true/false>

Enable or disable rate limiting for AI image generation.

⚠️ Warning: Disabling allows unlimited generations - costs can increase dramatically!

Example:

/eggshen-config-ai ai-images toggle enabled:true

Set User Cooldown

/eggshen-config-ai ai-images user-cooldown seconds:<60-3600>

Set time between AI image generations per user.

Default: 300 seconds (5 minutes)

Recommended values:

• 300 (5 min) - Default, balanced
• 600 (10 min) - Stricter, lower costs
• 60 (1 min) - Looser, higher costs

Example:

/eggshen-config-ai ai-images user-cooldown seconds:300

Set User Daily Limit

/eggshen-config-ai ai-images user-daily-limit limit:<1-100>

Maximum AI images per user per day.

Default: 10 images/day ($0.40/user/day max)

Examples:

• limit:5 - Very strict ($0.20/user/day max)
• limit:10 - Default ($0.40/user/day max)
• limit:25 - Generous ($1.00/user/day max)

Shows estimated monthly cost per user.

Example:

/eggshen-config-ai ai-images user-daily-limit limit:10

Set Server Daily Limit

/eggshen-config-ai ai-images guild-daily-limit limit:<1-500>

Maximum AI images per server per day.

Default: 50 images/day ($2/day = $60/month max)

Examples:

• limit:25 - Small server ($0.75/day = $22.50/month max)
• limit:50 - Default ($2/day = $60/month max)
• limit:100 - Large server ($4/day = $120/month max)

Shows estimated monthly cost.

Example:

/eggshen-config-ai ai-images guild-daily-limit limit:50

Toggle Admin Cooldown Bypass

/eggshen-config-ai ai-images admin-bypass enabled:<true/false>

Allow admins/moderators to bypass cooldown (they always respect daily limits).

Default: Enabled

Example:

/eggshen-config-ai ai-images admin-bypass enabled:true

Add User to Unlimited Whitelist

/eggshen-config-ai ai-images whitelist-add user:<@user>

Grant unlimited AI image generation to a specific user.

Use cases:

• Bot contributors helping with costs
• Premium/donor users
• Server boosters
• Testing accounts

Whitelisted users bypass ALL limits (cooldown + daily limits).

Example:

/eggshen-config-ai ai-images whitelist-add user:@JohnDoe

Remove User from Whitelist

/eggshen-config-ai ai-images whitelist-remove user:<@user>

Remove unlimited access - user returns to normal rate limits.

Example:

/eggshen-config-ai ai-images whitelist-remove user:@JohnDoe

View Whitelist

/eggshen-config-ai ai-images whitelist-list

Shows all users with unlimited AI image generation access.

Reset User Usage

/eggshen-config-ai ai-images reset-user user:<@user>

Reset a user's daily usage and cooldown.

Use cases:

• User hit limit due to testing
• Reward for event participation
• Resolve technical issues

Example:

/eggshen-config-ai ai-images reset-user user:@JohnDoe

Reset Server Usage

/eggshen-config-ai ai-images reset-guild

Reset the entire server's daily usage (user limits still apply).

Use cases:

• Special events
• Server milestones
• Testing periods

Example:

/eggshen-config-ai ai-images reset-guild

💡 See AI Image Generation for complete documentation on the /image and /bracket image commands, cost management strategies, and best practices.

---

Event Requests Group

Configure event request system for watch parties. See Event Requests Setup for complete documentation.

TIP

Event requests allow community members to submit watch party events via a web form. Moderators approve or deny requests in Discord, and approved events are automatically created as Discord Scheduled Events.

View Current Configuration

/eggshen-config-events event-requests view

Shows current event request settings including:

• Enabled status
• Server name displayed on form
• Moderation channel for approval queue
• Website URL where form is hosted
• Discord invite link (optional)
• Voice channel requests allowed/disallowed

Enable/Disable Event Requests

/eggshen-config-events event-requests toggle enabled:true
/eggshen-config-events event-requests toggle enabled:false

Turn event requests on or off for your server.

Set Moderation Channel

/eggshen-config-events event-requests moderation-channel channel:#mod-queue

Set where event request approval messages appear. Moderators will see:

• Request details (title, description, channels, date/time)
• Submitter information
• Approval buttons (varies based on voice channel request)

Set Server Name

/eggshen-config-events event-requests server-name name:My Cool Server

Customize the server name shown on the event request form.

Set Invite Link (Optional)

/eggshen-config-events event-requests invite-url url:https://discord.gg/yourserver

Discord invite link displayed on the form. Leave empty to hide.

Set Website URL

/eggshen-config-events event-requests website-url url:https://yourdomain.com

The URL where your event request form is hosted.

WARNING

After setting the website URL, you must also copy public/config.example.js to public/config.js on your web server and set GUILD_ID there. See the Event Requests Setup Guide for deployment instructions.

Allow/Disallow Voice Requests

/eggshen-config-events event-requests allow-voice-requests allow:true
/eggshen-config-events event-requests allow-voice-requests allow:false

Control whether users can request voice/stage channels for events.

When disabled:

• Voice channel checkbox hidden on form
• All events are text-channel only
• Simplifies form for servers that don't use voice for watch parties

When enabled (default):

• Checkbox appears on form: "Include voice/stage channel for this event"
• Users can optionally add voice channel to requests
• Moderators get granular approval options

Moderator Approval Options:

• Voice requested: ✅ Approve Both | 💬 Text Only | ❌ Deny
• Text-only request: ✅ Approve & Create Event | ❌ Deny

Announce Approve/Deny Decisions

/eggshen-config-events event-requests announce-decisions enabled:true
/eggshen-config-events event-requests announce-decisions enabled:false

Control whether approving or denying a request posts a new message to the moderation channel announcing the outcome, in addition to updating the original request's embed in place.

When enabled (default):

• A fresh message is posted announcing who approved/denied the request
• Approved: includes a link to the newly created event
• Denied: includes the reason, if one was given
• Shows up as new channel activity, so the whole moderation team sees it — not just whoever clicked

When disabled:

• Only the original request message updates (title, color, buttons)
• No separate announcement is posted

Allow User Channel Selection (Simple vs Advanced Mode)

/eggshen-config-events event-requests allow-user-channel-selection allow:false
/eggshen-config-events event-requests allow-user-channel-selection allow:true

Control whether users select channels in the event request form.

Simple Mode (default - allow:false):

• Users submit basic event details only: title, description, start/end time
• Form hides Location and Voice Channel selectors
• Message to users: "Moderators will select the channels when approving your event"
• Moderators assign channels during approval process
• Best for: New communities, servers with dedicated event coordinators, reducing decision fatigue

Advanced Mode (allow:true):

• Users select specific text/voice channels from whitelists (see below)
• Form shows Location field (required) and optional Voice Channel checkbox
• Users have full control over channel selection
• Form filters channels based on allowed lists configured by admins
• Best for: Experienced communities, power users, community-driven events

Default Behavior

Event requests default to Simple Mode. Users submit event ideas and moderators handle channel logistics during approval. Enable Advanced Mode only when users should control channel selection.

Whitelist Allowed Text Channels

/eggshen-config-events event-requests set-allowed-text-channels channel-ids:"123,456,789"
/eggshen-config-events event-requests set-allowed-text-channels channel-ids:"all"

Control which text channels appear in the event request form dropdown.

Channel IDs Parameter:

• Comma-separated list: "1234567890,9876543210,1111222233" - Only these channels
• "all" keyword: "all" - Allow all text channels (default)
• Empty string: "" - Also allows all channels

How It Works:

• Users only see whitelisted channels in the "Location" dropdown
• Empty list (default) = all channels available
• Populated list = only those specific channel IDs appear

Use Cases:

• Limit to dedicated watch party channels: "123,456"
• Exclude admin/announcement channels
• Simplify selection for users with many channels
• Reset to all channels: "all"

Example:

/eggshen-config-events event-requests set-allowed-text-channels channel-ids:"1234567890,9876543210"

Getting Channel IDs

Right-click a channel in Discord → Copy Channel ID (requires Developer Mode enabled in Discord Settings)

Whitelist Allowed Voice Channels

/eggshen-config-events event-requests set-allowed-voice-channels channel-ids:"123,456,789"
/eggshen-config-events event-requests set-allowed-voice-channels channel-ids:"all"

Control which voice/stage channels appear in the event request form dropdown.

Channel IDs Parameter:

• Comma-separated list: "1234567890,9876543210" - Only these channels
• "all" keyword: "all" - Allow all voice/stage channels (default)
• Empty string: "" - Also allows all channels

How It Works:

• Users only see whitelisted channels in the "Voice Channel" dropdown
• Empty list (default) = all voice/stage channels available
• Populated list = only those specific channel IDs appear

Use Cases:

• Limit to dedicated watch party voice channels
• Exclude private or admin voice channels
• Simplify selection when server has many voice channels
• Reset to all channels: "all"

Example:

/eggshen-config-events event-requests set-allowed-voice-channels channel-ids:"1234567890"

Independent Controls

Text and voice channel whitelists are independent. You can:

• Allow all text channels but limit voice channels
• Allow all voice channels but limit text channels
• Limit both to specific channels
• Allow all of both (default)

Get Configuration Summary

/eggshen-config-events event-requests get-link

Shows your form URL and reminds you to configure GUILD_ID in your web deployment.

💡 See Event Requests Setup for complete documentation including OAuth configuration, web server setup, and testing guide.

---

Other Admin Commands

View Statistics

/eggshen-stats filter:[time-period]

View bot usage statistics (admin/moderator only).

Filters:

• all-time - All time statistics
• month - Last 30 days
• week - Last 7 days
• today - Last 24 hours

Example:

/eggshen-stats filter:week

View Logs

/eggshen-logs stats
/eggshen-logs errors count:[1-50]
/eggshen-logs category:[category] count:[1-50]

View bot logs and diagnostics (admin only).

Subcommands:

• stats - View log file statistics
• errors - View recent errors (EMERGENCY to ERROR levels)
• category - View logs by category

Categories:

• system - Bot startup, shutdown, errors
• command - Command execution logs
• button - Button interaction logs
• scheduler - Tournament auto-close events
• bracket - Tournament operations
• api - External API calls
• performance - Slow operation tracking

Examples:

/eggshen-logs stats
/eggshen-logs errors count:20
/eggshen-logs category:command count:10

💡 See Logging System for complete documentation on log levels, file formats, rotation, and troubleshooting.

Restart Bot

/eggshen-restart

Restart the bot (admin/moderator only). Use with caution.

Help Command

/eggshen-help

Get help with bot commands and features.