ShadowGuard

ShadowGuard is a Discord bot for protecting and running a community. It provides anti-nuke controls, moderation, logging, leveling, tickets, reaction roles, giveaways, polls, custom commands, and optional music playback.

Quick start

You need Node.js 20+, a MongoDB database, and a Discord application with a bot user.

1. In the Discord Developer Portal, enable Server Members Intent, Message Content Intent, and Presence Intent for the bot.

2. Create a MongoDB database, then install and configure the project:

   git clone <repository-url>
   cd shadowguard
   npm install

   PowerShell:

   Copy-Item .env.example .env

   macOS or Linux:

   cp .env.example .env

3. Set these values in .env:

   DISCORD_TOKEN=your-bot-token
   CLIENT_ID=your-application-id
   MONGODB_URI=mongodb://127.0.0.1:27017/shadowguard

4. Register slash commands and start the bot:

   npm run deploy
   npm start

Use npm run dev during development. Set GUILD_ID in .env to deploy commands to one test server immediately; leave it blank for global deployment.

Configuration

Only DISCORD_TOKEN, CLIENT_ID, and MONGODB_URI are required. .env.example documents all optional settings.

• PREFIX changes the message-command prefix (default: ,).
• GUILD_ID scopes slash-command deployment to a test server.
• LAVALINK_HOST, LAVALINK_PORT, and LAVALINK_PASSWORD configure a music node you control.
• LASTFM_API_KEY, TRANSLATION_API_URL, and PREMIUM_WEBHOOK_SECRET enable their respective integrations.

Keep .env out of version control. Store production values in your hosting provider's secret manager and rotate any credential that may have been exposed.

Operating notes

• Start in a test server. Moderation and anti-nuke commands can change member, role, and channel access.
• Grant the bot only the permissions required for the features you enable.
• Music uses Lavalink. A self-hosted node is recommended for production; public-node fallback availability is not guaranteed.
• Run /help or ,help in Discord to discover available commands.

Development

npm test -- --runInBand
npm run lint
npm run format:check
npm audit

Project conventions and architecture: docs/DEVELOPMENT.md Contributing: CONTRIBUTING.md Security reporting: SECURITY.md

License

MIT