How to clear Discord messages safely with GuildPilot

GuildPilot provides /clear for one text channel and /clearmsg for one user's recent messages across accessible text channels. Both commands return a private summary and write a moderation audit record.

Before you start

• The moderator and GuildPilot both need View Channel, Read Message History and Manage Messages where deletion is attempted.
• The commands run only in a Discord server, not in direct messages.
• Decide the exact account, channel and time period before running a cleanup.

Warning: Message deletion cannot be undone. Confirm the target user and amount or period before submitting either command.

Clear messages

1. Delete messages from the current channel

Run /clear in the target text or announcement channel. amount is required from 1 to 50; user is optional.

/clear amount:20 user:@ExampleMember

When user is omitted, GuildPilot collects matching recent messages regardless of author. When it is present, only that user's messages count toward the requested amount.

2. Review the private result

GuildPilot reports how many messages were deleted and how many failed. It may say that the scan limit was reached when it could not inspect enough history to find the requested matches.

3. Delete one user's messages across the server

Use /clearmsg with the required user and period. The supported periods are 1h, 1d and 7d.

/clearmsg user:@ExampleMember period:1d

GuildPilot scans accessible text channels within its fixed safety budget. Channels it cannot read or manage are skipped rather than granting itself access.

Recommended configuration

Use /clear when the problem is limited to one channel. Reserve /clearmsg for a confirmed cross-channel incident because it inspects a wider server area.

Test the setup

1. Create a temporary staff-only text channel.
2. Post three harmless messages from a test account.
3. Run /clear amount:2 user:@TestAccount and confirm that two matching messages disappear.
4. Delete the remaining test message and remove the temporary channel if it is no longer needed.

What a successful setup looks like

Only messages matching the selected command scope are removed. The moderator receives an ephemeral completion summary, and failures in one channel do not expose or stop unrelated channels.

Common problems

GuildPilot lists missing permissions

Cause: The bot or moderator lacks View Channel, Read Message History or Manage Messages.

Fix: Grant the missing permission in the relevant channel, then rerun the command with the intended scope.

Fewer messages were removed than requested

Cause: Not enough matching messages were found inside the command's scan budget, or Discord rejected some deletions.

Fix: Check the user filter and channel, then run a smaller, targeted cleanup if appropriate.

The command is unavailable in a channel

Cause: The moderator lacks Manage Messages, application commands are disabled, or GuildPilot command restrictions block that channel.

Fix: Review the Discord permission and Settings → Command exception channels.