02. Getting Started

Getting Started with UtilsBot+

This guide will help you set up and run UtilsBot+ from scratch. Follow these steps to get your bot up and running quickly.

Prerequisites

Before you begin, ensure you have:

• Python 3.11+ (Python 3.12 recommended)
• Discord Bot Token (Create one here)
• Google Gemini API Key (Free tier here)
• Git for cloning the repository

Step 1: Create a Discord Bot

1. Go to the Discord Developer Portal
2. Click "New Application" and give it a name
3. Go to the "Bot" section
4. Click "Add Bot"
5. Copy the Bot Token (you'll need this later)
6. Under "Privileged Gateway Intents", enable:
   • Message Content Intent (if needed)
   • Server Members Intent (optional)

Step 2: Get Your Discord User ID

1. Enable Developer Mode in Discord (User Settings → Advanced → Developer Mode)
2. Right-click on your profile and select "Copy User ID"
3. Save this ID - you'll need it for the DEV_IDS configuration

Step 3: Get Google Gemini API Key

1. Visit Google AI Studio
2. Sign in with your Google account
3. Click "Create API Key"
4. Copy the generated API key

Note: The free tier provides 15 requests per minute with up to 1M input tokens - perfect for most use cases!

Step 4: Clone and Setup

# Clone the repository
git clone https://github.com/ad1107/utils-bot-plus.git
cd utils-bot-plus

# Run the automated setup script
chmod +x setup.sh
./setup.sh

# Install dependencies
pip install -r requirements.txt

The setup script will:

• Create necessary directories (data/, logs/)
• Generate a .env file from the template
• Create a secure SECRET_KEY
• Initialize the database structure

Step 5: Configure Environment Variables

Edit the .env file that was created:

# REQUIRED - Get from Discord Developer Portal
BOT_TOKEN=your_discord_bot_token_here

# REQUIRED - Your Discord User ID (from Step 2)
DEV_IDS=123456789012345678

# REQUIRED - Get from Google AI Studio (from Step 3)
GEMINI_API_KEY=your_gemini_api_key_here

# AUTO-GENERATED - Keep as is
SECRET_KEY=auto_generated_32_char_hex_key

# OPTIONAL - Feature toggles (all enabled by default)
ENABLE_GAMES=true
ENABLE_NETWORK_TOOLS=true
ENABLE_AI_COMMANDS=true
ENABLE_SYSTEM_COMMANDS=true

# OPTIONAL - Beta access control
CLOSED_BETA=false

Security Note: Never commit your .env file to version control. It contains sensitive credentials.

Step 6: Initialize Database

# Initialize the SQLite database
python migrations/init_db.py

This creates the database structure needed for:

• User management and whitelisting
• Game statistics (Wordle scores)
• API usage tracking
• Guild (server) information

Step 7: Start the Bot

# Start the bot
python main.py

You should see output similar to:

2024-01-01 12:00:00 [INFO] Bot starting up...
2024-01-01 12:00:01 [INFO] Database initialized successfully
2024-01-01 12:00:02 [INFO] Loaded cog: ai
2024-01-01 12:00:02 [INFO] Loaded cog: games
2024-01-01 12:00:02 [INFO] Loaded cog: info
2024-01-01 12:00:02 [INFO] Loaded cog: network
2024-01-01 12:00:02 [INFO] Loaded cog: system
2024-01-01 12:00:02 [INFO] Loaded cog: tools
2024-01-01 12:00:03 [INFO] UtilsBot+ is ready! Logged in as YourBot#1234

Step 8: Generate Bot Invite Link

UtilsBot+ provides multiple ways to create invite links with the correct permissions:

Option A: Use the Invite Generator Script (Recommended)

# Generate invite with recommended permissions
python generate_invite.py

# Generate invite with minimal permissions
python generate_invite.py --minimal

# Generate invite with admin permissions
python generate_invite.py --admin

# Interactive permission selection
python generate_invite.py --custom

The script will output a complete invite link with appropriate permissions and instructions.

Option B: Manual Setup via Discord Developer Portal

1. Go back to the Discord Developer Portal
2. Select your application
3. Go to "OAuth2" → "URL Generator"
4. Select scopes:
   • bot
   • applications.commands
5. Select bot permissions (for full functionality):
   • View Channels
   • Send Messages
   • Manage Messages
   • Embed Links
   • Attach Files
   • Read Message History
   • Add Reactions
   • Use External Emojis
   • Use Slash Commands
   • Manage Threads
   • Create Public Threads
6. Copy the generated URL and open it in your browser
7. Select your server and authorize the bot

Option C: Use the Discord Command (After Setup)

Once your bot is running, you can also use:

/invite permissions:"recommended"  # Generate invite from within Discord

Step 9: Test the Bot

In your Discord server, try these commands to verify everything is working:

/info                              # Check bot status and statistics
/ping                              # Test bot responsiveness  
/help                              # See enhanced help with categories
/help category:"AI"                # Filter help by category
/ask question:"Hello, how are you?" # Test AI integration
/invite                            # Generate invite for other servers

Expected Results:

• /info should show bot statistics with server count, uptime, and performance metrics
• /ping should return response times under 200ms
• /help should display a beautifully formatted command list with emoji categories
• /ask should respond with an AI-generated message
• Bot status should show dynamic information (server count, version, etc.)

Step 10: Sync Slash Commands (If Needed)

If commands don't appear immediately:

/sync          # Sync commands globally (developers only)

This ensures all slash commands are properly registered with Discord.

Verification Checklist

• Bot appears online in your server
• /info command works and shows correct statistics
• /help command displays all available commands
• /ask command responds with AI-generated content
• No error messages in the console output

What's Next?

Now that your bot is running:

1. Commands Reference - Learn about all available commands
2. Configuration Guide - Customize advanced settings
3. API Integrations - Set up additional external services
4. Security Guide - Configure permissions and security features

Troubleshooting

Bot Won't Start

Check Python Version:

python3 --version  # Should be 3.11 or higher

Verify Dependencies:

pip install -r requirements.txt

Check Environment Variables:

cat .env | grep -E "(BOT_TOKEN|GEMINI_API_KEY|DEV_IDS)"

Commands Not Working

1. Permissions: Ensure the bot has proper permissions in your server
2. Command Sync: Use /sync command to synchronize slash commands
3. Whitelist: If CLOSED_BETA=true, ensure you're whitelisted

Common Error Messages

"Invalid Bot Token"

• Double-check your bot token in the .env file
• Regenerate the token in Discord Developer Portal if needed

"Missing API Key"

• Verify your Gemini API key is correct
• Check that the API key has proper permissions

"Database Error"

• Run python migrations/init_db.py to reinitialize
• Check file permissions in the data/ directory

Getting Help

• Check Logs: Review logs/bot.log for detailed error information
• Enable Debug: Set DEBUG=true in .env for verbose logging
• GitHub Issues: Report bugs or ask questions

---

Navigation: ← Home | Commands Reference →

Related Pages: Configuration Guide | Troubleshooting | Developer Guide