slack-cleaner-node

slack-cleaner-node is a flag-driven Node.js CLI for safely finding and deleting Slack messages across channels, groups, and conversations, with dry-run by default, rich text-pattern matching, and retry-aware rate limiting.

Safety model

• Default mode is dry-run.
• Use --perform to actually delete messages.
• Use --limit to cap deletions while validating filters.

Install

Install from npm (published package):

npm install -g slack-cleaner

Alternatively check out the repo:

gh repo clone mcdado/slack-cleaner-node
cd slack-cleaner-node
npm link

Then run:

slack-cleaner --help

Slack token and scopes

Use a token that can read history and delete the target messages.

This CLI auto-loads a .env file from your current working directory. If not present there, it also checks .env in the installed package directory (useful when running a globally linked install via npm link).

Token setup by install mode:

• npm link (repo checked out): put token in repo .env and it will be picked up as fallback.
• npm install -g slack-cleaner (no repo checkout): use either a .env in the directory where you run slack-cleaner, shell env vars, or --token.

Create it from the example:

cp .env.example .env

Set token in .env or shell env vars:

export SLACK_BOT_TOKEN='xoxb-...'
# or
export SLACK_USER_TOKEN='xoxp-...'
# or
export SLACK_TOKEN='xoxp-...'

Or pass directly:

slack-cleaner --token xoxp-...

Typical scopes you will need depend on conversation types, for example:

• channels:history, groups:history, im:history, mpim:history
• chat:write
• users:read
• conversation listing scopes where needed

Usage

slack-cleaner --token xoxp-... [targets] [filters] [options]

Targets

• --channel <name[,name]> public channels
• --group <name[,name]> private channels
• --conversation <id[,id]> direct conversation IDs

At least one target flag is required.

Filters

• --user <username|user_id[,..]> only messages by users
• --message-type <user|bot> filter by type
• --pattern <regex> regex on message text, attachments, block text, and related textual fields
• --after <date> oldest date (ISO format supported)
• --before <date> newest date

Execution

• --perform execute deletions
• --limit <n> max matched messages to preview/delete
• --rate-limit-ms <ms> minimum delay between Slack API calls (default 250)
• --max-retries <n> retries on 429/5xx/network failures (default 6)
• --verbose detailed logs

Examples

Dry-run messages from a user in #general after Jan 1, 2024:

slack-cleaner --channel general --user alice --after 2024-01-01

Delete up to 50 bot messages matching deploy failed in a private channel:

slack-cleaner --group ops-alerts --message-type bot --pattern "deploy failed" --limit 50 --perform

Delete from known conversation ID with a slower API cadence:

slack-cleaner --conversation C12345678 --rate-limit-ms 800 --perform

Delete with more aggressive retry policy:

slack-cleaner --channel general --perform --max-retries 10

Notes

• Slack may refuse deletes for messages your token cannot remove.
• When multiple tokens are configured, delete attempts can fall back to secondary tokens on permission-related delete errors.
• Requests use retry with backoff and Retry-After when Slack responds with HTTP 429.
• If you still hit limits, increase --rate-limit-ms or reduce scope per run.
• During --perform, TTY terminals show a self-updating progress line instead of one log line per deleted message.
• Live progress includes retries_total=<n>, retries_429=<n>, and retry wait countdown wait=<seconds>s.
• Each run prints Rate limit retries: <n> and Total retries: <n> at the end.

Credits

• Inspired by slack_cleaner2 by @sgratzl.
• Built with implementation assistance from OpenAI Codex (GPT 5.3).