Commands

Not a plugin - this page explains how commands themselves behave.

Setup checklist

1. Open Setup > Access & Permissions and assign role or user levels. Start with 50 for moderators and 100 for administrators.
2. Use the Would it run? resolver with a real member, command, and channel. Fix level, override, lockdown, or blacklist results until it says the command will run for the reason you expect.
3. Run the prefix form in a test channel. Prefix commands need no Discord registration and are the quickest permission test.
4. Open Slash Commands, opt in one command, save, and wait a few seconds.
5. Invoke the slash command. If it does not appear, confirm the bot was invited with Discord's application commands scope and the plugin or feature is on.
6. Repeat the resolver after every access-rule change. It uses the command's real built-in level and shows which rule won.

Start with narrow overrides and lockdowns. A plugin-wide rule affects every command in that plugin, including commands added later.

Reading a command listing

Every command table in these docs lists a command with its arguments:

• {curly braces} mark a required argument. Leave it out and the command tells you what it needed.
• [square brackets] mark an optional argument.

So /tempban {user} {duration} [reason] needs a user and a duration, and takes a reason if you want to give one. The names match the option names Discord shows on the slash form, and the prefix form takes the same arguments in the same order. A few commands also offer an extra slash-only option, such as attaching an image, because Discord's slash form can carry a file and a typed message cannot.

Prefix

Every command works as a prefix command (!ban @user reason); the prefix is per-server (commands.prefix). Mentioning the bot does not run commands - the text prefix is the only trigger.

A space after a symbol prefix means the message is not a command. !ban runs, ! ban does nothing at all - no infraction, no log, no reply. That is deliberate: moderators often mime punishing each other with ! ban or ! slowmode, and a joke should never execute. The same applies to custom commands.

If your prefix ends in a letter or a digit, the space is your separator instead, so hep ban runs normally for a server whose prefix is hep. Both forms work there: hep ban and hepban.

Slash commands

Slash commands are opt-in per server: the dashboard's Slash Commands page lists every available command grouped by plugin, and only what you tick gets registered in your server. Changes deploy within seconds of saving. Commands whose plugin is unconfigured (or whose feature is not granted) are flagged on that page so you do not register dead entries.

Levels

Who can run what is decided by numeric levels from your levels: config (0 everyone, 10 trusted, 50 moderator, 100 admin). Each command has a default; overrides can change it per server.

Overrides and lockdowns

commands.overrides matches commands by name, group, plugin, or everything, and can disable them, change the required level, or set a per-user cooldown in seconds - handy for opening something like rank up in a busy general chat without the spam:

commands:
  overrides:
    - name: rank
      out: {cooldown: 30}

The cooldown counts per member per command; moderators (level 50 and up) are exempt, and a member still on cooldown gets told how long is left. commands.lockdown restricts where commands run: channel and category allow-lists, role allow/exclude lists. The channel and category allow-lists combine - a command runs in any channel you list AND anywhere under any category you list, so you can fence a plugin into a whole category plus a couple of stray channels outside it. Exclude lists always win over allow lists.

One limitation worth knowing: channel and category lockdown lists do not recognize threads - a thread is its own channel as far as Discord is concerned, so a command locked to a channel or category cannot be used inside threads or forum posts, even ones under an allowed channel. Role lists are unaffected.

A lockdown only ever narrows who and where - it never lowers a command's level. To let a role use a command above its level (say, tags create, which needs level 10), add an override that lowers the level, or give the role a level on the Access form.

The Setup → Access & Permissions page edits both structurally and includes a resolver: pick command + channel + member, and it answers "would this run?" with the exact rule that decided. The resolver knows every command's built-in level (shown next to each command in the picker), so its answer matches what the bot actually does.

Blacklists

commands.local_blacklist / commands.bot_blacklist block users from using the bot in your server; entries can carry reasons as YAML comments. The dashboard's Blacklist page manages the same lists.

The two blacklists

They are not the same:

• bot_blacklist makes the bot ignore the member completely - commands, tags, custom-command triggers, XP, starboard stars, the lot.
• local_blacklist blocks commands only; everything else still counts.

Cooldowns and denial behaviour

commands.dm_denied (on by default) deletes the command message and DMs the member the reason they could not run it. Turn it off and a denied command is ignored silently, with nothing posted in the channel either way. To switch a command off, give it an override with out: { disabled: true }. To switch a whole plugin off, remove its plugins.<name>: block.

Troubleshooting

• Prefix works but slash does not appear: opt the exact command in and verify the bot invite includes application commands.
• Slash appears but is denied: registration and permission to execute are separate. Use Would it run? for the member and channel.
• A role seems ignored: a direct user entry in levels overrides all of that user's role levels, including downward.
• A thread is unexpectedly denied: channel and category lockdown allowlists do not include child threads automatically.
• A command is silent: commands.dm_denied: false deliberately suppresses the denial explanation.