fusion - documentation

🔑

tracking ID system

what are entry IDs?
every important action (blacklist, note, flag, tag, audit) generates a unique ID in the format PREFIX-XXXXXX (e.g. BL-A3F2C1). you can always look up any entry using !lookup regardless of which collection it's in.

BL-XXXXXX

collection: blacklists

generated when adding to blacklist (permanent or temp). sent via DM to the user.

NOTE-XXXXXX

collection: UserNotes / GuildNotes

generated when adding a note to a user or server.

FLAG-XXXXXX

collection: UserFlags

generated when adding a flag to a user. stored in flag history.

TAG-XXXXXX

collection: Tags

generated when creating a new tag (response snippet).

AUD-XXXXXX

collection: AuditLog

generated automatically on important actions (e.g. blacklist add/remove).

!lookup <ID>

works with all prefixes

searches any entry by ID across the entire database and shows its details.

🔒

permission system

OWNERID set in environment variable OWNER - full access to all commands

STAFF+ID in STAFF var or admin role in config - access to staff+ commands

important: owners are always bypassed by blacklist and maintenance mode. staff is bypassed by guild disable and maintenance, but not by blacklist.

how to set permissions
in your .env file set:
OWNER=123456789,987654321
STAFF=111111111,222222222
you can also add an admin-level role per server through the Config collection (field Permissions.adminrole).

👤

user accounts

3 commands

!account [@user]

opens an interactive account management panel with action buttons

STAFF+

►

syntax!account [@user]

// if no user provided, shows your own account

argument	type	required	description
@user	Discord User (mention or ID)	optional	user to inspect. if omitted - checks the caller.

panel buttons:
toggle blacklist - if user is blacklisted, removes them. if not, opens modal with "Reason" field and blacklists permanently (auto-sends DM with blacklist info).

temp blacklist - opens modal with Duration (e.g. 30m, 2h, 7d) and Reason fields.

send DM - opens modal, type a message, bot sends it as embed to the user.

note - opens modal to add/update internal note.

refresh - refreshes embed with current database state.

examples

!account @fusion_user

opens panel for user

!account 123456789012345678

opens panel by user ID

!account

opens your own account panel

!userinfo !ui

detailed discord user info - ID, bot status, creation date, mutual servers, avatar

OWNER

►

syntax!userinfo <user>

argument	type	required	description
user	Discord User (mention or ID)	required	user to check. you can provide an ID even if they're not on the server.

embed contains: user ID (snowflake), bot status (true/false), account creation date (from snowflake, Warsaw time), mutual server count, avatar link.

vs !account: !userinfo shows raw Discord data (no db data). !account shows db data (premium, blacklist, notes) + action panel.

examples

!ui @someone

!userinfo 123456789012345678

!dm_user !dm

sends a DM to any user directly via command (as an embed from the bot)

OWNER

►

syntax!dm_user <user> <message>

argument	type	required	description
user	Discord User	required	recipient (mention or ID).
message	text (to end of message)	required	DM content. can contain spaces - everything after user is the message.

bot sends embed with your message and footer text "message from [you] via bot management". if user has DMs closed, bot notifies you with an error.

examples

!dm_user @user Your account has been verified.

!dm 123456789012345678 Welcome to premium testing!

🚫

blacklist

4 commands

how blacklist works:
a blacklisted user trying to use any command sees an embed with a "more information" button - clicking it sends DM details about the block (or ephemeral if DMs closed). owners always bypass blacklist. on permanent blacklist, bot auto-sends DM to the user with block details.

!add_blacklist

permanently blacklists a user by ID and sends them a DM with details

OWNER

►

syntax!add_blacklist <user_id> [reason]

argument	type	required	description
user_id	int (Discord ID)	required	user ID to block. user doesn't need to be in any server.
reason	text	optional	reason for the block. defaults to "no reason provided". visible in user DM and !account.

1

generates entry ID in format BL-XXXXXX

-

2

saves to blacklists collection (upsert - overwrites if exists)

-

3

adds entry to AuditLog (action: blacklist_add)

-

4

sends DM to user with embed (reason, who added, time, "permanent"). if DMs closed - warns you.

examples

!add_blacklist 123456789012345678 spamming commands

!add_blacklist 123456789012345678

without reason - uses "no reason provided"

!remove_blacklist

removes a user from the blacklist (permanent or temporary)

OWNER

►

syntax!remove_blacklist <user_id>

automatically adds entry to AuditLog (action: blacklist_remove). if user wasn't blacklisted - bot informs you.

examples

!remove_blacklist 123456789012345678

!list_blacklist

shows all blacklisted users (max 200 entries)

OWNER

►

syntax!list_blacklist

// no arguments

each entry shows: entry ID (BL-XXXXXX), user ID, expiry date (or "permanent"). embed shows total entry count.

!search_blacklist !sbl

search blacklist entries by user ID, entry ID, or reason fragment

OWNER

►

syntax!search_blacklist <query>

argument	type	required	description
query	text or number	required	if number: searches by exact user ID. if text: searches by reason fragment or entry ID (case-insensitive regex).

examples

!sbl 123456789012345678

search by user ID

!sbl spam

search by reason fragment

!sbl BL-A3F2C1

search by entry ID

⭐

premium

2 commands + panel

!premium_add

grants premium to a user (saves to Subscriptions collection)

OWNER

►

syntax!premium_add <user>

argument	required	description
user	required	mention or ID. saves to `Subscriptions` (upsert). stores: user ID, who added, when added.

server premium is managed via the !guild panel ("toggle premium" button adds/removes the PREMIUM flag from Config.Features).

!premium_remove

revokes premium from a user

OWNER

►

syntax!premium_remove <user>

if the user didn't have premium - bot will inform you. removes entry from Subscriptions collection.

🚩

user flags

1 command, 3 actions

what are flags?
flags are internal text tags assigned to users - e.g. suspicious, verified, vip, alt-account. visible in !account panel and help with internal organization. each flag addition creates a history entry with its own FLAG-XXXXXX ID.

!flag <action> <user_id> [tag]

add, remove, or list internal flags (tags) on a user account

OWNER

►

syntax!flag <add|remove|list> <user_id> [tag]

action	extra arg	description
add	tag (required)	adds tag to user's flag list. generates `FLAG-XXXXXX` ID and saves in history. user can have multiple flags.
remove	tag (required)	removes specific tag from flag list. doesn't delete history.
list	-	shows all active flags for user as embed.

suggested flag values:
suspicious - suspicious behavior
alt-account - suspected alt of another user
verified - verified user
vip - important person
banned-appeal - currently appealing a ban
you can enter any text as a tag.

examples

!flag add 123456789012345678 suspicious

!flag remove 123456789012345678 suspicious

!flag list 123456789012345678

🏰

server management

7 commands

!guild [guild_id]

interactive server management panel with 7 action buttons

STAFF+

►

syntax!guild [guild_id]

// without argument - uses current server

toggle premium - adds/removes PREMIUM flag from Config.Features.

toggle disable - disables/enables all bot commands on this server. staff+ can still use commands when server is disabled.

temp blacklist - temporarily blacklists the entire server (format: 30m, 2h, 7d).

DM owner - opens modal, bot sends DM to server owner.

note - adds internal note to server.

leave guild - bot leaves this server.

refresh - refreshes embed.

examples

!guild

panel for current server

!guild 123456789012345678

panel for server by ID

!guildinfo !gi

detailed server info without opening panel (channels, roles, emoji, boosts)

OWNER

►

syntax!guildinfo [guild_id]

shows: ID, owner, member count, channel count, role count, emoji count, boost tier, boost count, creation date. info-only, no action buttons.

!guilds

list of all servers the bot is in, sorted descending by member count

STAFF+

►

syntax!guilds

shows: server name, ID, member count. if list is very long - auto splits into multiple messages (chunking at 1900 chars).

!search_guilds !sg

search servers by name fragment (case-insensitive)

OWNER

►

syntax!search_guilds <name_fragment>

searches locally in bot memory (bot.guilds) - doesn't query Discord API. result: max 30 servers.

examples

!sg gaming

finds "Gaming Hub", "Pro Gaming", etc.

!leave <guild_id>

forces the bot to leave a server

STAFF+

►

syntax!leave <guild_id>

irreversible - after leaving the server, the bot loses access to all channels and permissions. to return, the bot must be re-invited.

!disable_guild / !enable_guild

disables or enables bot commands on a specific server without opening the panel

OWNER

►

syntax!disable_guild <guild_id> [reason]
!enable_guild <guild_id>

when server is disabled, users see an info embed. staff+ can still use commands. saves: guild_id, who disabled, when, reason (if given).

examples

!disable_guild 123456789012345678 terms of service violation

!enable_guild 123456789012345678

!features <add|remove> <guild_id> <feature>

adds or removes any feature flag from a server's configuration

OWNER

►

syntax!features <add|remove> <guild_id> <feature>

examples

!features add 123456789012345678 PREMIUM

!features add 123456789012345678 BETA_TESTER

!features remove 123456789012345678 BETA_TESTER

✅

server whitelist

3 commands

how whitelist works:
when the whitelist has at least 1 entry, the bot automatically leaves any server not on the whitelist. when empty - bot accepts all servers.

!whitelist / !unwhitelist / !wlist

manage server whitelist - add, remove, list

STAFF+

►

syntax!whitelist <guild_id>
!unwhitelist <guild_id>
!wlist // list all

!wlist shows embed with list: server name (if bot is in it), ID, date added, who added.

examples

!whitelist 123456789012345678

!unwhitelist 123456789012345678

!wlist

📝

internal notes

1 command, 3 actions

auto-detection: !notes automatically detects whether the provided ID is a server (via bot.get_guild()) or a user. servers go to GuildNotes, users to UserNotes.

!notes <action> <id> [text]

add, view, or delete internal notes for a user or server

STAFF+

►

syntax!notes <add|view|delete> <id> [text]

action	text?	description
add	required	adds or updates note. each `add` overwrites the previous note. generates `NOTE-XXXXXX` ID.
view	none	shows embed with note, author, and date.
delete / del / remove	none	deletes the note. all three forms work the same.

examples

!notes add 123456789012345678 reported payment issues in march 2025

!notes view 123456789012345678

!notes delete 123456789012345678

🏷️

tags (response snippets)

1 command, 4 actions

what are tags?
tags are ready-made response templates - e.g. frequently repeated instructions, FAQ, welcome messages. instead of writing the same thing over and over, create a tag once and call it with !tag send <name>.

!tag <action> [name] [content]

create, send, delete, and list tags (canned response snippets)

OWNER

►

syntax!tag create <name> <content>
!tag send <name>
!tag delete <name>
!tag list

action	aliases	description
create	add	creates or updates tag. name is lowercase. content can contain emotes, links, newlines. generates `TAG-XXXXXX`.
send	get	sends tag content as a normal message in the channel.
delete	del, remove	permanently deletes tag.
list	-	shows all tags with their TAG-XXXXXX IDs.

examples

!tag create how-premium To activate premium, message the developer or open a ticket.

!tag send how-premium

bot sends ready response in channel

!tag list

🔧

maintenance mode

1 command, 3 actions

when maintenance is active, all users (except OWNER and STAFF) see an embed with maintenance info instead of command responses. bot automatically changes status to DND + "watching maintenance".

!maintenance !maint

enable, disable, or check maintenance mode status

STAFF+

►

syntax!maintenance on [reason]
!maintenance off
!maintenance status

action	aliases	description
on	enable, start	activates maintenance. optional reason (if none: "no reason provided."). changes bot status to DND + watching.
off	disable, stop	disables maintenance. restores online + "watching !config".
status	check	shows whether maintenance is active, since when, by whom, and with what reason.

examples

!maint on database update - back in ~30 minutes

!maint off

!maint status

🎮

bot status

2 commands

!status

interactive panel to change bot activity (Playing, Watching, Listening, Streaming, Custom)

STAFF+

►

syntax!status

// shows buttons, each opens a modal with text field

button	Discord activity type	description
Playing	Game	e.g. "Playing Minecraft"
Watching	Activity.watching	e.g. "Watching 50 servers"
Listening	Activity.listening	e.g. "Listening to your commands"
Streaming	Streaming	requires: stream title + URL (must be Twitch/YouTube)
Custom	Game (custom text)	any text as status

status changes immediately and is visible to all Discord users. status is not saved in the database - resets after bot restart.

!say <message>

bot speaks the given text and auto-deletes your command

OWNER

►

syntax!say <message>

your command message is automatically deleted (if bot has Manage Messages permission). bot sends the content as plain text in the channel.

examples

!say Bot will go down at 11PM for 15 minutes.

📊

diagnostics & stats

8 commands

!uptime

how long the bot has been running without interruption (since last start/restart)

STAFF+

►

syntax!uptime

format: Xd Xh Xm Xs. also shows exact startup date and time in Warsaw timezone.

!ping

bot WebSocket latency + measured Discord API response time

STAFF+

►

syntax!ping

WebSocket latency - heartbeat delay between bot and Discord (low = good connection).
API round-trip - time from sending message to Discord returning it (measured via message edit).

!botstats

general bot stats: servers, users, blacklist, cogs, commands, version, Python

STAFF+

►

syntax!botstats

shows: server count, cached users, blacklist entry count, loaded cog count, command count, bot version (from Config), Python version, discord.py version.

!dbstats

number of documents in each MongoDB collection

OWNER

►

syntax!dbstats

checks: blacklists, Subscriptions, Config, whitelist, Errors, UserNotes, GuildNotes, AuditLog, Tags, UserFlags.

!vps

VPS server stats (CPU, RAM, Disk) - sent to your DMs

OWNER

►

syntax!vps

requires psutil library. if not installed - bot will inform you. results: CPU%, RAM% (used/total MB), Disk% (used/total GB). sent via DM for security.

!logs [n] [file]

sends last N lines from log file to your DMs

OWNER

►

syntax!logs [lines=30] [file=bot.log]

examples

!logs

last 30 lines from bot.log

!logs 100

!logs 50 errors.log

!error <error_id>

fetches full traceback of an error stored in the database by its ID

STAFF+

►

syntax!error <error_id>

error ID comes from the Errors collection. bot sends full traceback to your DMs as a Python code block.

!ebg <guild_id>

last 5 errors for a specific server - sent to your DMs

STAFF+

►

syntax!ebg <guild_id>

searches Errors collection filtering by guild_id, sorts from newest, takes last 5. each entry: error_id + first 160 chars of traceback.

📋

audit log & lookup

2 commands

!auditlog !audit

shows recent entries from the internal audit log with optional filtering

OWNER

►

syntax!auditlog [limit=20] [action_filter]

argument	default	description
limit	20	number of entries to show (max 50).
action_filter	none	filters by action name fragment (case-insensitive regex). e.g. `blacklist` shows only actions containing "blacklist".

automatically logged actions:
- blacklist_add - added to blacklist
- blacklist_remove - removed from blacklist
other actions can be added in code via await self._audit(...).

examples

!audit

last 20 entries

!audit 50 blacklist

last 50 entries filtered by "blacklist"

!lookup <ID>

searches any database entry by its tracking ID

OWNER

►

syntax!lookup <PREFIX-XXXXXX>

supported prefixes and collections:
- BL- - blacklists (field: entry_id)
- NOTE- - UserNotes (field: note_id) + fallback to GuildNotes
- FLAG- - UserFlags (field: history[].flag_id)
- AUD- - AuditLog (field: audit_id)
if prefix is known - searches directly in the right collection. if unknown or not found - searches all collections.

result is an embed with all document fields (database IDs hidden). footer shows source collection.

examples

!lookup BL-A3F2C1

!lookup NOTE-B7E4D2

!lookup AUD-FF1A90

💻

developer tools

6 commands

!eval !e

executes arbitrary Python code in the bot's context - dangerous command!

OWNERDANGER

►

syntax!eval <python code>

// can use code blocks or type code directly

warning: this command gives full access to the bot, database, and server filesystem. never give anyone else access to this command. any error in the code can crash the bot or corrupt data.

available variables in eval context:
bot - bot instance, ctx - command context, db - MongoDB database, cog - ManagementCog instance, discord - discord.py module, commands - commands module

examples

!e len(bot.guilds)

!e await db.blacklists.count_documents({})

!e [g.name for g in bot.guilds[:5]]

!reload / !load / !unload

reloads, loads, or unloads a cog extension without restarting the bot

OWNER

►

syntax!reload <path.to.extension>
!load <path.to.extension>
!unload <path.to.extension>

path is Python import format: folder.file (without .py). if the file is at Cogs/Developer/management.py, extension is Cogs.Developer.management.

examples

!reload Cogs.Developer.management

!load Cogs.Fun.games

!cogs

list of all currently loaded cogs

OWNER

►

syntax!cogs

shows alphabetically sorted list of all cogs loaded via bot.load_extension(). useful after !reload or to check if a specific cog is active.

!sync [mode]

syncs slash commands with Discord API (globally or for current server)

OWNER

►

syntax!sync [~ | ^]

mode	action	when to use
(none)	global sync - all servers	after adding new slash commands. may take up to 1h to appear everywhere.
~	sync only for current server	for testing - changes visible immediately on this server only.
^	clears slash commands from current server	when you want to remove local (test) commands from server.

global sync after every small change is a bad idea - Discord rate-limits this aggressively. use ~ for tests, global only for final deployment.

examples

!sync ~

sync to current server (instant, for testing)

!sync

global sync (appears everywhere within ~1h)

!version <version>

sets the bot version string in the database (visible in !botstats)

OWNER

►

syntax!version <version string>

examples

!version 2.1.0

!version 1.0.0-beta

!restart

graceful bot restart - stops process, PM2/systemd restarts automatically

OWNER

►

syntax!restart

bot calls bot.close() which ends the event loop. PM2 or systemd must be configured to auto-restart the process. without it, the bot simply shuts down.

before restarting, make sure there are no long-running operations in progress (e.g. an active broadcast).

📢

broadcast to server owners

1 command

!broadcast <message>

sends DM to owners of ALL servers the bot is in - with mandatory confirmation

OWNER

►

syntax!broadcast <message>

1

bot shows: "this will DM X owners. react with checkmark within 30s."

-

2

you wait and react with checkmark. if no reaction within 30s - broadcast cancelled.

-

3

bot iterates through all servers, fetches owner, sends DM with embed (title "message from the bot developer").

-

4

waits 0.5s between each DM (rate limit protection). at the end reports: sent count, failed count.

on each server bot tries to fetch the owner - if owner has left Discord or has DMs closed, the DM will fail (counted as "failed").

examples

!broadcast Bot will go offline Friday night. estimated downtime: 2-3h.

!broadcast New bot version available! changelog: discord.gg/xyz

fusiondocumentation

admin panel

fusion
documentation