Skip to content

Better-TG-CLI v0.38.0

Choose a tag to compare

@github-actions github-actions released this 19 Oct 11:30
· 41 commits to main since this release
69016e7

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 --flag per parameter (numbers, big integers, Bool, switch flags, bytes, lists, JSON for complex types). --json-params covers anything else. Peers accept an ID, @username, me or 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> --help marks each method [read], [write] or [refused]. telegram <ns> <method> --help shows 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 (api and the per-method commands) use the same rules. Reads run freely. Writes need telegram write-access on (telegram_write over 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_write based on the method. A bare help request is a read and never runs the method.

Statistics

  • --full (alias --stats) on read, get, search, inbox, watch, scheduled and 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.md and 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