better-tg-cli

<div align="center"> <picture> <source srcset="https://raw.githubusercontent.com/TheVilfer/better-tg-cli/main/assets/banner-dark.png" media="(prefers-color-scheme: dark)"/> <source srcset="https://raw.githubusercontent.com/TheVilfer/better-tg-cli/main/assets/banner-light.png" media="(prefers-color-scheme: light)"/> <img src="https://raw.githubusercontent.com/TheVilfer/better-tg-cli/main/assets/banner-light.png" alt="Better-TG-CLI"/> </picture>

<p> <a href="#install">Install</a> · <a href="skills/better-tg-cli/reference.md">Reference</a> · <a href="SECURITY.md">Security</a> · <a href="https://github.com/TheVilfer/better-tg-cli/issues">Issues</a> · <a href="README.ru.md">Русский</a> · <a href="README.es.md">Español</a> </p> </div>

https://github.com/user-attachments/assets/d143f7c7-7d50-439c-b373-cbcbff5a6675

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, any OS

On Windows (experimental), with Scoop or npm:

scoop bucket add thevilfer https://github.com/TheVilfer/scoop-bucket
scoop install better-tg-cli

The Windows telegram.exe is not code-signed, so SmartScreen may warn about the release download.

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:

| Where | What you get | Install | |---|---|---| | Homebrew | standalone binary | brew install thevilfer/tap/better-tg-cli | | npm | CLI and MCP server (Node 20+) | npm install -g better-tg-cli | | Scoop (Windows, experimental) | standalone telegram.exe | scoop bucket add thevilfer https://github.com/TheVilfer/scoop-bucket then scoop install better-tg-cli | | GitHub Releases | binaries and SHA256SUMS | download by hand | | Claude Code plugin | skill and MCP server | see below | | Claude Desktop extension | MCP server, runs on Claude's built-in Node | download .mcpb and open it | | Grok Build plugin | skill and MCP server | see below | | Gemini CLI extension | skill and MCP server | gemini extensions install https://github.com/TheVilfer/better-tg-cli | | Cursor, VS Code | MCP server | one-click buttons | | Grok Bot | MCP server over HTTP from your Mac | see below | | The CLI itself | agent skill for Claude Code, Codex, Cursor, Gemini CLI and 7 more | telegram skill install | | skills.sh | agent skill for any shell agent | npx skills add TheVilfer/better-tg-cli | | MCP Registry | MCP server entry io.github.TheVilfer/better-tg-cli | through your MCP client |

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.

Codex plugin

The same skill and MCP server as a Codex plugin (also shows up in the ChatGPT desktop app):

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

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 a login key 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 login key, 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.

With a login key. You don't need your own keys with a login key. Get one at better-tg-cli.com (confirm your email with a code; the page also has an install guide), or from the maintainer. Run telegram auth --login-key --qr and paste the key, or pass it as TG_LOGIN_KEY=… or --login-key -. The login service (broker/) hands out the app's keys once, for this login only. The api_hash is not kept on your machine. Login keys are personal, work on up to 3 computers, and can be revoked. Before 0.37 the key was called an invite: --invite and TG_INVITE still work.

The session is stored in the macOS Keychain (service tg-cli), or in 1Password with --op-vault <vault>. telegram logout removes it. On Linux it goes to the Secret Service (GNOME Keyring, KWallet, KeePassXC) through secret-tool, which needs the libsecret-tools package. A session already saved in the config file moves there automatically. Without any secret store, the session is kept in ~/.config/tg/config.json5 (mode 0600) and write commands stay disabled. On Linux, write-access on is confirmed at a terminal prompt. On Windows the secrets live in %APPDATA%\tg\secrets.dpapi, encrypted with DPAPI for your Windows user (only you on this machine can decrypt it), and write-access on asks in a Yes/No window when there's no terminal.

Usage

telegram chats --type channel                 # one line per chat, ID first
telegram read "Chat" --since 1h               # exa