Installation

Complete installation guide for Egg Shen Bot. Follow these steps to set up the bot from scratch, including creating your Discord application, obtaining API keys, and getting the bot online.

Minimum Viable Setup

Everything on this page gets you a working bot on one Discord server. That's it — the steps below don't require a domain, a web server, or any of the multi-server complexity described elsewhere in these docs.

The Event Requests feature (a public web form where members request watch-party events) is entirely optional, and its setup guide covers running that form across multiple Discord communities from one bot process (e.g. a dev server and a production server, or several communities you moderate) — skip that guide entirely unless you specifically want the web-form feature.

Quick FAQ

Q: What's the difference between required and optional APIs?
A: TMDB is required for all movie/TV features. Optional APIs enable additional commands - without them, those specific commands won't appear in Discord.

Q: How do I know if my API keys are working?
A: The bot logs will show successful connections on startup. Commands requiring missing APIs simply won't register.

Q: Can I add API keys later?
A: Yes! Just update your .env file, redeploy commands with node src/deploy-commands.js, and restart the bot.

Q: Why do I need to run deploy-commands.js?
A: This registers your slash commands with Discord. Run it once initially and whenever you change API keys or update commands.

Q: What if I don't want certain features?
A: Simply don't configure those API keys. Commands requiring them won't be registered.

---

Requirements

• Node.js v20.x or higher
• npm (comes with Node.js)
• Discord Bot Token from Discord Developer Portal
• TMDB API Key from TMDB (required for all movie/TV features)

API Keys

Required APIs

Service	Purpose	Get Key
TMDB	Movie and TV show data	Get API Key

Optional APIs

These APIs enable additional features. Commands requiring them will not be registered if their API keys aren't configured.

Service	Purpose	Enables Commands	Get Key
OMDB	IMDb & RT ratings	Enhanced ratings display	Get API Key
Trakt	Community ratings	Enhanced ratings display	Get API Key
RAWG	Video game data	/game, /random game, /similar (games)	Get API Key
BoardGameGeek	Board game data	/boardgame, /random boardgame, /similar (board games)	Get API Key

Note: Commands requiring optional APIs won't appear in Discord at all if their keys aren't configured. This prevents users from seeing unavailable features.

Step-by-Step Installation

1. Create Discord Bot

1. Go to Discord Developer Portal
2. Click "New Application"
3. Name your bot and accept the Terms of Service
4. Go to "Bot" section
5. Click "Add Bot"
6. Privileged Gateway Intents: leave these unchecked — the bot doesn't use Server Members Intent or Message Content Intent (it only reads slash-command interactions and reactions, both non-privileged)
7. Copy your bot token (you'll need this later)
8. Click "OAuth2" → "URL Generator" in the left sidebar
9. Under SCOPES, check bot and applications.commands
10. Under BOT PERMISSIONS, check: View Channels, Send Messages, Embed Links, Attach Files, Manage Events, Manage Messages
11. Copy the generated URL, open it in your browser, select your server, and click Authorize

2. Get API Keys

Follow the links in the API Keys table above to obtain your keys. At minimum, you need:

• Discord Bot Token (from Discord Developer Portal)
• TMDB API Key (required for core functionality)

Optional APIs can be added later to enable additional features.

3. Clone and Install

# Clone repository
git clone https://github.com/r3volution11/Egg-Shen-Bot.git
cd Egg-Shen-Bot

# Install dependencies
npm install

4. Configure Bot

This project is configured entirely through a .env file in the project root — there's no separate config.json to copy or edit.

# Copy the example environment file
cp .env.example .env

# Edit with your API keys
nano .env  # or use your preferred editor

Required .env variables:

# Discord Configuration (Required)
DISCORD_TOKEN=your_discord_bot_token_here
DISCORD_CLIENT_ID=your_discord_client_id_here

# TMDB API (Required for core functionality)
TMDB_API_KEY=your_tmdb_api_key_here

# Optional APIs (enable specific features)
OMDB_API_KEY=your_omdb_api_key_here
TRAKT_CLIENT_ID=your_trakt_client_id_here
RAWG_API_KEY=your_rawg_api_key_here
BGG_CLIENT_ID=your_bgg_client_id_here

# Optional: Guild ID for testing (leave empty for global commands)
GUILD_ID=

See .env.example in the repo for the complete list of variables, including ones only needed by optional features (AI images, the event-request web form, Spotify soundtrack links, etc.).

What happens if optional APIs aren't configured:

• /game and /boardgame commands won't be registered at all - they won't appear in Discord
• /random game/boardgame subcommands will show error messages when used
• /similar will skip unavailable media types (games/board games) in searches
• Rating displays will have fewer sources without OMDB/Trakt

5. Invite the Bot to Your Server

If you haven't already (via the URL Generator step above), open the invite URL in your browser and select your server.

6. Register Commands

npm run deploy-commands

This registers all slash commands with Discord. You should see:

Successfully registered application commands.

7. Start Bot

npm start

You should see:

✓ Logged in as YourBot#1234

Verification

Test that everything works:

/movie title:The Matrix
/eggshen-help

If commands appear and work, installation is complete!

Troubleshooting

Commands not appearing

• Wait 1 hour after running deploy-commands (Discord cache)
• Try in a private message with the bot
• Verify bot permissions in server settings

Bot immediately crashes

• Check DISCORD_TOKEN in .env
• Check Node.js version: node --version

API errors

• Verify TMDB API key is correct
• Make sure you activated the OMDB key via email
• Check rate limits on API providers

Permission errors

• The bot's server role needs: View Channel, Send Messages, Embed Links, Attach Files, Manage Events, Manage Messages — see the invite-link step in "Create Discord Bot" above
• Check role hierarchy (bot role should be high enough)
• A channel-specific permission override (common in mod-only channels) can block the bot even when its server-wide role looks correct — check that channel's own permission settings too

Production Deployment

For production servers, consider:

• Using PM2 for process management
• Setting up log rotation
• Configuring automatic restarts
• Monitoring system resources

See Configuration Guide for production setup.

Next Steps

• Configure server settings
• Set up rate limiting
• Enable moderation tools
• Configure statistics tracking