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>

  [![npm version](https://img.shields.io/npm/v/better-tg-cli?style=flat&colorA=000000&colorB=000000)](https://www.npmjs.com/package/better-tg-cli)
  [![CI](https://img.shields.io/github/actions/workflow/status/TheVilfer/better-tg-cli/ci.yml?branch=main&label=ci&style=flat&colorA=000000&colorB=000000)](https://github.com/TheVilfer/better-tg-cli/actions/workflows/ci.yml)
  [![npm provenance](https://img.shields.io/badge/npm-provenance-000000?style=flat&colorA=000000&colorB=000000&logo=npm)](https://www.npmjs.com/package/better-tg-cli#provenance)
  [![install size](https://img.shields.io/npm/unpacked-size/better-tg-cli?label=size&style=flat&colorA=000000&colorB=000000)](https://www.npmjs.com/package/better-tg-cli)
  [![dependencies](https://img.shields.io/badge/dependencies-0-000000?style=flat&colorA=000000&colorB=000000)](package.json)
  [![MCP](https://img.shields.io/badge/MCP-server-000000?style=flat&colorA=000000&colorB=000000)](#mcp-server)
  [![platforms](https://img.shields.io/badge/macOS%20%C2%B7%20Linux-000000?style=flat&colorA=000000&colorB=000000&logo=apple)](#install)
  [![license](https://img.shields.io/badge/license-MIT-000000?style=flat&colorA=000000&colorB=000000)](LICENSE)

  <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>
  </p>
</div>

An unofficial, agent-friendly command-line client for Telegram that runs **on your own account**
(MTProto via [`teleproto`](https://www.npmjs.com/package/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.

```console
$ 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 Moscow @rust_msk | 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](SECURITY.md)
> before letting an agent write. The authors are not responsible for restricted accounts.

## Why this fork

A fork of [skillhq/telegram](https://github.com/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

```bash
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:

| Where | What you get | Install |
|---|---|---|
| [Homebrew](https://github.com/TheVilfer/homebrew-tap) | standalone binary | `brew install thevilfer/tap/better-tg-cli` |
| [npm](https://www.npmjs.com/package/better-tg-cli) | CLI and MCP server (Node 20+) | `npm install -g better-tg-cli` |
| [GitHub Releases](https://github.com/TheVilfer/better-tg-cli/releases) | binaries and SHA256SUMS | download by hand |
| Claude Code plugin | skill and MCP server | [see below](#claude-code-plugin) |
| Claude Desktop extension | MCP server, runs on Claude's built-in Node | [download `.mcpb`](https://github.com/TheVilfer/better-tg-cli/releases/latest/download/better-tg-cli.mcpb) and open it |
| Grok Build plugin | skill and MCP server | [see below](#grok-build-plugin) |
| 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](#mcp-server) |
| Grok Bot | MCP server over HTTP from your Mac | [see below](#grok-bot-remote-mcp-over-http) |
| [skills.sh](https://skills.sh) | agent skill for any shell agent | `npx skills add TheVilfer/better-tg-cli` |
| [MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=better-tg-cli) | 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.

### Grok Build plugin

[Grok Build](https://x.ai/cli) installs the same plugin, skill and MCP server together:

```bash
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`](skills/better-tg-cli/SKILL.md)) 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.
Install it with the [skills](https://skills.sh) CLI:

```bash
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

**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 an invite.** If the maintainer gave you an invite token, you don't need your own keys.
Run `telegram auth --invite --qr` and paste the token, or pass it as `TG_INVITE=…` or `--invite -`. The
invite service (`broker/`) hands out the app's keys once, for this login only. The `api_hash` is not
kept on your machine. Invites are personal, allow a limited number of logins, and can be revoked.

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.

## Usage

```bash
telegram chats --type channel                 # one line per chat, ID first
telegram read "Chat" --since 1h               # exact range, newest first (--asc to flip)
telegram read @channel --thread 123           # comments under a post
telegram search "invoice" --chat "Work" --type document
telegram get "Chat" 812 813                   # exact messages by ID
telegram download "Chat" 812                  # save the attached file
telegram sync --chat "Chat" --output ./export --resume   # incremental markdown export

telegram write-access on --for 1h             # a human confirms this
printf '%s' "$text" | telegram send @alice -  # text from stdin, no quoting problems
telegram reply "Chat" 812 "on it" --silent
telegram click @SomeBot 4410 "Settings"       # press an inline button
```

Read commands take `--json`, and some also take `--markdown`.