# Commands Reference

Complete reference for all UtilsBot+ slash commands with examples and usage guidelines.

## Command Categories

- [AI Commands](#ai-commands) - Google Gemini AI integration
- [Games](#games) - Interactive games and entertainment
- [Network Tools](#network-tools) - Web and network utilities
- [Security Tools](#security-tools) - Security and encryption utilities
- [Information Commands](#information-commands) - Bot stats and help
- [Developer Commands](#developer-commands) - Development and system tools (restricted)
- [Admin Commands](#admin-commands) - User management (restricted)

---

## AI Commands

### `/ask`
Ask questions to Google Gemini AI for intelligent responses.

**Usage:**
```
/ask question:"What is machine learning?" [ephemeral:true]
```

**Parameters:**
- `question` (required): Your question or prompt
- `ephemeral` (optional): Whether the response should be private (default: false)

**Examples:**
```
/ask question:"Explain quantum computing in simple terms"
/ask question:"Write a Python function to calculate fibonacci" ephemeral:true
/ask question:"What's the weather like today?" 
```

**Features:**
- Context-aware responses using Gemini 1.5 Flash
- Response truncation for Discord's character limits (3800 chars)
- Rate limiting: 3 questions per minute per user
- Usage tracking and statistics

**Rate Limits:**
- 3 requests per 60 seconds per user
- Free tier: 15 requests per minute globally

---

### `/chat`
Start an interactive chat session with AI through a modal interface.

**Usage:**
```
/chat
```

**Features:**
- Interactive modal for longer conversations
- Continue/End buttons for extended chats
- Context preservation within the session
- Private ephemeral responses

**How it works:**
1. Use `/chat` to open the chat modal
2. Type your message in the text area
3. Click "Send" to get AI response
4. Use "Continue" for follow-up questions
5. Use "End Chat" to close the session

---

## Games

### `/wordle`
Play the classic Wordle word-guessing game.

**Usage:**
```
/wordle
```

**Game Rules:**
- Guess the 5-letter word in 6 attempts
- Color-coded feedback:
  - 🟩 Green: Correct letter in correct position
  - 🟨 Yellow: Correct letter in wrong position
  - ⬛ Black: Letter not in the word

**Features:**
- Full Wordle game implementation
- Interactive UI with guess input modals
- Statistics tracking (games played, won, best scores)
- One active game per user at a time
- 2000+ valid word database

**Example Game Flow:**
1. Use `/wordle` to start a new game
2. Enter your 5-letter guess in the modal
3. Receive color-coded feedback
4. Continue guessing until you solve it or run out of attempts
5. View your statistics and start a new game

---

## Network Tools

### `/screenshot`
Capture screenshots of websites with customizable options.

**Usage:**
```
/screenshot url:"https://example.com" [full_page:true] [width:1920] [height:1080]
```

**Parameters:**
- `url` (required): Website URL to capture
- `full_page` (optional): Capture full page vs viewport (default: false)
- `width` (optional): Viewport width in pixels (default: 1920)
- `height` (optional): Viewport height in pixels (default: 1080)

**Examples:**
```
/screenshot url:"https://github.com"
/screenshot url:"https://example.com" full_page:true
/screenshot url:"https://mobile-site.com" width:375 height:667
```

**Features:**
- High-quality PNG screenshots
- Ad blocking enabled by default
- Timeout protection (30 seconds)
- URL validation and security checks
- Private IP protection

**Requirements:**
- Bot needs "Attach Files" permission
- ScreenshotOne API key for enhanced features (optional)

---

### `/ip`
Get detailed information about IP addresses or domains.

**Usage:**
```
/ip address:"8.8.8.8"
/ip address:"google.com"
```

**Parameters:**
- `address` (required): IP address or domain name

**Examples:**
```
/ip address:"1.1.1.1"
/ip address:"github.com"
/ip address:"192.168.1.1"
```

**Information Provided:**
- Country, region, city
- ISP and organization
- Coordinates (latitude/longitude)
- Timezone
- Country flag emoji
- Private IP detection

**Features:**
- Support for both IPv4 addresses and domain names
- Automatic domain resolution
- Rate limiting protection
- Private IP range detection

---

### `/unshorten`
Expand shortened URLs and check their safety.

**Usage:**
```
/unshorten url:"https://bit.ly/example"
```

**Parameters:**
- `url` (required): Shortened URL to expand

**Examples:**
```
/unshorten url:"https://tinyurl.com/example"
/unshorten url:"https://bit.ly/3xyz123"
/unshorten url:"https://t.co/abcd1234"
```

**Features:**
- Follows redirect chains safely
- Suspicious domain detection
- Redirect limit protection (max 10 redirects)
- Final URL validation
- Safety warnings for potentially harmful sites

**Supported Services:**
- bit.ly, tinyurl.com, t.co, goo.gl
- Custom shorteners and redirect services
- Most URL shortening services

---

## Security Tools

### `/totp`
Generate Time-based One-Time Passwords (TOTP) for 2FA authentication.

**Usage:**
```
/totp secret:"YOUR2FASECRET" [ephemeral:true]
```

**Parameters:**
- `secret` (required): Your 2FA secret key (base32 encoded)
- `ephemeral` (optional): Private response (recommended: true)

**Examples:**
```
/totp secret:"JBSWY3DPEHPK3PXP" ephemeral:true
/totp secret:"GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ"
```

**Features:**
- Standard TOTP algorithm (RFC 6238)
- 30-second time windows
- Time remaining indicator
- Base32 secret validation
- Ephemeral responses for security

**Security Notes:**
- Always use `ephemeral:true` to keep codes private
- Secrets are not stored by the bot
- Codes expire every 30 seconds

---

### `/qr`
Generate QR codes for text, URLs, or other data.

**Usage:**
```
/qr text:"Hello World" [size:"medium"]
```

**Parameters:**
- `text` (required): Text to encode (max 2000 characters)
- `size` (optional): QR code size - "small", "medium", "large" (default: medium)

**Examples:**
```
/qr text:"https://github.com/ad1107/utils-bot-plus"
/qr text:"WiFi:T:WPA;S:NetworkName;P:password;;" size:"large"
/qr text:"My contact info: John Doe, john@example.com" size:"small"
```

**Size Options:**
- **Small**: 200x200 pixels
- **Medium**: 400x400 pixels (default)
- **Large**: 600x600 pixels

**Features:**
- High-quality PNG output
- Error correction level M
- Support for various data types (URLs, WiFi, contact info, plain text)
- Automatic optimization for readability

---

### `/base64`
Encode or decode text using Base64 encoding.

**Usage:**
```
/base64 text:"Hello World" operation:"encode"
/base64 text:"SGVsbG8gV29ybGQ=" operation:"decode"
```

**Parameters:**
- `text` (required): Text to encode or decode
- `operation` (required): "encode" or "decode"

**Examples:**
```
/base64 text:"Secret message" operation:"encode"
/base64 text:"U2VjcmV0IG1lc3NhZ2U=" operation:"decode"
/base64 text:"https://example.com" operation:"encode"
```

**Features:**
- Standard Base64 encoding/decoding
- UTF-8 text support
- Input validation
- Error handling for invalid Base64 strings

---

### `/hash`
Generate cryptographic hashes for text input.

**Usage:**
```
/hash text:"password123" algorithm:"sha256"
```

**Parameters:**
- `text` (required): Text to hash
- `algorithm` (required): Hash algorithm - "md5", "sha1", "sha256", "sha512"

**Examples:**
```
/hash text:"hello world" algorithm:"sha256"
/hash text:"password123" algorithm:"md5"
/hash text:"important data" algorithm:"sha512"
```

**Supported Algorithms:**
- **MD5**: 128-bit hash (deprecated for security)
- **SHA1**: 160-bit hash (deprecated for security)
- **SHA256**: 256-bit hash (recommended)
- **SHA512**: 512-bit hash (most secure)

**Features:**
- Hexadecimal output format
- All major hash algorithms supported
- Consistent hashing results

---

### `/password`
Generate cryptographically secure random passwords.

**Usage:**
```
/password [length:16] [include_symbols:true] [ephemeral:true]
```

**Parameters:**
- `length` (optional): Password length 8-128 characters (default: 16)
- `include_symbols` (optional): Include special characters (default: true)
- `ephemeral` (optional): Private response (recommended: true)

**Examples:**
```
/password
/password length:24 include_symbols:false ephemeral:true
/password length:12 include_symbols:true
```

**Character Sets:**
- **Letters**: a-z, A-Z
- **Numbers**: 0-9
- **Symbols**: !@#$%^&*()_+-=[]{}|;:,.<>?

**Features:**
- Cryptographically secure random generation
- Customizable length and character sets
- No password storage or logging
- Ephemeral responses for security

---

## Information Commands

### `/info`
Display comprehensive bot statistics and system information.

**Usage:**
```
/info
```

**Information Displayed:**
- Bot version and uptime
- Server and user counts
- System resources (CPU, memory usage)
- Database statistics
- Feature toggle status
- Performance metrics
- Discord API latency

**Example Output:**
```
📊 UtilsBot+ Statistics
Version: 2.0.0 | Uptime: 2d 3h 45m
Servers: 150 | Users: 12,543
Memory: 125MB | CPU: 2.3%
Commands: 1,234 total | Latency: 45ms
```

---

### `/ping`
Test bot responsiveness and latency.

**Usage:**
```
/ping
```

**Metrics Displayed:**
- Response time (command processing)
- WebSocket latency (Discord connection)
- Round-trip time measurement

**Example Output:**
```
🏓 Pong!
Response Time: 123ms
WebSocket Latency: 45ms
```

---

### `/version`
Show bot version information and changelog.

**Usage:**
```
/version
```

**Information Displayed:**
- Current bot version
- Build date and commit hash
- Recent changelog entries
- Update notifications

---

### `/invite`
Generate Discord invite links for the bot with customizable permissions.

**Usage:**
```
/invite [permissions:"recommended"] [ephemeral:true]
```

**Parameters:**
- `permissions` (optional): Permission level for the invite
  - `recommended` (default): Full bot functionality
  - `minimal`: Basic commands only
  - `network`: Network tools optimization
  - `admin`: Administrator permissions
- `ephemeral` (optional): Whether to show privately (default: true)

**Permission Levels:**

**Minimal:**
- View Channels, Send Messages, Use Slash Commands
- Embed Links, Attach Files, Read Message History
- Use External Emojis

**Recommended (Default):**
- All minimal permissions plus:
- Manage Messages, Add Reactions
- Use External Stickers, Manage Threads
- Create Public Threads

**Network:**
- Optimized for screenshot and network tools
- Minimal permissions + Attach Files

**Administrator:**
- Full server access (all permissions)

**Examples:**
```
/invite                                    # Recommended permissions
/invite permissions:"minimal"              # Basic functionality
/invite permissions:"admin" ephemeral:false # Admin perms, public response
```

**Features:**
- Interactive permission descriptions
- Direct invite links with proper Discord scopes
- Usage instructions and requirements
- Bot avatar display in embed

---

### `/help`
Enhanced interactive help system with modern UI and category filtering.

**Usage:**
```
/help [category:"AI"] [ephemeral:false]
```

**Parameters:**
- `category` (optional): Filter commands by specific category
- `ephemeral` (optional): Whether to show help privately (default: false)

**Available Categories:**
- `Information` ℹ️ - Bot info, help, invite commands
- `AI` 🤖 - Google Gemini AI integration
- `Games` 🎮 - Interactive games (Wordle, etc.)
- `Tools` 🔧 - Security and utility tools
- `Network` 🌐 - Web and network utilities
- `System` ⚙️ - Developer and admin commands

**Enhanced Features:**
- **Emoji-categorized organization** for visual clarity
- **Smart autocomplete** for category selection
- **Command grouping** with subcommand support
- **Developer indicators** (🔒) for restricted commands
- **Responsive design** with automatic field splitting
- **Built-in usage guides** and documentation links
- **Real-time command counting** and statistics

**Examples:**
```
/help                           # Show all commands with usage guide
/help category:"AI"             # Show only AI commands
/help category:"Games" ephemeral:true # Private games help
```

**Display Format:**
```
🛠️ UtilsBot+ Commands

ℹ️ Information
  `/info` - Display bot information and statistics
  `/help` - View all available commands
  🔒 `/invite` - Generate bot invite links

🤖 AI
  `/ask` - Ask questions to Google Gemini AI
  `/chat` - Interactive chat session

💡 How to Use Commands
• Type `/` in chat to see all available commands
• Use `/help <category>` to filter by category
• Commands marked with 🔒 require developer permissions

📚 Documentation & Support
• Commands Reference • User Guide • FAQ • Report Issues
```

---

## Developer Commands

> **Restriction**: These commands are only available to users listed in `DEV_IDS` environment variable.

### `/sync`
Synchronize slash commands with Discord.

**Usage:**
```
/sync [scope:"global"]
```

**Parameters:**
- `scope` (optional): "global", "guild", or specific guild ID

**Sync Options:**
- **Global**: Updates commands for all servers (takes up to 1 hour)
- **Guild**: Updates commands for current server only (immediate)
- **Specific**: Updates commands for a specific guild ID

**When to Use:**
- After adding new commands
- When commands don't appear
- After modifying command parameters

---

### `/eval`
Execute Python code in a secure sandboxed environment with file upload support.

**Usage:**
```
/eval [code:"print('Hello World')"] [stdin_input:"test"] [file:upload] [legacy_mode:false]
```

**Parameters:**
- `code` (optional): Python code to execute - can be left blank when uploading files
- `stdin_input` (optional): Input data for the program
- `file` (optional): Upload a Python file (.py) or text file (.txt) to execute
- `legacy_mode` (optional): Use unsafe legacy mode (not recommended)

**File Upload Features:**
- 📤 **Upload Support**: Attach .py or .txt files up to 1MB
- 🔄 **Flexible Input**: Use code parameter, file upload, or both combined
- 📁 **Smart Handling**: Automatically uses file content when code field is blank
- 💡 **File Feedback**: Real-time processing status with file size information

**Security Features:**
- 🐳 **Docker containerization**: Full isolation with resource limits
- ⏱️ **Timeout protection**: 10-second execution limit
- 🔒 **Import restrictions**: Blocked dangerous modules (os, sys, subprocess)
- 💾 **Memory limits**: 128MB memory allocation
- 🚫 **Network isolation**: No external network access

**Available Context (Legacy Mode):**
- `bot`: Bot instance
- `interaction`: Current interaction
- `discord`: Discord.py module
- `db`: Database connection

**Examples:**
```
# Direct code execution
/eval code:"print('Hello World')"

# With input handling
/eval code:"x = input('Enter number: '); print(int(x) * 2)" stdin_input:"42"

# File upload only (leave code blank)
/eval file:upload_your_script.py

# File upload with additional code
/eval code:"print('Additional code')" file:upload_your_script.py

# With stdin input and file
/eval file:upload_your_script.py stdin_input:"test data"
```

**⚠️ Security Note:** Always use the default secure mode. Legacy mode bypasses security restrictions and should only be used for trusted code.

---

### `/run`
Execute code with competitive programming support and comprehensive file upload capabilities.

**Usage:**
```
/run [code:"solution code"] [language:"python"] [input_data:"test input"] [timeout:10] [file:upload]
```

**Parameters:**
- `code` (optional): Code to execute - can be left blank when uploading files
- `language` (optional): Programming language (auto-detected from filename if not specified)
- `input_data` (optional): Input data for the program
- `timeout` (optional): Execution timeout in seconds (1-30, default: 10)
- `file` (optional): Upload source code files up to 5MB

**File Upload Features:**
- 📤 **Enhanced Upload Support**: Multiple file types up to 5MB each
- 🔄 **Language Auto-Detection**: Automatically detects language from file extension
- 📁 **Smart Code Handling**: Uses file content when code parameter is blank
- 💡 **Flexible Input**: Combine uploaded files with additional code parameters
- 📊 **File Processing Feedback**: Real-time status updates during file processing

**Supported Languages:**
- 🐍 **Python**: Full support with scientific libraries
- 🔄 **C++/Java**: Compilation and execution support
- 📝 **Auto-Detection**: Language determined from file extensions (.py, .cpp, .java, etc.)

**Features:**
- 🏃 **Competitive programming**: Optimized for algorithm contests
- 💾 **Enhanced resources**: 256MB memory, full CPU access
- 📊 **Detailed output**: Execution time, memory usage, file creation tracking
- 📁 **Multiple files**: Support for multiple input files and data sets
- ⏱️ **Flexible timeout**: Configurable execution time limits

**Examples:**
```
# Direct code execution
/run code:"n = int(input()); print(sum(range(1, n+1)))" input_data:"100"

# File upload only (leave code blank)
/run file:solution.py input_data:"5\n1 2 3 4 5" timeout:15

# Auto-detect language from filename
/run file:solution.cpp input_data:"test case data"

# Combine file upload with additional code
/run code:"print('Debug info')" file:main_solution.py input_data:"test data"

# Python with custom timeout
/run file:algorithm.py input_data:"large_dataset" timeout:25
```

**Available Python Libraries:**
- **Scientific**: NumPy, SciPy, SymPy
- **Algorithms**: NetworkX for graph problems
- **Data Processing**: Pandas, Matplotlib (limited output)

**File Size Limits:**
- **Maximum file size**: 5MB per file
- **Supported extensions**: .py, .cpp, .java, .c, .txt, and more
- **Multiple files**: Can handle multiple uploaded files in execution environment
- **Standard**: math, itertools, collections, etc.

---

### `/reload`
Hot reload bot cogs without restarting.

**Usage:**
```
/reload cog:"ai"
```

**Parameters:**
- `cog` (required): Name of cog to reload

**Available Cogs:**
- ai, games, info, network, system, tools

**Benefits:**
- No bot downtime
- Instant code updates
- Development efficiency

---

### `/load` / `/unload`
Dynamically load or unload cogs.

**Usage:**
```
/load cog:"new_feature"
/unload cog:"maintenance_feature"
```

**Features:**
- Dynamic feature management
- No restart required
- Safe unloading with cleanup

---

## Admin Commands

> **Restriction**: These commands are only available to developers for user management.

### `/whitelist add`
Add users to the beta whitelist.

**Usage:**
```
/whitelist add user:@username
```

### `/whitelist remove`
Remove users from the beta whitelist.

**Usage:**
```
/whitelist remove user:@username
```

### `/whitelist list`
View all whitelisted users.

**Usage:**
```
/whitelist list
```

### `/whitelist check`
Check if a user is whitelisted.

**Usage:**
```
/whitelist check user:@username
```

---

## Usage Tips

### Command Permissions
- Most commands work in any server where the bot has permissions
- Developer commands require `DEV_IDS` configuration
- Some commands may require specific bot permissions (e.g., "Attach Files" for screenshots)

### Rate Limiting
- AI commands: 3 requests per minute per user
- Other commands: Standard Discord rate limits apply
- Rate limits prevent spam and ensure fair usage

### Privacy Options
- Use `ephemeral:true` for sensitive commands (TOTP, passwords)
- AI responses can be made private with the ephemeral parameter
- Most commands support both public and private responses

### Error Handling
- Commands provide clear error messages
- Check bot permissions if commands fail
- Review logs for detailed error information

---

**Navigation**: [← Getting Started](Getting-Started) | [Configuration Guide →](Configuration-Guide)

**Related Pages**: [API Integrations](API-Integrations) | [Troubleshooting](Troubleshooting) | [Security Guide](Security-Guide)