Telegram CLI
Project website · Telegram CLI documentation · Telegram group · 简体中文 README
Telegram CLI is a TypeScript command-line interface (CLI) for live Telegram data, local SQLite search, and remote management. It aims to be the most capable Telegram CLI for people and artificial intelligence (AI) agents that need dependable Telegram access from one tg command. Account sessions and synced messages stay on your machine.
Why Telegram CLI stands out
Telegram CLI combines online reads, local persistence, file archives, live listeners, remote writes, group administration, account isolation, a local web UI, and structured output in one tool.
It is designed for AI agents:
- Stable command contracts: finite commands support JSON, YAML, Markdown, exit statuses, and stable error codes
- Local-first data access: synced messages stay in SQLite so agents can search and analyze Telegram history without repeated network reads
- Explicit account control: --account selects the intended session for one command
- Write safety: a write-access gate separates read-only automation from commands that modify Telegram
- Agent skill support: the using-telegram-cli skill teaches supported agents how to authenticate, sync, query, and avoid unsafe writes
Read the documentation
Read the complete Telegram CLI documentation for installation, workflows, every command, automation, safety, and troubleshooting.
Choose a Telegram workflow
Choose a workflow by the data freshness you need, where the result should go, and whether the command changes Telegram.
Read current Telegram data
Use online commands when you need the latest server state. These commands do not add returned messages to SQLite.
tg inbox
tg read @team --since 2h
tg search-online "incident" --chat @team --jsonYou can also inspect contacts, notification settings, folders, and group details without importing messages.
Build a searchable local history
Sync one chat or many chats into the selected account’s SQLite database. Search and analyze the stored copy without reconnecting to Telegram.
tg sync @team
tg search "release" --chat @team
tg recent --chat @team --hours 24
tg recent --chat @team --user 123456 --limit 50 --offset 0 --json