> ## Documentation Index
> Fetch the complete documentation index at: https://docs.headlesslabs.xyz/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Moderation setup

> Prepare moderation, mute roles, and action messages using Headless's actual permission checks.

## Recommended workflow

Good practices: review the member with `.userinfo @Member`, choose an action with a clear reason, and verify the record with `.case <ID>` or `.cases`. Sanctions and individual role changes create moderation cases and log events.

> [!TIP]
>
> Use concise reasons, keep relevant evidence, and confirm role hierarchy allows
> the action. Do not raise the bot's role to fix an isolated permission issue.

**Note:**

Fake Permissions can satisfy some compatible moderator checks, but never gives
Headless native Discord permissions. The bot's own permissions and Discord
role hierarchy still apply. Setup reports configured-log failures instead of silently replacing it.

## Staff roles shared with Strip Staff

`.bind staff @role` toggles a normal server role in the list shared by Strip Staff and Dashboard Staff Roles. `.bind staff list` displays the configured roles. The command requires the server owner or an authorized Anti-Nuke Admin, and Headless must be above the role. `@everyone` and integration-managed roles are rejected; the list is limited to 120 roles. Changes are stored per server and written to the security log. This list does not grant Anti-Nuke Admin access, add a whitelist exemption, or bypass other protections.

```headless-command Syntax theme={null}
.bind staff [role]
```

```headless-command Example theme={null}
.bind staff @Moderators
```

```headless-command Syntax theme={null}
.bind staff list
```

```headless-command Example theme={null}
.bind staff list
```

![Headless response confirming a role was configured as a staff role; server-specific mentions were hidden.](https://mintcdn.com/headless-labs/ZF85v3KoGVX7saRn/images/headless-replies/moderation-bind-staff-redacted.png?fit=max\&auto=format\&n=ZF85v3KoGVX7saRn\&q=85\&s=d26849efb51443f179922a2cbce0a273)

Real Headless confirmation after adding a staff role; the member and role mentions were redacted. The captured response is in Spanish.

## Member actions

Ban, kick, and timeout have prefix and slash commands. The reason is optional; when omitted, Headless records `No reason provided`. The server owner and bot cannot be targets; every target must be below both the moderator and Headless. The server owner can bypass only the moderator hierarchy check. Timeout accepts `30m`, `2h`, or `1d`, up to 28 days.

For slash commands, select the member and optional reason in Discord's option picker; those fields are not typed after the command name.

> [!WARNING]
>
> Headless needs `Ban Members`, `Kick Members`, or `Moderate Members` depending
> on the action. Slash-command defaults do not replace the bot's actual
> permissions.

### Ban

```headless-command Syntax theme={null}
.ban <user_query> [reason=No reason provided]
```

```headless-command Example theme={null}
.ban @Member repeated spam
```

```headless-command Syntax theme={null}
/ban member:<member> [reason:<reason>]
```

```headless-command Example theme={null}
/ban
```

### Kick

```headless-command Syntax theme={null}
.kick <user_query> [reason=No reason provided]
```

```headless-command Example theme={null}
.kick @Member repeated disruption
```

```headless-command Syntax theme={null}
/kick member:<member> [reason:<reason>]
```

```headless-command Example theme={null}
/kick
```

### Timeout

```headless-command Syntax theme={null}
.timeout <user_query> <duration> [reason=No reason provided]
```

```headless-command Example theme={null}
.timeout @Member 30m repeated flooding
```

```headless-command Syntax theme={null}
/timeout member:<member> duration:<duration> [reason:<reason>]
```

```headless-command Example theme={null}
/timeout
```

## Initial setup

**1. Check permissions and hierarchy**

For `.setup`, you must be the owner or have `Manage Server` / `Administrator`; Headless needs `Manage Roles` and `Manage Channels`, or `Administrator`. Role hierarchy still applies.

**2. Set up Jail and logs**

Run `.setup` and review `Created`, `Existing`, and `Failed` before using Jail.

**3. Set up mute roles**

Run `.setupmute`; review channel failures and fix permissions or hierarchy before rerunning.

**4. Customize messages if needed**

`.invoke` can customize acknowledgements and DMs by action; it is not required to enable sanctions.

> [!NOTE]
>
> `.setupmute` also requires the caller to be the owner or have `Manage Server`
> / `Administrator`. Headless needs `Manage Roles` or `Administrator`, and its
> role must stay above each mute role.

> **What `.setup` creates**
>
> It uses the configured log channel when Headless can resolve and access it
> to view, send messages, and embed links. Otherwise it reuses `#jail-log` or
> creates a private channel. If the configured channel exists but lacks
> permissions, setup reports the failure instead of silently replacing it.
> It also creates or reuses the `Jailed` role and private `Jail` channel; once
> setup succeeds, Jail is enabled and saved per server. A partial failure does not mean earlier changes were rolled back.

> **Roles and results from `.setupmute`**
>
> It creates or reuses `Muted` (messages and threads: prevents writing and creating public or private threads), `Image Muted` (prevents attaching files), and `Reaction Muted` (prevents adding reactions). Permission overwrites are applied to
> supported categories and channels; synced channels use their category's
> overwrite. It cannot use `@everyone`, managed roles, roles with
> `Administrator`, or roles at or above Headless. The result separates created
> roles, reused roles, and channel failures; role IDs are stored per server.

## Cases, logs, and limits

> **Cases, logs, and limits**
>
> Prefix-command permission or access-check denials go to the denial log when
> a destination is available. Other Discord errors and slash commands may use
> different responses or logging paths. The runtime controls automatic command-message deletion; no published Dashboard control was found.
> Cooldowns are defined per command, with no verified Dashboard control to
> adjust them.

> **Customize acknowledgements with `.invoke`**
>
> It accepts `jail`, `kick`, `ban`, `hardban`, `timeout`, and `warn`. `message`
> customizes the command response; `dm` customizes the private message to the
> target. Each combination is stored separately; `.invoke list` shows which differ
> from defaults and `.invoke <action> reset` removes only that action's custom
> text.
> Templates are validated before saving. The caller must be the owner or have
> `Administrator` or `Manage Server`. `tempban` and `softban` are not
> implemented.

## Forced nicknames

`.forcenickname <user> <nickname>` stores a server-scoped rule and reapplies it when Discord reports a nickname change. The nickname from before the first change is kept for later restoration.

```headless-command Syntax theme={null}
.forcenickname <user_query> [nickname]
```

```headless-command Example theme={null}
.forcenickname @Member Blue-Team
```

```headless-command Syntax theme={null}
.unforcenickname <user_query>
```

```headless-command Example theme={null}
.unforcenickname @Member
```

```headless-command Syntax theme={null}
/forcenickname member:<member> [nickname:<nickname>]
```

```headless-command Example theme={null}
/forcenickname
```

> [!WARNING]
>
> Removing a rule restores the saved nickname, which may not be the latest
> visible name. Headless cannot reapply it if it loses `Manage Nicknames` or its
> role falls below the member.

> **Aliases, permissions, and nickname limits**
>
> The rule is reapplied best-effort when Discord reports a nickname change.
> Prefix aliases include `.fnick`, `.fn`, `.forcenick`, `.forzarnombre`,
> `.forcenames`, and `.locknick`. `.unforcenickname <user>` or
> `.forcenickname <user> off` removes the rule; omitting the nickname in the
> prefix command also removes it. `/fnick` accepts an optional nickname.
> `.forcednames` and `/forcednames` list up to 25 rules; the slash command
> responds privately. Both the caller and Headless need `Manage Nicknames`.
> Nicknames are limited to 32 characters and cannot target the server owner or
> the bot. The rule and original nickname are stored per server.

## Manual role management

`.role @user @role` toggles a role. Individual changes validate the member and role, and create a case and log when applied.

`.role add` accepts multiple roles separated by commas, semicolons, `|`, or `+`; a trailing `--reason <text>` records the reason. The subcommand parses this from its free-form payload rather than as a command-framework argument.

#### `.role`

```headless-command Syntax theme={null}
.role [rest]
```

```headless-command Example theme={null}
.role @Member @Helper
```

```headless-command Syntax theme={null}
/role user:<user> role:<role> [reason:<reason>]
```

```headless-command Example theme={null}
/role
```

#### `.role add`

```headless-command Syntax theme={null}
.role add <rest>
```

```headless-command Example theme={null}
.role add @Member Helper, Trial --reason Access approved
```

#### `.roleall`

```headless-command Syntax theme={null}
.roleall [role_query]
```

```headless-command Example theme={null}
.roleall @Verified
```

**Note:**

Role changes require the moderator's `Manage Roles` (native or through
compatible Fake Permissions) and Headless's native `Manage Roles`. Hierarchy
still applies; `@everyone` and integration-managed roles cannot be changed.
Roles with `Administrator` require native `Administrator`, the server owner,
or the Headless owner.

> [!CAUTION]
>
> `.rolesadmin delete` deletes the server role and may remove it from every
> member who has it; the callback has no confirmation or case/log flow. Verify
> the role before running it.

**Additional warning:**

`.roleall` changes many members without confirmation and only scans members
available in the cache. It skips bots, members who already have the role, the
owner, and targets outside the hierarchy; it reports additions, skips, and
failures. The prefix command has a 30-second per-server cooldown; `/roleall`
does not register that cooldown.

> **`.rolesadmin` variants**
>
> The group provides `add`, `remove`, `toggle`, `list`, and `delete`; `.ra` /
> `.roleadd` add roles, and `.roleremove` / `.removerol` remove them. See
> [Roles](/docs/en/server/roles.md) for restoration and member self-service panels.

## Bulk actions and hardban

> **Mass timeouts and unban**
>
> `.cleartimeouts [reason]` and `/cleartimeouts reason:...` clear active timeouts and process members available in the current cache in batches.
> Both the moderator and Headless
> need `Moderate Members`. It skips targets outside the moderator's hierarchy,
> writes a summary log, and may partially complete; it does not roll back
> actions already applied.

> **Unban and hardban**
>
> `.unban <ID> [reason]` and `/unban user_id:<ID> reason:...` need a numeric ID
> and `Ban Members` from both the caller and Headless. Regular unban is blocked
> for a member on the persistent hardban list. `.hardban` requires `Ban
>         Members` and Anti-Nuke Admin access; it presents approve/reject controls and
> checks hierarchy. Confirming deletes up to seven days of messages and
> reapplies the ban if someone unbans the user while the record is active.
> Use `.hardban remove <ID>` to remove the record and unban the user; if
> Discord returns a permission or HTTP error, Headless restores the record. `.unban` is not a
> substitute. For a normal removal: `.unban 123456789012345678 reason`.

### Recreate a channel with `.nuke`

> [!WARNING]
>
> `.nuke` clones the current text channel and, after confirmation, deletes the
> original. Message history is not copied and this action cannot be undone.
> Headless posts the literal `first` message in the replacement channel after
> recreating it.

The caller needs `Manage Channels` and Anti-Nuke Admin access (the server owner
also passes that gate). Headless needs `Manage Channels`, `View Channel`, and
`Send Messages`; the prefix command also checks that Headless has `Manage
Messages`. The channel is cloned with its settings and position. If a Discord
operation fails after the original is deleted, the replacement may remain even
though the command did not finish with its normal confirmation.

**1. Run it in the target channel**

Use `.nuke` inside the text channel you want to recreate. `/nuke` is also available.

**2. Review the confirmation**

Verify the target and irreversible loss of message history before choosing **Approve**.

**3. Check the replacement**

Headless keeps the channel settings, records a case and log, and does not restore previous messages.

```headless-command Syntax theme={null}
.nuke [reason]
```

```headless-command Example theme={null}
.nuke replace a compromised channel
```

## Cases and verification

`.cases @Member` lets moderators review the member's cases; `.case <ID>` shows one record. For operational follow-up, check the caller's and Headless's native permissions, then review the log after acting.

> [!NOTE]
>
> The public text prefix is `.`. The [Commands catalog](https://headlesslabs.xyz/commands/) keeps the registered syntax and aliases; its 45 Moderation entries were checked against the current registry and callbacks.

## Related pages

* [Headless permissions](/docs/en/permissions.md)
* [Anti-Nuke](/docs/en/security/anti-nuke.md)
* [Warnings](/docs/en/security/warnings.md)
* [Jail](/docs/en/security/jail.md)
* [Cases](/docs/en/moderation/cases.md)
* [Channels and lockdown](/docs/en/server/channels.md)
* [Message variables](/docs/en/resources/scripting/variables.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.