telegram_grep

Search Telegram messages from the command line.

By default telegram-grep searches private one-to-one human chats only. It skips groups, channels, and bot dialogs unless you opt in.

Install

python -m pip install .

For development:

python -m pip install -e '.[dev]'

Authentication

This uses Telegram MTProto through Telethon, not the Bot API. A Telegram bot token cannot search your personal private chats.

Required environment:

export TG_API_ID=123456
export TG_API_HASH=0123456789abcdef0123456789abcdef

Session options:

# Recommended for automation: Telethon StringSession token.
export TG_SESSION='...'

# Or a local session file. Default: ./telegram_grep.session
export TG_SESSION_FILE=/path/to/telegram_grep.session

If neither session option exists, Telethon will create/use telegram_grep.session and may prompt interactively for login. You can also set TG_PHONE for the first login.

Usage

Search private human chats:

telegram-grep 'wikimedia commons bot'

Include groups:

telegram-grep --groups 'wikimedia commons bot'

Search only groups:

telegram-grep --groups-only 'wikimedia commons bot'

Include bot private dialogs:

telegram-grep --include-bots 'wikimedia commons bot'

Print JSON Lines:

telegram-grep --json 'wikimedia commons bot'

Show neighboring messages:

telegram-grep --context 2 'wikimedia commons bot'

Related Documentation

• Telethon documentation
• Telethon sessions
• Telegram API development tools
• Telegram MTProto API
• PyPI Trusted Publishing

Publishing

CI publishes to PyPI on every push to main after tests pass.

PyPI must have a Trusted Publisher configured for:

• owner/repository: vitaly-zdanevich/telegram_grep
• workflow: .github/workflows/ci.yml
• environment: pypi

Versions are derived from Git tags/commits through hatch-vcs, because PyPI does not allow re-uploading the same version.