Better Tg Cli (Telegram)

Install · Reference · Security · Issues · Русский

An unofficial, agent-friendly command-line client for Telegram that runs on your own account (MTProto via teleproto, TL layer 229). The command is telegram: about 60 commands for reading, searching, writing, bots, groups and exports, built so that AI agents (Claude Code, Codex, …) can drive it cheaply and safely.

$ telegram inbox -n 3
48 unread in 7 chats (showing 3)
1234567890 user unread=2 Alice @alice | see you at 7?
-1001234567 supergroup muted unread=41 Rust Seattle @rust_sea | anyone tried 1.90?
-1009876543 channel unread=5 Changelog | v2.4 is out
$ telegram read @alice -n 1 --json
{"chatTitle":"Alice","messages":[{"id":812,"date":"2026-09-27T10:02:11.000Z","sender":"Alice","senderId":"1234567890","text":"see you at 7?"}]}

[!WARNING] Your account, your risk. This is an unofficial client that logs in as you. Telegram may limit or freeze accounts that behave like bots. The risk is highest for new accounts, bulk messaging, mass joins or invites, and anything that looks like spam. Use it the way you would use Telegram yourself, keep writes off unless you need them, and read SECURITY.md before letting an agent write. The authors are not responsible for restricted accounts.

Contents: Why this fork · Install · Log in · Usage · MCP server · FAQ · Development · Privacy · License

Why this fork

A fork of skillhq/telegram, reworked for agents:

• Current Telegram layer. Bot replies with rich (layer 228+) content show real text instead of (no text). You can press bot buttons (click) and walk bot menus.
• Token-efficient output. Off a TTY you get one compact line per item with the ID first, and JSON on one line with empty fields dropped. --max-text trims long posts. telegram help-all -g <word> prints every flag, generated from the code.
• Exact reads. Real pagination for --since/--until, --unread, threads and channel comments, forum topics, get by ID, search filters by type, sender or date, and me / Избранное for Saved Messages.
• Safe by default. The account is read-only until a human runs write-access on [--for 1h] and confirms it in a terminal prompt or a macOS dialog, so an agent cannot switch it on itself. Every write is logged to ~/.config/tg/audit.jsonl. Secrets live in the macOS Keychain, the Linux Secret Service or 1Password.
• Small and self-contained. The npm package is one 0.3 MB file with zero runtime dependencies. Homebrew installs a standalone binary with no Node.

Install

brew install thevilfer/tap/better-tg-cli   # standalone binary, macOS and Linux
npm install -g better-tg-cli               # Node >= 20

telegram update upgrades an existing install, whichever of these you used. On a terminal the CLI checks for new versions once a day. Agents and pipes never see that notice, and TG_NO_UPDATE_CHECK=1 turns it off.

Downloading a binary from Releases by hand on macOS? It is not notarized, so remove the quarantine flag once: xattr -d com.apple.quarantine ./telegram. Homebrew handles this for you.

Do not install @skillhq/telegram. It is the old upstream build on GramJS (layer 198).

Every channel ships the same version from one release:

Claude Code plugin

The skill and the MCP server together, in one install:

/plugin marketplace add TheVilfer/better-tg-cli
/plugin install better-tg-cli@better-tg-cli

It runs the MCP server through npx, so Node 20+ is enough. Log in once with telegram auth --qr (or npx better-tg-cli auth --qr) in a terminal.

Grok Build plugin

Grok Build installs the same plugin, skill and MCP server together:

grok plugin install TheVilfer/better-tg-cli --trust
# or add the marketplace first, then install from the /plugins menu:
grok plugin marketplace add TheVilfer/better-tg-cli && grok plugin install better-tg-cli --trust

As an agent skill

The skill (skills/better-tg-cli) teaches any agent with a shell (Claude Code, Codex, Cursor, Gemini CLI, OpenCode and others) to use the CLI safely. It checks the setup, never logs in on its own, keeps writes behind your approval, and avoids ban-prone patterns. The CLI carries the skill and installs it itself, so it always matches your version:

telegram skill install                  # every supported agent found on this machine
telegram skill install -a claude-code codex
telegram skill status                   # installed, outdated, linked or missing, per agent

It knows Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Grok Build, OpenCode, Goose, Droid, Windsurf and Pi (telegram skill status lists the folders). Run it again after telegram update to refresh the skill. A skill folder that is a symlink is left alone unless you pass --force. For other agents, use the skills CLI:

npx skills add TheVilfer/better-tg-cli          # pick agents interactively
npx skills add TheVilfer/better-tg-cli -g -a claude-code -a codex -y

Log in

Through your agent (easiest): ask it to set up Telegram, or run telegram onboard yourself. It opens a page on 127.0.0.1 where you get an invite from better-tg-cli.com (it comes back to the page by itself) or enter your own keys, scan a QR code and type your 2FA password. The agent only starts the command and waits: it never sees the invite, the QR code or the password. The page answers only on a random secret path and closes when you're done.

With your own API keys (the default):

1. Open https://my.telegram.org/apps, create an application, and copy its api_id and api_hash.
2. Run telegram auth --qr and enter them. Then, on your phone, go to Settings → Devices → Link Desktop Device and scan the QR code. Enter your 2FA password if you have one. Plain telegram auth asks for your phone number and a login code instead. If the QR won't scan on a light terminal theme, run with TG_QR_INVERT=1.