tg-purger

Interactive CLI/TUI tool to purge Telegram supergroup messages older than a cutoff date using MTProto via gotd/td (user login, not Bot API).

Build

go build -o tg-purger .

Run

./tg-purger

Optional dry-run flag:

./tg-purger -dry-run

Optional credentials flags (avoid prompts):

./tg-purger -api-id 12345 -api-hash "your_api_hash" -phone "+1234567890"

Environment variable alternatives:

export TG_PURGER_API_ID=12345
export TG_PURGER_API_HASH="your_api_hash"
export TG_PURGER_PHONE="+1234567890"

Required permissions

• You must be a member of the target supergroup.
• You need permission to delete messages in that supergroup (e.g., admin rights for full history purges).
• You must provide your Telegram API ID and API hash (from https://my.telegram.org).

Dry run

When Dry Run is enabled, tg-purger performs the full scan and reports counts and progress, but does not issue any delete calls. The summary will show “Would delete”.

Session and log files

Files are created next to the executable:

• Session file: tg-purger.session.json
• Log file: tg-purger.log
• Optional config file (if you choose to save credentials): tg-purger.config.json

The log file contains detailed technical info (chat IDs, message IDs per batch, API call counts, flood-wait sleeps, errors).

Saving credentials

After a successful run, you can choose to save API ID, API hash, and phone in tg-purger.config.json (permissions 0600). You can also force saving by running with -save-credentials.