tg-cli knowledge
Local-first Telegram sync, search, and export via MTProto
tg is a CLI for Telegram that syncs messages into a local SQLite database via MTProto. Search, analyze, and export your Telegram conversations — all locally and offline-capable.
Features
- Sync Telegram dialogs into local SQLite for fast offline queries
- Full-text and regex search with chat, sender, and time filters
- View recent messages, today’s activity, top senders, and timelines
- Export messages in text, JSON, or YAML formats
- Near-real-time cache with
tg listen --persist - Send messages to any chat from the terminal
- Structured output (JSON/YAML) for AI agent integration
Install
uv: uv tool install kabi-tg-clipipx: pipx install kabi-tg-cliCommands
| Command | Syntax | Description |
|---|---|---|
refresh | tg refresh | Refresh all current dialogs |
sync | tg sync <chat_name> | Sync a specific chat's messages |
search | tg search <keyword> | Full-text search across synced messages |
recent | tg recent --hours 24 --limit 20 | View recent messages within a time window |
today | tg today --sync-first | View today's messages with optional sync |
export | tg export <chat_name> -f yaml -o messages.yaml | Export messages to file |
send | tg send <chat_name> <message> | Send a message to a chat |
Links
Agent Usage Example
Use cases:
- Search and retrieve Telegram conversations by keyword
- Analyze messaging patterns and top senders
- Export chat history for archival or analysis
Example workflow:
tg refresh && tg search 'meeting' --hours 48 --yaml