Repository navigation
Better-TG-CLI v0.38.0
The whole Telegram client API is now usable from the command line, by people and by agents (#47, #61).
Highlights
A dedicated command for every Telegram API method
- All 823 TL schema methods (layer 229) are commands of the form
telegram <namespace> <method>, generated from the schema. Examples:telegram messages get-history --peer @x --limit 20,telegram account get-authorizations,telegram help get-config. Root methods are top-level commands, e.g.telegram ping. - One typed
--flagper parameter (numbers, big integers, Bool, switch flags, bytes, lists, JSON for complex types).--json-paramscovers anything else. Peers accept an ID,@username,meor a chat title. Paging fields default to 0. Output is JSON. - Self-describing: descriptions from core.telegram.org for 783/823 methods and their params.
telegram <ns> --helpmarks each method[read],[write]or[refused].telegram <ns> <method> --helpshows the description, access, return type, params, an example, common errors and the docs link. telegram schema [<ns> [<method>]]prints the same information as JSON for agents.- Existing commands are unchanged. Where a namespace has the same name as an existing command (
stats,stories,contacts,auth,folders,help), the methods become its subcommands and are picked only on an exact method name.
Generic api command
telegram api <namespace.Method> --params '<json>'calls any TL method with JSON params.
Safety
- Raw calls (
apiand the per-method commands) use the same rules. Reads run freely. Writes needtelegram write-access on(telegram_writeover MCP). - Always refused: login/session management, session termination, 2FA/password/phone/email changes, takeout and Passport, logging into websites, ownership transfer, account deletion, spending money, and sharing your phone number or location.
- MCP: no new tools. API commands go through
telegram_read/telegram_writebased on the method. A bare help request is a read and never runs the method.
Statistics
--full(alias--stats) onread,get,search,inbox,watch,scheduledand the MCP read tool adds full per-message stats: views, forwards, reactions, replies, edit date, author, forward/reply headers, and media metadata. Default output is unchanged.- New
telegram stats <chat>: chat statistics, broadcast and megagroup stats,--graphs, and per-message or per-story stats (--message,--story).
New curated commands
drafts, admin-log, profile-photos, pin-chat/unpin-chat, mark-unread, delete-dialog, permissions, edit-permissions, scheduled, sessions, stars, invites (--requests), topic create|edit|close|reopen|pin|unpin.
Coverage tracking
docs/api-coverage.mdand a CI gate (npm run coverage:api): reachability ≥ 90%, Telethon 1.45.0 parity ≥ 90%, and a dedicated command for 100% of TL methods. Today it is 823/823, 67/67 and 823/823.
Skill / docs
- The agent skill has a discovery workflow (curated commands first, then namespace help, method help, call), peer formats, paging, common errors (FLOOD_WAIT, etc.) and an index of all namespaces.
Size
npm package dist/telegram.mjs: ~465 KB → ~550 KB, most of it the method descriptions. Startup time is unchanged.
What's Changed
- Update next with v0.37.0 by @TheVilfer in #57
- Add full Telegram client API coverage: a command per TL method, generic api command, --full stats, stats command (#47) by @TheVilfer in #61
- Release v0.38.0 by @TheVilfer in #62
Full Changelog: v0.37.0...v0.38.0