Telegram Cleaner

Professional Telegram channel and group cleaner for power users who want a fast CLI, reusable library API, and Telegram-controlled command mode. telegram-cleaner uses your own Telegram account through a userbot session, supports safe batch deletion, handles FloodWait retries, and keeps you informed with live progress updates.

Why Telegram Cleaner

• Installable from PyPI as telegram-cleaner
• Polished CLI with interactive channel selection
• First-run setup wizard with automatic .env creation
• Reuses your saved Telegram session on future runs
• Deletes in batches of 100 for speed and stability
• Falls back to per-message deletion if a batch fails
• Supports Telegram command mode from your own account only
• Writes logs to telegramcleaner.log for easier troubleshooting
• Importable as a Python library for scripting and automation

Installation

pip install telegram-cleaner

You need:

• Python 3.10+
• A Telegram account with permission to delete messages in the target chat
• Telegram API credentials from https://my.telegram.org

First Run

Run the CLI:

telegramcleaner

If .env is missing, Telegram Cleaner automatically launches the setup wizard, asks for:

• Telegram API ID
• Telegram API HASH
• Session name (default: telegramcleaner)

It then saves your credentials to .env and reuses your session on the next run.

If your credentials are wrong, the CLI shows:

Invalid Telegram API credentials. Get them from https://my.telegram.org

Usage

With no command, the CLI defaults to interactive list mode:

telegramcleaner
telegramcleaner list

Direct commands:

telegramcleaner deleteall @channel
telegramcleaner da @channel
telegramcleaner delete 1000 @channel
telegramcleaner d 1000 @channel
telegramcleaner clean @channel
telegramcleaner c @channel
telegramcleaner command-mode

deleteall, da, clean, and the interactive list flow ask for confirmation before deleting everything.

CLI Commands

Command	Alias	Description
list	telegramcleaner default	Show admin channels/groups, let you pick one, then clean it
deleteall @channel	da @channel	Delete everything from a specific channel or group
delete N @channel	d N @channel	Delete the most recent N messages
clean @channel	c @channel	Shortcut for full cleanup
command-mode	-	Control cleanup through Telegram messages

Interactive Channel Listing

list fetches your dialogs, filters for channels and groups where your account has admin rights, and shows them in a numbered menu:

[1] @channel1
[2] My Private Channel
[3] Team Archive

Choose a number, confirm the action, and the cleanup starts immediately.

Telegram Command Mode

Start command mode:

telegramcleaner command-mode

Then send commands from your own Telegram account. Only your own outgoing messages are accepted.

Supported commands:

• deleteall / da
• delete N / d N
• clean @channel / c @channel
• status / s
• pause / p
• resume / r
• stop / x
• help / h

Command mode provides live progress updates and supports safe pause, resume, and stop controls while a cleanup is running.

Demo Examples

Interactive listing:

> telegramcleaner list
Available Admin Channels
[1] @channel1
[2] My Private Channel
Select channel number (or q to cancel): 2
Are you sure you want to delete all messages from My Private Channel? (y/n): y
Cleaning My Private Channel

Delete the last 1000 messages:

telegramcleaner delete 1000 @channel

Telegram command mode:

You -> d 500
Telegram Cleaner -> Cleanup in progress
State: running
Channel: @channel
Deleted: 300
Failed: 0
Total: 500
Progress: 60.00%

Library Usage

import asyncio

from telegramcleaner import TelegramCleaner, configure_logging, load_config


async def main() -> None:
    configure_logging(log_level="INFO")
    config = load_config()
    cleaner = TelegramCleaner(config)

    try:
        await cleaner.start()
        result = await cleaner.clean_channel("@channel")
        print(result)
    finally:
        await cleaner.stop()


asyncio.run(main())

See examples/example_usage.py for a complete example.

Logging

Telegram Cleaner writes runtime logs to telegramcleaner.log and keeps terminal output focused on progress, confirmation prompts, and results.

Build And Publish

pip install build twine
python -m build
twine upload dist/*

For token-based publishing, configure your PyPI API token in .pypirc.

Post-Publish Test

Fresh-install smoke test:

pip install telegram-cleaner
telegramcleaner list

Verify:

• Login prompt appears on the first authenticated run
• Existing sessions are reused on later runs
• Interactive listing works
• Cleanup commands execute successfully
• Command mode responds to your own account only

Roadmap

• Multi-channel queue execution
• Resume checkpoints for interrupted runs
• Standalone Windows .exe build
• Richer terminal theming and release demos

Author

GitHub: https://github.com/dtvanshulll

Telegram: https://t.me/dtvanshul

License

MIT License. See LICENSE.