telegram-tools

A local CLI for operating your own Telegram chats: find the real IDs of your groups, channels, and forum topics, search and export messages, and clear all messages out of forum topics without destroying the topics themselves.

Built on Telethon. Everything runs on your machine with your own Telegram API credentials — no server, no third party, nothing leaves your computer except the Telegram API calls you asked for.

What it does

• discover — lists your chats, channels, and forum groups with their exact numeric IDs and every forum topic ID. The fastest way to answer "what is this chat's -100… ID and what are its topic IDs?"
• search — searches messages by text, sender, date range, or topic, and prints a table or exports JSON/CSV.
• clear-messages — deletes all messages inside selected forum topic(s) while preserving the topics and their IDs. Dry-run by default; deleting requires both --execute and typing DELETE at a prompt.
• doctor — checks your local setup without printing any secrets.

What it doesn't do (on purpose)

• No deleting or creating forum topics — topic IDs never change.
• No media downloads.
• No sending messages, no bots, no automation loops.
• No cloud anything — credentials and session files stay in ~/.telegram-tools/.

Install

pipx install telegram-tools
# or
uv tool install telegram-tools

Or from source: pipx install git+https://github.com/banozz0/telegram-tools.git

Requires Python 3.11+.

Setup: your Telegram API credentials

The tool logs in as you (a user account, not a bot), so it needs a Telegram API key. One-time, about two minutes:

1. Open https://my.telegram.org/apps and log in with your Telegram phone number.
2. Fill in the short "Create new application" form (any name/short name works; platform "Desktop").
3. Copy the App api_id (a number) and App api_hash (a hex string).
4. Store them where the tool can find them:

mkdir -p ~/.telegram-tools
cat > ~/.telegram-tools/.env <<'EOF'
TELEGRAM_API_ID=123456
TELEGRAM_API_HASH=your-api-hash-here
EOF

Shell environment variables and a .env in the current directory also work, and win over ~/.telegram-tools/.env.

Treat the api_hash like a password. The first command you run starts Telethon's interactive login (phone number + code from Telegram); the resulting session file is stored in ~/.telegram-tools/ and reused afterwards. Log out anytime by deleting the session file in that directory (your .env can stay) — the session also shows under Telegram's Settings → Devices.

30 seconds of usage

# What are my chats and their IDs?
telegram-tools discover            # admin/managed chats only
telegram-tools discover --all      # everything

# Search a group
telegram-tools search --chat @mygroup --contains deploy

# Export a topic to JSON
telegram-tools search --chat @mygroup --topic 141 --output topic-141.json

# Clear a topic (dry-run first — this is the default)
telegram-tools clear-messages --chat @mygroup --topic 141
# Actually delete: needs --execute AND typing DELETE at the prompt
telegram-tools clear-messages --chat @mygroup --topic 141 --execute

Running telegram-tools with no arguments opens an interactive menu with the same operations.

discover output looks like:

Forum Groups
============
Example Forum
Chat ID: -1001234567890
Type: Forum Group
Admin: yes

Topics
--------------------------------------------
141   Deploys
217   Support
16    General

Safety model

clear-messages also verifies you actually hold the delete-messages permission in the chat before doing anything, skips topic starter messages, and handles Telegram flood-wait limits automatically.

Status

Stable for its three jobs; used regularly by its author. This is a solo project whose code was written by AI agents under review — issues are welcome, fixes are best-effort, and there is no support promise.

License

MIT. See LICENSE.