Durations and flags

A duration is a number and a unit, with no space between them. Several can be chained.

/mute Steve 30m Spam
/ban Steve 7d Griefing
/ban Steve 1d12h Griefing
/ban Steve 2w3d Repeated griefing

Months are always 30 days and years are always 365. They are shorthand, not calendar arithmetic, so 1mo from 1 January expires on 31 January.

Decimals are accepted and rounded to the nearest second, so 1.5h is 90 minutes.

Permanent

/ban Steve permanent Cheating
/ban Steve perm Cheating
/ban Steve forever Cheating
/ban Steve Cheating

All four are permanent. Omitting the duration entirely is the same as writing permanent, because the first word is only read as a duration if it parses as one. Cheating does not, so it becomes the reason.

That is also why a reason starting with a duration-like word needs care. /ban Steve 30 day ban for griefing reads 30 as an invalid duration and stores the whole thing as the reason. Use a template or reword it.

How durations are displayed

Remaining time is compacted to two units at most: 2d 4h, 45m, 3h 20m. Anything under a minute shows in seconds. Permanent punishments show the text from placeholder-api.values.permanent, which defaults to Permanent.

Caps

If your rank has a duration limit, a longer duration is refused with a message naming your maximum. It is not silently trimmed.

Flags go after the reason and can be combined in any order.

/ban Steve 30d Cheating --silent --proof https://imgur.com/a/example
/mute Steve 1h Spam --scope server:global
/ban Steve Cheating --preview

--silent

Suppresses announcements, not the record. The punishment is stored with its silent flag set, appears in history normally, and is enforced normally. Staff who need to know can still look it up.

Without blazebans.silent, the flag is rejected and the command does nothing, rather than running loudly. Tab completion only offers --silent to staff who hold the node.

--proof

Takes one URL with no spaces.

/ban Steve 30d Cheating --proof https://imgur.com/a/example

The URL is checked before it is saved. Anything containing whitespace, <, >, quotes, or backslashes is rejected rather than stored. A bare domain gets https:// prefixed.

BlazeBans also picks up a URL sitting loose in the reason, so /ban Steve 30d Cheating https://imgur.com/a/example attaches it too. Being explicit is better, because it keeps the URL out of the stored reason text.

Proof appears on the record, in /proof view, and as an "Open proof" button on the Discord embed. See Proof.

--preview

Runs every check and reports what would happen. Nothing is written, nobody is removed, nothing is announced. Useful for confirming what a template resolves to before applying it to a real player.

--ip

Widens the match to the player's stored IP address, so other accounts on that address are covered.

This needs privacy.store-ip-addresses: true. With IP storage off, there is no address on file and the flag has nothing to match.

/ipban and /ipmute are the same behaviour as dedicated commands, which is usually clearer for staff and easier to gate with a separate permission.

--scope

Sets which servers enforce the punishment.

global, all, *, server:all, and server:* are all accepted for global. Anything else unrecognised is read as a server ID.

Global scope needs blazebans.scope.global. A specific server needs blazebans.scope.server.<id>, unless it is the server you are on, which is always allowed. See Servers and scope.

--punisher

Records the punishment against a different name:

/ban Steve 30d Cheating --punisher Alex
/ban Steve 30d Cheating --punisher Anti-cheat
/punish Steve Cheating --punisher Anti-cheat

Console only. A player running it gets an error.

The name replaces the issuer everywhere one appears: /history, /staffhistory, staff profiles, and the Discord post.

Two uses:

Attributing a decision to the person who made it. An appeals panel or Discord bot acting through the console can credit the staff member who approved the action rather than CONSOLE.

Naming the system that acted. An anticheat or chat filter punishing through BlazeBans should identify itself, or every automated punishment on your server is indistinguishable from an administrator typing at the console.

/punish Steve Cheating --punisher Anti-cheat

Combining it with /punish is worth doing: automated punishments then escalate on the same ladders as manual ones, instead of the detector applying a policy of its own.

The flag captures everything up to the next flag or the end of the line, so multi-word names work as long as it comes last or before another -- flag:

/ban Steve 30d Cheating --punisher Chat Filter --silent

See Best practices for why this matters to how your history reads later.

/unban, /unmute, and /unwarn accept --silent and -s. Everything else in their arguments is treated as the revoke reason.

/unban Steve Appeal accepted
/unban Steve Appeal-Accepted
/unmute Steve --silent

The second line uses an unban template, which can carry its own broadcast. See Revoking and editing.