Commands
Every slash command and message command PolarBot registers, with its subcommands, options, the permission level it needs and whether it works in a DM with the bot. Levels come from /perms (see Permission levels); the bot checks the level itself on every use, whatever Discord shows.
Before a server runs /perms authorize, Discord shows every command except /about, /help and /privacy to Administrators only.
Overview
| Command | Required level | In DMs | What it does |
|---|---|---|---|
/about | User | yes | Show the bot’s version, license and source code |
/ban | Moderator | no (servers only) | Ban a user from the server |
/config | Admin | no (servers only) | View or change PolarBot’s settings |
/help | User | yes | Show the commands you can use, or explain one command or topic |
/kick | Moderator | no (servers only) | Kick a member from the server |
/lookup | Moderator | no (servers only) | Show a user’s punishment history, account age and current scanner activity |
/modlog | Moderator | no (servers only) | Show the latest moderation actions |
/perms | Admin to Owner | no (servers only) | Manage which roles have which permission level |
/privacy | User | yes | What PolarBot processes and stores about you |
/scanner | Moderator to Admin | no (servers only) | Configure the scam and spam scanner |
/setup | Admin | no (servers only) | Set up PolarBot: choose the modlog channel |
/timeout | Moderator | no (servers only) | Time out a member so they cannot chat or talk |
/unban | Moderator | no (servers only) | Lift a user’s ban |
/untimeout | Moderator | no (servers only) | Remove a member’s timeout |
/warn | Moderator | no (servers only) | Warn a member |
/warnings | Moderator | no (servers only) | List a user’s warnings |
Analyze with PolarBot | Moderator | no (servers only) | Message command: right-click a message → Apps. |
/about
Shows the running version of PolarBot, the commit and date it was built from, its release channel, its license (AGPL-3.0-or-later) and a link to its source code. Anyone can use it, also in a DM with PolarBot.
- Required level: User
- In DMs: yes
- Shown before
/perms authorize: to everyone - Example:
/about
No options.
/ban
Bans the user from the server. Works for users who are not members too (paste their user ID). You can’t ban yourself, the server owner, PolarBot, or a member whose highest role or PolarBot level is equal to or above yours, and PolarBot’s role must be above theirs. The ban is posted in the log channel and kept in the punishment history for 180 days.
- Required level: Moderator
- In DMs: no (servers only)
- Shown before
/perms authorize: to Administrators only - Example:
/ban user:@Spammer reason:Phishing links delete_messages:Previous 24 hours
| Option | Type | Required | Limits and choices | Description |
|---|---|---|---|---|
user | user | yes | – | The user: pick a member or paste a user ID. |
reason | text | no | at most 500 characters | Why, at most 500 characters. Shown in the audit log and the log channel. |
delete_messages | text | no | one of: Don’t delete any (none), Previous hour (1h), Previous 24 hours (1d), Previous 7 days (7d) | How much of their message history to delete: none (the default), the previous hour, 24 hours or 7 days. |
/config
Shows and changes the settings from /setup. The log level decides how much PolarBot posts in the log channel, from 0 (nothing) to 10 (every event); each level adds to the ones below it. New servers start at level 2.
- Required level: Admin
- In DMs: no (servers only)
- Shown before
/perms authorize: to Administrators only - Example:
/config log-level level:4
/config log-channel
Required level: Admin
Changes the log channel, or turns logging off when you leave channel empty. PolarBot checks its permissions in the channel like /setup does.
| Option | Type | Required | Limits and choices | Description |
|---|---|---|---|---|
channel | channel | no | channel types: GuildText, GuildAnnouncement | The new log channel. Leave it empty to turn logging off. |
/config log-level
Required level: Admin
Sets how much is posted. 0: nothing. 1: scanner punishments. 2 (default): + moderation through PolarBot. 3: + every flagged message. 4: + Discord’s own bans, kicks, timeouts and AutoMod. 5: + joins, leaves and invites. 6: + deleted and edited messages. 7: + role, channel, server, emoji, sticker and webhook changes. 8: + nickname, avatar, username, member role and voice changes. 9: + reactions, threads, pins and every scan score. 10: + every message, presence, typing and other event.
| Option | Type | Required | Limits and choices | Description |
|---|---|---|---|---|
level | integer | yes | 0 to 10 | A number from 0 to 10; each level includes everything below it. |
/config announcements-channel
Required level: Admin
Sets the staff channel where PolarBot posts its “updated to vX.Y.Z” notices. Leave channel empty to clear it: PolarBot then uses a channel named like “staff-announcements”, “staff-news”, “mod-announcements”, “staff-updates” or “bot-updates” (emoji and separators don’t matter) where it can post, otherwise the log channel.
| Option | Type | Required | Limits and choices | Description |
|---|---|---|---|---|
channel | channel | no | channel types: GuildText, GuildAnnouncement | The staff announcements channel. Leave it empty to let PolarBot find one by name. |
/config view
Required level: Admin
Shows the log channel, the log level, where update notices go and which roles have which level.
No options.
/help
Without options, lists the commands your permission level allows in this server (in a DM: the commands that work in DMs), each with a short description and an example. With command, explains one command: what it does, the level it needs, every subcommand and option, and examples. With topic, explains how the scanner works, the permission levels or privacy. Only you see the answer.
- Required level: User
- In DMs: yes
- Shown before
/perms authorize: to everyone - Example:
/help command:scanner
| Option | Type | Required | Limits and choices | Description |
|---|---|---|---|---|
command | text | no | at most 32 characters; autocompletes | The command to explain. Start typing and pick it from the list. |
topic | text | no | one of: How the scanner works (scanner), Permission levels (levels), Privacy (privacy) | A topic: how the scanner works, permission levels or privacy. Ignored when you also give a command. |
/kick
Removes the member from the server; they can come back with a new invite. The same rank rules as /ban apply. The kick is posted in the log channel and kept in the punishment history for 180 days.
- Required level: Moderator
- In DMs: no (servers only)
- Shown before
/perms authorize: to Administrators only - Example:
/kick user:@Troll reason:Ignored two warnings
| Option | Type | Required | Limits and choices | Description |
|---|---|---|---|---|
user | user | yes | – | The member to kick. |
reason | text | no | at most 500 characters | Why, at most 500 characters. Shown in the audit log and the log channel. |
/lookup
Shows the member’s bans, kicks, timeouts and warnings in this server from the last 180 days (counts and the 5 latest), account age, join date, roles, the scanner’s live view of their recent activity, and a risk band (Low, Elevated or High) with the reasons behind it. It is computed on the spot from data PolarBot already keeps; nothing new is stored. Only you see the answer.
- Required level: Moderator
- In DMs: no (servers only)
- Shown before
/perms authorize: to Administrators only - Example:
/lookup user:@Member
| Option | Type | Required | Limits and choices | Description |
|---|---|---|---|---|
user | user | yes | – | The member (or a user who left; then only the history is shown). |
/modlog
Shows the 10 latest bans, unbans, kicks, timeouts and warnings in this server, made with PolarBot’s commands or by the scanner, with moderator, reason and duration. Entries are deleted after 180 days.
- Required level: Moderator
- In DMs: no (servers only)
- Shown before
/perms authorize: to Administrators only - Example:
/modlog user:@Member
| Option | Type | Required | Limits and choices | Description |
|---|---|---|---|---|
user | user | no | – | Only show actions against this user. |
/perms
PolarBot has its own permission levels: User, Moderator, Admin and Owner. A member gets the highest level of their roles; members with the Administrator permission and the server owner are always Owner; everyone else is User. See /help topic: Permission levels for what each level can do.
- Required level: Admin to Owner
- In DMs: no (servers only)
- Shown before
/perms authorize: to Administrators only - Example:
/perms set role:@Moderators level:Moderator
/perms set
Required level: Owner
Gives a role a level, replacing the one it had. @everyone can’t get a level.
| Option | Type | Required | Limits and choices | Description |
|---|---|---|---|---|
role | role | yes | – | The role. |
level | text | yes | one of: User (user), Moderator (mod), Admin (admin), Owner (owner) | User, Moderator, Admin or Owner. |
/perms remove
Required level: Owner
Removes a role’s level; its members keep the levels of their other roles.
| Option | Type | Required | Limits and choices | Description |
|---|---|---|---|---|
role | role | yes | – | The role. |
/perms list
Required level: Admin
Lists the roles that have a level.
No options.
/perms authorize
Required level: Owner
Gives you a private link, valid for 10 minutes, to let PolarBot manage command permissions. After you approve it, each role sees only the commands its level allows, and PolarBot keeps that up to date when levels change. Until then the staff commands are hidden from everyone but administrators.
No options.
/privacy
Explains what PolarBot processes and stores, and shows the punishment history it has about you in every server. Anyone can use it, also in a DM with PolarBot. See also /help topic: Privacy.
- Required level: User
- In DMs: yes
- Shown before
/perms authorize: to everyone - Example:
/privacy my-data
/privacy info
Required level: User
Shows what PolarBot processes and stores, how long it keeps it, the privacy policy and the source code.
No options.
/privacy my-data
Required level: User
Shows the punishment history stored about you (bans, kicks, timeouts and warnings, each server), only to you.
No options.
/scanner
The scanner scores every message from 0 to 100 and logs, deletes or punishes from the thresholds you set. Changes apply at once. See /help topic: How the scanner works for what it looks at.
- Required level: Moderator to Admin
- In DMs: no (servers only)
- Shown before
/perms authorize: to Administrators only - Example:
/scanner status
/scanner status
Required level: Admin
Shows every scanner setting: on or off, actions or log-only mode, thresholds, punishment, channels, exempt roles, domain lists and the size of the threat lists.
No options.
/scanner enable
Required level: Admin
Turns the scanner on (the default).
No options.
/scanner disable
Required level: Admin
Turns the scanner off; no message is scanned.
No options.
/scanner actions
Required level: Admin
Switches between acting (deleting and punishing at the thresholds) and log-only mode, which only posts cards.
| Option | Type | Required | Limits and choices | Description |
|---|---|---|---|---|
enabled | true/false | yes | – | True to delete and punish, False for log-only mode. |
/scanner thresholds
Required level: Admin
Sets the scores (1 to 100) where the scanner logs, deletes and punishes. Give one or more; they must stay in order log ≤ delete ≤ punish. Defaults: 60, 90 and 97.
| Option | Type | Required | Limits and choices | Description |
|---|---|---|---|---|
log | integer | no | 1 to 100 | Post a card for messages at or above this score. |
delete | integer | no | 1 to 100 | Also delete messages at or above this score. |
punish | integer | no | 1 to 100 | Also punish the author at or above this score. |
/scanner punishment
Required level: Admin
Chooses what happens to the author at the punish threshold: nothing, a timeout (default 1 hour), a kick or a ban.
| Option | Type | Required | Limits and choices | Description |
|---|---|---|---|---|
action | text | yes | one of: No punishment (none), Timeout (timeout), Kick (kick), Ban (ban) | No punishment, Timeout, Kick or Ban. |
duration | text | no | at most 32 characters | Timeout length, e.g. 1h or 2d, from 1 minute to 28 days. Only for Timeout. |
/scanner hacked
Required level: Admin
Chooses what happens when an account posts the same link in 3 or more channels within 2 minutes: nothing, delete those messages, or delete them and time out the author (the default).
| Option | Type | Required | Limits and choices | Description |
|---|---|---|---|---|
action | text | yes | one of: Do nothing (none), Delete the messages (delete), Delete the messages and time out (delete_timeout) | Do nothing, Delete the messages, or Delete the messages and time out. |
/scanner mod-role
Required level: Admin
Sets the role PolarBot pings in the log channel on punishments and hacked accounts.
| Option | Type | Required | Limits and choices | Description |
|---|---|---|---|---|
role | role | no | – | The role to ping. Leave it empty to stop pinging. |
/scanner invites
Required level: Admin
Chooses whether Discord invite links are allowed or count towards the score (flagged is the default).
| Option | Type | Required | Limits and choices | Description |
|---|---|---|---|---|
allow | true/false | yes | – | True to allow invites, False to flag them. |
/scanner channel
Required level: Admin
Gives a channel a rule: Monitor (scanned in “only monitored channels” mode), Exempt (never scanned) or Clear the rule. Threads follow their parent channel.
| Option | Type | Required | Limits and choices | Description |
|---|---|---|---|---|
channel | channel | yes | channel types: GuildText, GuildAnnouncement, GuildVoice, GuildStageVoice, GuildForum | The channel. |
rule | text | yes | one of: Monitor (monitor), Exempt (exempt), Clear the rule (clear) | Monitor, Exempt or Clear the rule. |
/scanner channel-mode
Required level: Admin
Chooses which channels are scanned: all except exempt ones (the default), or only monitored ones.
| Option | Type | Required | Limits and choices | Description |
|---|---|---|---|---|
mode | text | yes | one of: All channels except exempt ones (all), Only monitored channels (selected) | All channels except exempt ones, or Only monitored channels. |
/scanner exempt-role
Required level: Admin
Stops scanning members with a role, or starts again. Members with the Moderator level or higher are never scanned anyway.
| Option | Type | Required | Limits and choices | Description |
|---|---|---|---|---|
role | role | yes | – | The role. |
exempt | true/false | yes | – | True to exempt the role, False to scan it again. |
/scanner allow
Required level: Admin
Puts a domain on the allow list: links to it and its subdomains skip the link checks. A domain on a threat list or the block list is still flagged.
| Option | Type | Required | Limits and choices | Description |
|---|---|---|---|---|
domain | text | yes | at most 300 characters | The domain, e.g. example.com. |
/scanner block
Required level: Admin
Puts a domain on the block list: links to it and its subdomains score at least 90. Official domains such as discord.com can’t be blocked.
| Option | Type | Required | Limits and choices | Description |
|---|---|---|---|---|
domain | text | yes | at most 300 characters | The domain, e.g. example.com. |
/scanner unlist
Required level: Admin
Removes a domain from the allow or block list.
| Option | Type | Required | Limits and choices | Description |
|---|---|---|---|---|
domain | text | yes | at most 300 characters | The domain, e.g. example.com. |
/scanner nsfw-links
Required level: Admin
Chooses what happens to links to adult sites (from public adult-domain lists): Ignore, Log (a card), Delete, or Delete and time out. This is separate from the scam score and never applies in channels Discord marks age-restricted (threads follow their parent). New servers: Delete; servers that had PolarBot before 0.3.1: Log. In log-only mode they are only logged.
| Option | Type | Required | Limits and choices | Description |
|---|---|---|---|---|
action | text | yes | one of: Ignore (ignore), Log (log), Delete (delete), Delete and time out (delete_timeout) | Ignore, Log, Delete, or Delete and time out (the timeout length of /scanner punishment). |
/scanner analyze
Required level: Moderator
A dry run: shows the score 0 to 100, what the scanner would do under the current settings, every reason with its weight, a plain-English “Why” for the strongest reasons, what to do when the rating is Elevated or higher, the domains and a line per attachment. Nothing is stored, deleted or posted. Also available by right-clicking a message → Apps → Analyze with PolarBot (Moderator).
| Option | Type | Required | Limits and choices | Description |
|---|---|---|---|---|
text | text | no | at most 2000 characters | Text to analyze, e.g. a message you were sent elsewhere. |
message | text | no | at most 200 characters | A link to a message in this server (right-click → Copy Message Link). Only channels you can read. |
attachment | attachment | no | – | A file to check. Today only its name and type are checked; image content analysis comes later. |
attachment2 | attachment | no | – | A second file to check. |
attachment3 | attachment | no | – | A third file to check. |
/setup
Sets the log channel: PolarBot posts moderation actions, scanner cards and, depending on the log level, other server events there. PolarBot checks that it can view the channel, send messages and embed links in it and refuses the channel otherwise. Change it later with /config log-channel.
Next steps: give your staff roles a level with /perms set, run /perms authorize once, and check the scanner with /scanner status.
- Required level: Admin
- In DMs: no (servers only)
- Shown before
/perms authorize: to Administrators only - Example:
/setup log_channel:#mod-log
| Option | Type | Required | Limits and choices | Description |
|---|---|---|---|---|
log_channel | channel | yes | channel types: GuildText, GuildAnnouncement | A text or announcement channel in this server where PolarBot can view, send messages and embed links. |
/timeout
Puts the member in a Discord timeout: they can still read, but can’t send messages, react or speak until it ends. The same rank rules as /ban apply. End it early with /untimeout.
- Required level: Moderator
- In DMs: no (servers only)
- Shown before
/perms authorize: to Administrators only - Example:
/timeout user:@Spammer duration:1h reason:Spam
| Option | Type | Required | Limits and choices | Description |
|---|---|---|---|---|
user | user | yes | – | The member to time out. |
duration | text | yes | at most 32 characters | How long, e.g. 10m, 1h30m or 7d (units s, m, h, d, w), at most 28 days. |
reason | text | no | at most 500 characters | Why, at most 500 characters. Shown in the audit log and the log channel. |
/unban
Lifts a ban. Banned users aren’t in the server, so paste their user ID (from the server’s ban list or the log channel). Tells you when the user isn’t banned.
- Required level: Moderator
- In DMs: no (servers only)
- Shown before
/perms authorize: to Administrators only - Example:
/unban user:123456789012345678 reason:Appeal accepted
| Option | Type | Required | Limits and choices | Description |
|---|---|---|---|---|
user | user | yes | – | The banned user’s ID. |
reason | text | no | at most 500 characters | Why, at most 500 characters. Shown in the audit log and the log channel. |
/untimeout
Ends the member’s timeout now. The same rank rules as /ban apply.
- Required level: Moderator
- In DMs: no (servers only)
- Shown before
/perms authorize: to Administrators only - Example:
/untimeout user:@Member reason:Calmed down
| Option | Type | Required | Limits and choices | Description |
|---|---|---|---|---|
user | user | yes | – | The member whose timeout to remove. |
reason | text | no | at most 500 characters | Why, at most 500 characters. Shown in the audit log and the log channel. |
/warn
Records a warning with a reason and posts it in the log channel. PolarBot doesn’t message the member, so tell them yourself if they should know. The same rank rules as /ban apply. Warnings are deleted after 180 days; list them with /warnings.
- Required level: Moderator
- In DMs: no (servers only)
- Shown before
/perms authorize: to Administrators only - Example:
/warn user:@Member reason:No advertising in #general
| Option | Type | Required | Limits and choices | Description |
|---|---|---|---|---|
user | user | yes | – | The member to warn. |
reason | text | yes | at most 500 characters | Why, required, at most 500 characters. |
/warnings
Shows how many warnings the user has in this server and the latest 10, with reason, moderator and date.
- Required level: Moderator
- In DMs: no (servers only)
- Shown before
/perms authorize: to Administrators only - Example:
/warnings user:@Member
| Option | Type | Required | Limits and choices | Description |
|---|---|---|---|---|
user | user | yes | – | The user whose warnings to show. |
Message command: Analyze with PolarBot
A message command (right-click a message → Apps → Analyze with PolarBot). It has no options: it runs on the message you clicked.
- Required level: Moderator
- In DMs: no (servers only)
- Shown before
/perms authorize: to Administrators only