Documentation

Getting started

1. Invite the bot to your server and give it Administrator (or at least Manage Roles, Manage Channels, Ban/Kick Members, Moderate Members, Manage Messages and View Audit Log).
2. Move the bot's role above the roles it should manage. Discord's role hierarchy cannot be bypassed.
3. Run ,setup to create the moderation log and jail resources, and ,setupmute for the mute roles.
4. Run ,help for a link to the command list, or ,help moderation for one category.

Prefix and slash commands

The default prefix is a comma: ,ping. Admins can change it with ,prefix set ! and every member can set a personal prefix with ,prefix self ?. The comma always keeps working as a fallback.

The most common commands are also slash commands (/ban, /play). Newer commands are prefix-only because Discord limits bots to 100 slash commands.

Arguments in (parentheses) are required and [brackets] are optional. Most options can be given as --flag value, for example ,antiraid massjoin on --threshold 5 --do kick.

Permissions

Commands need the same Discord permission you would need to do the action by hand (Ban Members for ,ban, Manage Roles for ,r). Server owners and administrators can use everything. The command list shows the permission each command needs.

Moderation

,warn @user spamming        ,timeout @user 10m reason
,mute @user                 ,jail @user reason
,kick @user                 ,ban @user reason
,tempban @user 7d           ,unban 1234567890
,history @user              ,notes add @user watch this one
,proof add 12 (link)        ,reason 12 new reason

Every action creates a numbered case. ,history @user lists a member's cases and ,caselog 12 shows one in detail, including who acted and any proof you attached with ,proof. ,modstats @mod shows a moderator's activity.

Customising responses

Change what members see and what is sent to the punished user: ,invoke ban message (text) and ,invoke ban dm (text). Use ,invoke ban message view to see the current text.

Lockdowns and channels

,lock   ,unlock   ,lockdown all raid in progress   ,lockdown release
,hide #channel @role   ,slowmode 10   ,nuke

,lockdown ignore add #announcements keeps a channel out of a server-wide lockdown.

Temporary and sticky roles

,temprole @user 2d @VIP        ,stickyrole @user @Supporter

Temporary roles are removed automatically, even after a restart. Sticky roles come back if the member rejoins.

Automod filters

Each filter deletes the message, can warn, timeout, kick or ban, and skips admins and exempt roles.

,filter links on action=timeout
,filter links whitelist youtube.com
,filter caps on threshold=70
,filter spam on count=5 seconds=6
,filter invites on
,filter massmention on threshold=5
,filter add badword        ,filter regex (pattern)
,filter exempt @Trusted    ,filter reset

Filters available: invites, links, caps, spam, emoji, massmention, spoilers, musicfiles. Add a #channel to limit a filter to that channel. You can also manage everything from the dashboard's Automod page.

Anti-nuke and anti-raid

Anti-nuke watches for destructive actions (mass bans, channel or role deletion, webhook spam, new bots, giving out admin) and punishes the member responsible. Trusted staff can be whitelisted.

,antinuke ban on --threshold 3 --do quarantine
,whitelist @TrustedAdmin

Anti-raid protects the join gate:

,antiraid massjoin on --threshold 5 --do kick
,antiraid avatar on        ,antiraid age on 7 ban
,antiraid whitelist @friend   ,antiraid state off

When a mass join is detected the bot enters raid state, locks invites and punishes the joiners until you run ,antiraid state off. A honeypot channel (,honeypot add #do-not-post ban) catches bots that post everywhere.

Welcome messages and embeds

,welcome set #welcome Welcome {user.mention} to {guild.name}!
,goodbye set #goodbye {user.name} left.
,boost set #boosts Thanks {user.mention} for boosting!

Messages support variables such as {user.mention}, {user.name}, {guild.name}, {guild.member_count} and {date.utc_now} (list them with ,welcome variables), and embed scripts:

{embed}$v{title: Welcome {user.name}}$v{description: You are member #{guild.member_count}}$v{color: #8b5cf6}

Add --self_destruct 30 to delete the message after 30 seconds. The same scripting works for level-up messages, auto responders, sticky messages, timers and webhooks.

Levels, starboard, giveaways

Levels

,levels unlock            ,levels add @Active 5
,levels message {user.mention} reached level {level.new_rank}!
,levels setrate 1.5       ,rank

Starboard and clownboard

,starboard set #starboard    ,starboard threshold 3
,clownboard set #hall-of-shame   ,clownboard emoji (emoji)

Messages that reach the threshold of reactions are reposted to the board, and the count updates as reactions change.

Giveaways

,giveaway start #giveaways 1h 1 Discord Nitro
,giveaway edit requiredroles (message link) @Member
,giveaway end (message link)    ,giveaway reroll (message link)

Members enter by reacting to the giveaway message. Requirements: required roles, minimum or maximum level, account age and time in server. Giveaways survive restarts.

Also included

Suggestions (,suggest), sticky messages (,stickymessage add), timers (,timer add), counters (,counter add members), bump reminders, birthdays, reminders, tickets, and temporary voice channels (,voicemaster setup).

Music and Spotify

,play never gonna give you up
,play https://open.spotify.com/playlist/...
,queue   ,skip   ,pause   ,resume   ,seek 1:30
,shuffle   ,repeat queue   ,volume 60   ,preset nightcore on

Spotify links, albums and playlists work without any account: the bot reads the track list and plays the matching audio. Run ,spotify login to connect your account for ,play liked, playing your current Spotify track, and controlling your own Spotify (Premium required for playback control).

Last.fm

,lastfm login yourname      ,fm      ,lastfm whoknows Radiohead
,lastfm topartists 7d       ,lastfm collage 3x3 month    ,lastfm taste @friend

Plain ,fm works from the public Last.fm profile page. Most other commands use the Last.fm API, which the bot owner enables by adding an API key. If Last.fm has nothing to show, ,fm falls back to your Spotify status and then to what the bot is playing.

Social feeds and reposter

,youtube add #videos @channelname
,subreddit add #memes memes
,pinterest add #inspo username

YouTube, subreddit and Pinterest posts are delivered automatically (checked every few minutes). Other platforms can be subscribed but have no public feed to read yet.

,reposter on turns TikTok, Instagram, X and YouTube Shorts links into uploaded videos. Tune it with ,reposter delete on, strict, suppress, embed and prefix.

Control commands per server

,disablecommand #general snipe        ,disablecommand all snipe
,disablemodule #general fun           ,disableevent #general levels
,restrictcommand giveaway @Staff      ,ignore @someone

Disabled commands stay silent for members, administrators can always use them, and the core commands cannot be switched off. The dashboard's Modules page does the same with switches. Add your own shortcuts with ,alias add (name) (command).

Running your own copy

The bot is open Python (discord.py). You need Python 3.11+, FFmpeg for music, a Discord bot token and a machine that stays on.

pip install -r requirements.txt
cp env.example .env       # add DISCORD_TOKEN and optional keys
python -m app.main

FAQ

A command says I am missing permissions.

You need the matching Discord permission, and the bot's role must be above the target's highest role.

Commands run twice.

Two copies of the bot are running with the same token. Stop one.

Music does not play.

The bot needs Connect and Speak in the voice channel, and FFmpeg installed on the host.

Where do I report a bug or ask for a feature?

Contact the server or bot owner who invited you.