Metadata-Version: 2.4
Name: dtvanshul-telegram-cleaner
Version: 0.1.1
Summary: Powerful Telegram channel cleaner CLI with userbot control, batch deletion, and progress tracking.
Author: dtvanshulll
License-Expression: MIT
Project-URL: Homepage, https://github.com/dtvanshulll/Telegram_cleaner
Project-URL: Repository, https://github.com/dtvanshulll/Telegram_cleaner
Project-URL: Issues, https://github.com/dtvanshulll/Telegram_cleaner/issues
Keywords: telegram,userbot,automation,cleaner
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: colorama>=0.4.6
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: telebridge
Requires-Dist: tqdm>=4.62.3
Provides-Extra: publish
Requires-Dist: build>=1.2.2; extra == "publish"
Requires-Dist: twine>=6.1.0; extra == "publish"
Dynamic: license-file

# Telegram Cleaner

![Python](https://img.shields.io/badge/python-3.10%2B-blue)
![License](https://img.shields.io/badge/license-MIT-green)

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

```bash
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:

```bash
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:

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

## Usage

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

```bash
telegramcleaner
telegramcleaner list
```

Direct commands:

```bash
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:

```text
[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:

```bash
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:

```text
> 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:

```bash
telegramcleaner delete 1000 @channel
```

Telegram command mode:

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

## Library Usage

```python
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

```bash
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:

```bash
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`.
