Command Reference
Complete reference for every Solstice command, organized by module. Each entry includes the command syntax, required permission level, and behavior description.
Permission Levels
Solstice has a hierarchical permission system. Higher levels include all permissions of lower levels.
| Level | Who | Scope |
|---|---|---|
| Owner | Single user set via OWNER_ID env var | Global - unrestricted access to everything |
| Sudoer | Users added via /addsudo | Global - can use sudo commands across all chats |
| Group Admin | Telegram group administrators + creators | Per-chat - can use admin and music commands |
| Authorized User | Users added via /auth per-chat | Per-chat - can use music playback commands |
| Everyone | All users (when playmode is set to everyone) | Per-chat - can use basic play commands |
Music & Playback
Playing Music
| Command | Permission | Description |
|---|---|---|
/play <query|URL> | Everyone* | Search YouTube and stream audio in VC. Accepts: search queries, YouTube URLs, Spotify track links |
/vplay <query|URL> | Everyone* | Stream video in VC (with picture). Same input as /play |
/playforce <query|URL> | Admin | Force-play audio immediately, clearing the current queue |
/vplayforce <query|URL> | Admin | Force-play video immediately, clearing the current queue |
/song <query> | Everyone | Download a song and send as audio file |
/lyrics <query> | Everyone | Fetch song lyrics from LrcLib API |
/suggest <query> | Everyone | Show 8 song suggestions with inline play buttons |
*When playmode is set to everyone (default). When set to admin, only admins can play.
Playback Control
| Command | Permission | Description |
|---|---|---|
/pause (or /cpause) | Admin | Pause the current stream |
/resume (or /cresume) | Admin | Resume a paused stream |
/stop / /end (or /cstop / /cend) | Admin | Stop playback and clear the queue |
/sleep <duration> (or /csleep <duration>) | Admin | Set a sleep timer to stop playback automatically (e.g., 30m, 1h or off to disable) |
/skip [N] (or /cskip [N]) | Admin | Skip N songs (default: 1). Normal users trigger vote-skip |
/seek <seconds> (or /cseek) | Admin | Seek forward by N seconds |
/seekback <seconds> (or /cseekback) | Admin | Seek backward by N seconds |
/volume <1-200> (or /cvolume <1-200>) | Admin | Set audio playback volume |
/speed (or /cspeed) | Admin | Open speed control panel (0.5x to 2.0x) |
/loop <1-10> (or /cloop <1-10>) | Admin | Loop current song N times |
/shuffle (or /cshuffle) | Admin | Randomly shuffle the queue |
/remove <index> (or /delq <index>) | Admin | Remove a specific track from the queue by its index position |
/queue [page] (or /cqueue) | Everyone | View paginated queue (5 songs per page) |
Playlists
All configuration subcommands are DM-only, while playback is restricted to group chats.
| Command | Permission | Description |
|---|---|---|
/playlist | Everyone | Open the interactive playlist settings panel (DM only) |
/playlist create <name> | Everyone | Create a new custom playlist (DM only, limit 1 per user) |
/playlist delete <name> | Everyone | Delete a playlist (DM only) |
/playlist list | Everyone | List all of your playlists (DM only) |
/playlist show [name] | Everyone | View all tracks in a playlist (DM only, name is optional) |
/playlist add [name] <song/link> | Everyone | Add a track to a playlist (DM only, name is optional) |
/playlist remove [name] <track_number> | Everyone | Remove a track from a playlist (DM only, name is optional) |
/playlist clear [name] | Everyone | Remove all tracks from a playlist (DM only, name is optional) |
/playlist rename <old_name> <new_name> | Everyone | Rename a playlist (DM only) |
/playlist share [name] <public|private> | Everyone | Set privacy settings (DM only, name is optional) |
/playlist play [name] | Everyone | Play your playlist in a group voice chat (Group only, name is optional) |
/playlist play <@username/user_id> <name> | Everyone | Play another user's public playlist (Group only) |
Playback Settings
| Command | Permission | Description |
|---|---|---|
/autoplay (or /cautoplay) | Admin | Toggle autoplay - auto-queues related songs when queue empties |
/playcard (or /cplaycard, /cards) | Admin | Toggle "Now Playing" cards in the chat |
/playmode (or /mode) | Admin | Toggle between everyone and admin play permissions |
/setvotes <1-20> | Admin | Set number of votes required for vote-skip |
/voteskip | Everyone | Cast a vote to skip the current song |
/channelplay <linked|channel_id> | Admin | Connect VC playback to a channel instead of the group |
Now Playing Card Controls
When a song starts playing, an inline keyboard is sent with these buttons:
| Button | Symbol | Action |
|---|---|---|
| Resume | ▷ | Resume paused stream |
| Pause | II | Pause current stream |
| Loop | ↻ | Cycle loop: Off → 1x → 2x → 3x → Off |
| Skip | ‣‣I | Skip to next song |
| Stop | ▢ | Stop playback and clear queue |
| Vote Skip | 👍 N/T | Vote to skip (N = current votes, T = threshold) |
Group Management
Ban Module
| Command | Permission | Description |
|---|---|---|
/ban [user] [reason] | Admin | Permanently ban a user. Target via reply, @username, or user ID |
/tban [user] <duration> | Admin | Temporarily ban. Duration format: 5m, 2h, 3d |
/dban | Admin | Delete replied message AND ban user |
/sban | Admin | Silent ban (bans target and deletes command message without sending chat reply) |
/sdban / /dsban | Admin | Silent delete & ban (deletes replied message + command message, silent execution) |
/stban / /dtban / /sdtban | Admin | Silent and/or delete variants for temporary bans |
/unban [user] | Admin | Unban a previously banned user |
Mute Module
| Command | Permission | Description |
|---|---|---|
/mute [user] [reason] | Admin | Permanently mute a user (revoke send permissions) |
/dmute [user] | Admin | Delete replied message AND mute user |
/smute [user] | Admin | Silent mute (mutes target and deletes command message without sending chat reply) |
/sdmute / /dsmute | Admin | Silent delete & mute (deletes replied message + command message, silent execution) |
/tmute [user] <duration> | Admin | Temporarily mute. Duration format: 10m, 1h, 2d |
/stmute / /dtmute / /sdtmute | Admin | Silent and/or delete variants for temporary mutes |
/unmute [user] | Admin | Unmute a muted user (restore default permissions) |
Kick Module
| Command | Permission | Description |
|---|---|---|
/kick [user] | Admin | Kick a user (they can rejoin via invite link) |
/dkick [user] | Admin | Delete replied message AND kick user |
/skick [user] | Admin | Silent kick (kicks user and deletes command message without sending chat reply) |
/sdkick / /dskick | Admin | Silent delete & kick |
Message Management
| Command | Permission | Description |
|---|---|---|
/del | Admin | Delete the replied-to message |
/purge | Admin | Delete all messages from the replied message to the command message |
/spurge | Admin | Silent purge - same as /purge but no confirmation message |
/pin | Admin | Pin the replied message (silently) |
/unpin | Admin | Unpin the replied message |
/unpinall | Admin | Unpin all messages (with confirmation dialog) |
Admin Promotion
| Command | Permission | Description |
|---|---|---|
/promote [user] [title] | Admin | Promote user to admin with basic permissions |
/fullpromote [user] [title] | Admin | Promote with all available permissions (matches bot's own) |
/demote [user] | Admin | Remove all admin permissions from a user |
/setadmintitle [title] | Admin | Set custom admin title (reply to admin, max 16 chars). Alias: /admintitle |
Warning System
| Command | Permission | Description |
|---|---|---|
/warn [user] [reason] | Admin | Issue a warning. Auto-actions at limit (default: 3 warns) |
/dwarn [user] [reason] | Admin | Delete replied offending message AND issue warning (warning notification remains visible) |
/unwarn [user] | Admin | Remove the latest warning |
/warns [user] | Everyone | Check a user's warning count and history |
/setwarnmode <ban|mute|kick> | Admin | Set action taken when warn limit is reached |
Authorization
| Command | Permission | Description |
|---|---|---|
/auth [user] | Admin | Authorize a user to use music commands (max 25 per chat) |
/unauth [user] | Admin | Remove a user's authorization |
/authlist | Admin | List all authorized users for the current chat |
Locks
| Command | Permission | Description |
|---|---|---|
/lock <type> | Admin | Lock a message type: url, media, bot, forward, game, sticker, gif, inline, poll |
/unlock <type> | Admin | Unlock a previously locked type |
/locks | Admin | Show current lock status for all types |
Welcome System
| Command | Permission | Description |
|---|---|---|
/welcome <on|off> | Admin | Enable/disable welcome messages |
/setwelcome <text> | Admin | Set custom welcome message. Supports {name}, {chat}, {mention} placeholders |
/clearwelcome | Admin | Clear the custom welcome message |
Rules
| Command | Permission | Description |
|---|---|---|
/setrules <text> | Admin | Set group rules |
/rules | Everyone | Display group rules |
Member Tagging
| Command | Permission | Description |
|---|---|---|
/tagall [message] | Admin | Mention all group members (sends in batches with delay) |
/cancel | Admin | Cancel an in-progress /tagall operation |
Approvals (Lock Bypass)
| Command | Permission | Description |
|---|---|---|
/approve [user] | Admin | Approve a user to bypass chat locks |
/unapprove [user] | Admin | Remove approval |
/approved | Admin | List all approved users |
Sudo Commands
These commands are restricted to the bot Owner and Sudoers.
User Management
| Command | Permission | Description |
|---|---|---|
/addsudo [user] | Owner only | Add a user to the global sudoers list |
/delsudo [user] | Owner only | Remove a user from sudoers |
/sudolist | Sudoer | List all sudoer user IDs |
/gban [user] | Sudoer | Globally ban a user across all served chats (async) |
/ungban [user] | Sudoer | Remove a global ban |
/block [user] | Sudoer | Block a user from using the bot entirely |
/unblock [user] | Sudoer | Unblock a user |
/blocked | Sudoer | List all blocked users |
Chat Management
| Command | Permission | Description |
|---|---|---|
/blacklistchat <chat_id> | Sudoer | Blacklist a chat from using the bot |
/whitelistchat <chat_id> | Sudoer | Remove a chat from the blacklist |
/blchats | Sudoer | List all blacklisted chats |
/activevc or /vc | Sudoer | List all chats with active audio voice chats |
/activevideo or /vvc | Sudoer | List all chats with active video voice chats |
/ac or /av | Sudoer | Summary of active audio + video stream counts |
Bot Control
| Command | Permission | Description |
|---|---|---|
/broadcast <text> | Sudoer | Broadcast a message to all served chats and users |
/maintenance <enable|disable> | Sudoer | Toggle maintenance mode (disables all commands for non-sudoers) |
/logger <enable|disable> | Sudoer | Toggle activity logging |
/autoend | Sudoer | Toggle auto-leave when voice chat becomes empty |
/reboot or /restart | Owner only | Restart the bot process |
/setcookies | Owner only | Set YouTube cookies (reply to a text message or .txt file) |
/checkcookies | Owner only | Validate current YouTube cookies against YouTube |
Utility Commands
| Command | Permission | Description |
|---|---|---|
/q / /qr / /r | Everyone | Generate a quote sticker with user profile picture (PFP) from replied message |
/ping | Everyone | Check bot latency and system stats (uptime, RAM, CPU, disk, PyTgCalls ping) |
/stats | Everyone | Bot-wide statistics (served chats, users, database size) |
/afk [reason] | Everyone | Set yourself as AFK. Bot will notify others who mention you |
/whois or /info | Everyone | Get information about a user |
/owner or /creator | Everyone | Show bot developer information |
/id | Everyone | Get Telegram IDs (chat ID, user ID, message ID) |
/reload or /admincache | Everyone | Refresh the admin cache (3-minute cooldown per chat) |
/language or /lang | Admin | Set chat language (currently English) |
/tr [lang_code] | Everyone | Translate the replied message (via Google Translate). Default: en |
/kang | Everyone | "Kang" (steal) a sticker to your personal sticker pack |
Fun Commands
Interactive Reactions (with Accept/Reject)
These commands require replying to another user's message:
| Command | Description |
|---|---|
/hug | Send a hug request (with anime GIF from nekos.best) |
/kiss | Send a kiss request |
/cuddle | Send a cuddle request |
/propose | Propose to someone (💍) |
The target user sees Accept / Reject buttons. Only they can respond.
One-Way Actions
| Command | Description |
|---|---|
/slap | Slap someone (anime GIF) |
/kill | Eliminate someone (anime GIF) |
/crush | Randomly pick a "secret crush" from group admins |
Mood Commands
| Command | Description |
|---|---|
/cry, /blush, /smile, /happy, /dance, /bully | Express emotions with anime GIFs. Can target someone via reply |
Games & Misc
| Command | Description |
|---|---|
/truth | Random truth question |
/dare | Random dare challenge |
/couples or /couple | Pick two random admins as "couple of the day" (with composite profile picture image) |
/wish <text> | Make a wish - get a random probability score |
/cute | Check how cute you (or replied user) are (random %) |
/fonts <text> | Convert text to stylish/fancy fonts with pagination |
/tts <text> | Convert text or replied message into speech audio (.mp3) |
Whisper (Inline Mode)
Whisper lets users send secret messages that only the target can read, using Telegram's inline mode:
@BotUsername <@user|user_id> <message>Types:
- Normal Whisper - Target can open it multiple times
- One-Time Whisper - Message self-destructs after the target reads it
Both sender and target can view the whisper. Anyone else who tries will get denied and the sender will be notified.
Target User Resolution
For commands that act on a user (ban, mute, promote, etc.), the target is resolved in this order:
- Reply - Reply to a user's message
- Text mention - Mention with user entity in the message
- @username - First word of the payload as a username
- Numeric ID - First word of the payload as a Telegram user ID
Example equivalents:
/ban ← reply to target's message
/ban @username ← by username
/ban 123456789 ← by user ID
/ban @username reason ← with reason