better-tg-cli 0.25.1 → 0.26.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +51 -2
  2. package/README.ru.md +51 -2
  3. package/dist/telegram.mjs +1 -1
  4. package/package.json +1 -1
  5. package/skills/better-tg-cli/reference.md +3 -1
package/README.md CHANGED
@@ -41,6 +41,8 @@ $ telegram read @alice -n 1 --json
41
41
  > use Telegram yourself, keep writes off unless you need them, and read [SECURITY.md](SECURITY.md)
42
42
  > before letting an agent write. The authors are not responsible for restricted accounts.
43
43
 
44
+ **Contents:** [Why this fork](#why-this-fork) · [Install](#install) · [Log in](#log-in) · [Usage](#usage) · [MCP server](#mcp-server) · [FAQ](#faq) · [Development](#development) · [Privacy](#privacy) · [License](#license)
45
+
44
46
  ## Why this fork
45
47
 
46
48
  A fork of [skillhq/telegram](https://github.com/skillhq/telegram), reworked for agents:
@@ -89,6 +91,7 @@ Every channel ships the same version from one release:
89
91
  | Gemini CLI extension | skill and MCP server | `gemini extensions install https://github.com/TheVilfer/better-tg-cli` |
90
92
  | Cursor, VS Code | MCP server | [one-click buttons](#mcp-server) |
91
93
  | Grok Bot | MCP server over HTTP from your Mac | [see below](#grok-bot-remote-mcp-over-http) |
94
+ | The CLI itself | agent skill for Claude Code, Codex, Cursor, Gemini CLI and 7 more | `telegram skill install` |
92
95
  | [skills.sh](https://skills.sh) | agent skill for any shell agent | `npx skills add TheVilfer/better-tg-cli` |
93
96
  | [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 |
94
97
 
@@ -119,7 +122,18 @@ grok plugin marketplace add TheVilfer/better-tg-cli && grok plugin install bette
119
122
  The skill ([`skills/better-tg-cli`](skills/better-tg-cli/SKILL.md)) teaches any agent with a shell
120
123
  (Claude Code, Codex, Cursor, Gemini CLI, OpenCode and others) to use the CLI safely. It checks the
121
124
  setup, never logs in on its own, keeps writes behind your approval, and avoids ban-prone patterns.
122
- Install it with the [skills](https://skills.sh) CLI:
125
+ The CLI carries the skill and installs it itself, so it always matches your version:
126
+
127
+ ```bash
128
+ telegram skill install # every supported agent found on this machine
129
+ telegram skill install -a claude-code codex
130
+ telegram skill status # installed, outdated, linked or missing, per agent
131
+ ```
132
+
133
+ It knows Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Grok Build, OpenCode, Goose,
134
+ Droid, Windsurf and Pi (`telegram skill status` lists the folders). Run it again after
135
+ `telegram update` to refresh the skill. A skill folder that is a symlink is left alone unless you
136
+ pass `--force`. For other agents, use the [skills](https://skills.sh) CLI:
123
137
 
124
138
  ```bash
125
139
  npx skills add TheVilfer/better-tg-cli # pick agents interactively
@@ -135,7 +149,9 @@ npx skills add TheVilfer/better-tg-cli -g -a claude-code -a codex -y
135
149
  `telegram auth` asks for your phone number and a login code instead. If the QR won't scan on a
136
150
  light terminal theme, run with `TG_QR_INVERT=1`.
137
151
 
138
- **With an invite.** If the maintainer gave you an invite token, you don't need your own keys.
152
+ **With an invite.** You don't need your own keys with an invite token. Get one at
153
+ [better-tg-cli.com](https://better-tg-cli.com) (confirm your email with a code; the page is in Russian
154
+ and also has an install guide), or from the maintainer.
139
155
  Run `telegram auth --invite --qr` and paste the token, or pass it as `TG_INVITE=…` or `--invite -`. The
140
156
  invite service (`broker/`) hands out the app's keys once, for this login only. The `api_hash` is not
141
157
  kept on your machine. Invites are personal, allow a limited number of logins, and can be revoked.
@@ -230,6 +246,39 @@ tunnel URL plus `/mcp` (for example `https://<machine>.<tailnet>.ts.net/mcp`) an
230
246
  for your tailnet first. A `cloudflared` quick tunnel gets a new URL on every start. Read "Remote
231
247
  MCP over HTTP" in [SECURITY.md](SECURITY.md) first.
232
248
 
249
+ ## FAQ
250
+
251
+ **Will Telegram ban my account?**
252
+ Using your own account from a third-party client is allowed by the [Telegram API terms](https://core.telegram.org/api/terms). What gets accounts limited is behaviour that looks like a bot: bulk messaging, mass joins or invites, spam, and brand-new accounts doing a lot at once. Use it the way you would use Telegram yourself. The skill tells agents to avoid these patterns.
253
+
254
+ **Is this a bot?**
255
+ No. It logs in as you over MTProto, like Telegram Desktop, and sees exactly what you see. Bots can't read your chats; this can.
256
+
257
+ **Can an agent send messages on its own?**
258
+ Only after you turn writes on. `telegram write-access on` asks you to confirm in the terminal or in a macOS dialog, which an agent can't answer. Writes then need an exact chat, and each one is logged. Over MCP, writing is a separate tool that clients can ask you to approve every time. Details are in [SECURITY.md](SECURITY.md).
259
+
260
+ **Does reading mark messages as read?**
261
+ No. `read`, `inbox` and `search` leave chats unread. Only `telegram mark-read` marks them.
262
+
263
+ **Do I need my own API keys?**
264
+ Yes, from [my.telegram.org/apps](https://my.telegram.org/apps). They are free and take a minute to create. With an invite from [better-tg-cli.com](https://better-tg-cli.com), `telegram auth --invite --qr` logs you in without them.
265
+
266
+ **Where is my session stored, and who can see my messages?**
267
+ The session is in the macOS Keychain, the Linux Secret Service or 1Password. The CLI talks to Telegram directly and has no analytics. The only other hosts are npm for a daily version check and the invite service at login. See [PRIVACY.md](PRIVACY.md).
268
+
269
+ **Can I use several accounts?**
270
+ Yes, with `TG_PROFILE`: each profile has its own login, config and Keychain items, for example `TG_PROFILE=work telegram auth --qr`. Switching accounts properly is tracked in [#5](https://github.com/TheVilfer/better-tg-cli/issues/5).
271
+
272
+ **Does it work on Windows?**
273
+ Not yet. It is built and tested on macOS and Linux, and relies on their secret stores.
274
+
275
+ **Can I use it from Grok Bot, ChatGPT or another cloud agent?**
276
+ Cloud agents can't start a program on your computer, so run the MCP server over HTTP and reach it through a tunnel. See [Grok Bot](#grok-bot-remote-mcp-over-http).
277
+
278
+ **How do I update?**
279
+ Run `telegram update`. It uses the same channel you installed from: Homebrew, npm or a release binary.
280
+ If you installed the agent skill with `telegram skill install`, run that again to refresh it.
281
+
233
282
  ## Development
234
283
 
235
284
  [DEVELOPMENT.md](DEVELOPMENT.md) covers:
package/README.ru.md CHANGED
@@ -40,6 +40,8 @@ $ telegram inbox -n 3
40
40
  > она не нужна. Прежде чем разрешать агенту писать, прочитайте [SECURITY.md](SECURITY.md). Авторы
41
41
  > не отвечают за ограниченные аккаунты.
42
42
 
43
+ **Содержание:** [Чем этот форк лучше](#чем-этот-форк-лучше) · [Установка](#установка) · [Вход](#вход) · [Использование](#использование) · [MCP-сервер](#mcp-сервер) · [FAQ](#faq) · [Разработка](#разработка) · [Приватность](#приватность) · [Лицензия](#лицензия)
44
+
43
45
  ## Чем этот форк лучше
44
46
 
45
47
  Это форк [skillhq/telegram](https://github.com/skillhq/telegram), переделанный под агентов:
@@ -88,6 +90,7 @@ npm install -g better-tg-cli # Node >= 20
88
90
  | Расширение Gemini CLI | скилл и MCP-сервер | `gemini extensions install https://github.com/TheVilfer/better-tg-cli` |
89
91
  | Cursor, VS Code | MCP-сервер | [кнопки в один клик](#mcp-сервер) |
90
92
  | Grok Bot | MCP-сервер по HTTP с вашего Mac | [см. ниже](#grok-bot-удалённый-mcp-по-http) |
93
+ | Сам CLI | скилл для Claude Code, Codex, Cursor, Gemini CLI и ещё 7 агентов | `telegram skill install` |
91
94
  | [skills.sh](https://skills.sh) | скилл для любого агента с шеллом | `npx skills add TheVilfer/better-tg-cli` |
92
95
  | [MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=better-tg-cli) | запись MCP-сервера `io.github.TheVilfer/better-tg-cli` | через ваш MCP-клиент |
93
96
 
@@ -118,7 +121,18 @@ grok plugin marketplace add TheVilfer/better-tg-cli && grok plugin install bette
118
121
  Скилл ([`skills/better-tg-cli`](skills/better-tg-cli/SKILL.md)) учит любого агента с шеллом
119
122
  (Claude Code, Codex, Cursor, Gemini CLI, OpenCode и других) безопасно работать с CLI. Он проверяет
120
123
  установку, никогда не входит сам, держит запись под вашим подтверждением и обходит действия, за
121
- которые банят. Ставится через CLI [skills](https://skills.sh):
124
+ которые банят. Скилл лежит внутри CLI, и CLI ставит его сам, поэтому версии всегда совпадают:
125
+
126
+ ```bash
127
+ telegram skill install # во все поддерживаемые агенты на этой машине
128
+ telegram skill install -a claude-code codex
129
+ telegram skill status # по каждому агенту: стоит, устарел, симлинк или нет
130
+ ```
131
+
132
+ Поддерживаются Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Grok Build, OpenCode,
133
+ Goose, Droid, Windsurf и Pi (папки показывает `telegram skill status`). После `telegram update`
134
+ запустите команду ещё раз, чтобы обновить скилл. Папку-симлинк команда не трогает без `--force`.
135
+ Для остальных агентов есть CLI [skills](https://skills.sh):
122
136
 
123
137
  ```bash
124
138
  npx skills add TheVilfer/better-tg-cli # агенты выбираются интерактивно
@@ -134,7 +148,9 @@ npx skills add TheVilfer/better-tg-cli -g -a claude-code -a codex -y
134
148
  Обычный `telegram auth` вместо QR спрашивает номер телефона и код. Если в светлой теме
135
149
  терминала QR не сканируется, запустите с `TG_QR_INVERT=1`.
136
150
 
137
- **По инвайту.** Если мейнтейнер дал вам инвайт-токен, свои ключи не нужны. Запустите
151
+ **По инвайту.** С инвайт-токеном свои ключи не нужны. Получите его на
152
+ [better-tg-cli.com](https://better-tg-cli.com) (почта подтверждается кодом, там же гайд по установке)
153
+ или у мейнтейнера. Запустите
138
154
  `telegram auth --invite --qr` и вставьте токен. Его также можно передать через `TG_INVITE=…` или
139
155
  `--invite -`. Сервис инвайтов (`broker/`) выдаёт ключи приложения один раз, только для этого входа.
140
156
  `api_hash` на вашей машине не сохраняется. Инвайты персональные, число входов по ним ограничено, и
@@ -231,6 +247,39 @@ tailscale funnel --bg 8787 # или: cloudflared tunnel --url h
231
247
  разрешить для вашего tailnet. Быстрый туннель `cloudflared` при каждом запуске получает новый
232
248
  адрес. Сначала прочитайте раздел «Remote MCP over HTTP» в [SECURITY.md](SECURITY.md).
233
249
 
250
+ ## FAQ
251
+
252
+ **Не забанит ли Telegram мой аккаунт?**
253
+ [Условия Telegram API](https://core.telegram.org/api/terms) разрешают пользоваться своим аккаунтом через сторонние клиенты. Ограничения получают за поведение, похожее на бота: массовые рассылки, массовые вступления и приглашения, спам, активность только что созданного аккаунта. Пользуйтесь так же, как пользовались бы самим Telegram. Скилл учит агентов обходить эти сценарии.
254
+
255
+ **Это бот?**
256
+ Нет. CLI входит от вашего имени по MTProto, как Telegram Desktop, и видит ровно то же, что и вы. Боты не читают ваши чаты, а этот клиент читает.
257
+
258
+ **Может ли агент отправлять сообщения сам?**
259
+ Только после того, как вы включите запись. `telegram write-access on` просит подтверждения в терминале или в диалоге macOS, на которое агент ответить не может. Дальше запись требует точно указанный чат, а каждая отправка пишется в журнал. В MCP запись вынесена в отдельный инструмент, и клиенты могут спрашивать вас перед каждым вызовом. Подробнее в [SECURITY.md](SECURITY.md).
260
+
261
+ **Отмечает ли чтение сообщения прочитанными?**
262
+ Нет. `read`, `inbox` и `search` оставляют чаты непрочитанными. Отмечает только `telegram mark-read`.
263
+
264
+ **Нужны ли свои API-ключи?**
265
+ Да, с [my.telegram.org/apps](https://my.telegram.org/apps). Они бесплатные, их создание занимает минуту. С инвайтом с [better-tg-cli.com](https://better-tg-cli.com) `telegram auth --invite --qr` войдёт без своих ключей.
266
+
267
+ **Где хранится сессия и кто видит мои сообщения?**
268
+ Сессия лежит в Keychain macOS, в Secret Service на Linux или в 1Password. CLI общается с Telegram напрямую, аналитики нет. Кроме Telegram, он ходит только в npm (раз в день за номером версии) и в сервис инвайтов при входе. Подробнее в [PRIVACY.md](PRIVACY.md).
269
+
270
+ **Можно ли несколько аккаунтов?**
271
+ Да, через `TG_PROFILE`: у каждого профиля свой вход, конфиг и записи в Keychain, например `TG_PROFILE=work telegram auth --qr`. Удобное переключение аккаунтов — в [#5](https://github.com/TheVilfer/better-tg-cli/issues/5).
272
+
273
+ **Работает ли на Windows?**
274
+ Пока нет. CLI собирается и проверяется на macOS и Linux и опирается на их хранилища секретов.
275
+
276
+ **Можно ли пользоваться из Grok Bot, ChatGPT или другого облачного агента?**
277
+ Облачный агент не может запустить программу на вашем компьютере, поэтому поднимите MCP-сервер по HTTP и откройте к нему туннель. См. [Grok Bot](#grok-bot-удалённый-mcp-по-http).
278
+
279
+ **Как обновиться?**
280
+ `telegram update`. Команда обновляет тем же способом, каким CLI был установлен: Homebrew, npm или бинарник из релиза.
281
+ Если скилл для агентов ставили через `telegram skill install`, запустите её ещё раз, чтобы обновить скилл.
282
+
234
283
  ## Разработка
235
284
 
236
285
  В [DEVELOPMENT.md](DEVELOPMENT.md) описаны: