better-tg-cli 0.27.0 → 0.29.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 (6) hide show
  1. package/README.md +53 -4
  2. package/README.ru.md +53 -4
  3. package/dist/telegram.mjs +1 -1
  4. package/package.json +2 -2
  5. package/skills/better-tg-cli/SKILL.md +1 -1
  6. package/skills/better-tg-cli/reference.md +1 -1
package/README.md CHANGED
@@ -66,9 +66,18 @@ A fork of [skillhq/telegram](https://github.com/skillhq/telegram), reworked for
66
66
 
67
67
  ```bash
68
68
  brew install thevilfer/tap/better-tg-cli # standalone binary, macOS and Linux
69
- npm install -g better-tg-cli # Node >= 20
69
+ npm install -g better-tg-cli # Node >= 20, any OS
70
70
  ```
71
71
 
72
+ On Windows (experimental), with [Scoop](https://scoop.sh) or npm:
73
+
74
+ ```powershell
75
+ scoop bucket add thevilfer https://github.com/TheVilfer/scoop-bucket
76
+ scoop install better-tg-cli
77
+ ```
78
+
79
+ The Windows `telegram.exe` is not code-signed, so SmartScreen may warn about the release download.
80
+
72
81
  `telegram update` upgrades an existing install, whichever of these you used. On a terminal the CLI
73
82
  checks for new versions once a day. Agents and pipes never see that notice, and
74
83
  `TG_NO_UPDATE_CHECK=1` turns it off.
@@ -84,6 +93,7 @@ Every channel ships the same version from one release:
84
93
  |---|---|---|
85
94
  | [Homebrew](https://github.com/TheVilfer/homebrew-tap) | standalone binary | `brew install thevilfer/tap/better-tg-cli` |
86
95
  | [npm](https://www.npmjs.com/package/better-tg-cli) | CLI and MCP server (Node 20+) | `npm install -g better-tg-cli` |
96
+ | [Scoop](https://github.com/TheVilfer/scoop-bucket) (Windows, experimental) | standalone `telegram.exe` | `scoop bucket add thevilfer https://github.com/TheVilfer/scoop-bucket` then `scoop install better-tg-cli` |
87
97
  | [GitHub Releases](https://github.com/TheVilfer/better-tg-cli/releases) | binaries and SHA256SUMS | download by hand |
88
98
  | Claude Code plugin | skill and MCP server | [see below](#claude-code-plugin) |
89
99
  | 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 |
@@ -107,6 +117,15 @@ The skill and the MCP server together, in one install:
107
117
  It runs the MCP server through `npx`, so Node 20+ is enough. Log in once with `telegram auth --qr`
108
118
  (or `npx better-tg-cli auth --qr`) in a terminal.
109
119
 
120
+ ### Codex plugin
121
+
122
+ The same skill and MCP server as a Codex plugin (also shows up in the ChatGPT desktop app):
123
+
124
+ ```bash
125
+ codex plugin marketplace add TheVilfer/better-tg-cli
126
+ codex plugin add better-tg-cli@better-tg-cli
127
+ ```
128
+
110
129
  ### Grok Build plugin
111
130
 
112
131
  [Grok Build](https://x.ai/cli) installs the same plugin, skill and MCP server together:
@@ -167,7 +186,9 @@ The session is stored in the macOS Keychain (service `tg-cli`), or in 1Password
167
186
  Keyring, KWallet, KeePassXC) through `secret-tool`, which needs the `libsecret-tools` package. A
168
187
  session already saved in the config file moves there automatically. Without any secret store, the
169
188
  session is kept in `~/.config/tg/config.json5` (mode 0600) and write commands stay disabled.
170
- On Linux, `write-access on` is confirmed at a terminal prompt.
189
+ On Linux, `write-access on` is confirmed at a terminal prompt. On Windows the secrets live in
190
+ `%APPDATA%\tg\secrets.dpapi`, encrypted with DPAPI for your Windows user (only you on this machine
191
+ can decrypt it), and `write-access on` asks in a Yes/No window when there's no terminal.
171
192
 
172
193
  ## Usage
173
194
 
@@ -276,7 +297,9 @@ The session is in the macOS Keychain, the Linux Secret Service or 1Password. The
276
297
  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).
277
298
 
278
299
  **Does it work on Windows?**
279
- Not yet. It is built and tested on macOS and Linux, and relies on their secret stores.
300
+ Yes, experimentally: `scoop install better-tg-cli` or npm. Secrets are stored with Windows DPAPI
301
+ and CI runs the tests on Windows, but live use there is less tested than on macOS and Linux. Please
302
+ report problems in the issues.
280
303
 
281
304
  **Can I use it from Grok Bot, ChatGPT or another cloud agent?**
282
305
  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).
@@ -293,17 +316,43 @@ If you installed the agent skill with `telegram skill install`, run that again t
293
316
  - Telegram test servers;
294
317
  - editor debugging and tests.
295
318
 
296
- Releases are cut by `scripts/release.sh patch|minor|major`. A tag builds the binaries and
319
+ Releases are cut by `scripts/release.sh patch|minor|major` (a release PR), then `scripts/release.sh tag` after the merge. A tag builds the binaries and
297
320
  publishes to GitHub Releases, npm (trusted publishing with provenance), the Homebrew tap and the
298
321
  MCP Registry. See
299
322
  [CONTRIBUTING.md](CONTRIBUTING.md).
300
323
 
324
+ ## Uninstall
325
+
326
+ 1. `telegram logout` deletes the saved session. To end it on Telegram's side too, terminate it in
327
+ Telegram → Settings → Devices.
328
+ 2. `telegram skill uninstall` removes the skill from the agents it was installed into.
329
+ 3. Remove the program: `brew uninstall better-tg-cli`, `npm uninstall -g better-tg-cli` or
330
+ `scoop uninstall better-tg-cli`. For a binary from Releases, delete `telegram` / `telegram.exe`.
331
+ 4. Delete the config folder: `~/.config/tg` (`%APPDATA%\tg` on Windows), plus `~/.config/tg-<profile>`
332
+ for any `TG_PROFILE` you used. On Windows this also removes the DPAPI secrets file. Elsewhere the
333
+ api_hash and write-access flag stay in the secret store: delete the `tg-cli` items in Keychain
334
+ Access (or `secret-tool clear service tg-cli`), or the item in your 1Password vault.
335
+
301
336
  ## Privacy
302
337
 
303
338
  No analytics. The only service we run is the optional invite broker, which never sees your
304
339
  messages or session. See [PRIVACY.md](PRIVACY.md) for the three hosts the CLI talks to and what it
305
340
  stores locally.
306
341
 
342
+ ## Code signing policy
343
+
344
+ Windows binaries are built from this repository by GitHub Actions only (`.github/workflows/release.yml`),
345
+ never on a personal machine. We have applied for free code signing from SignPath Foundation; once it
346
+ is in place, release binaries will carry: *Free code signing provided by
347
+ [SignPath.io](https://about.signpath.io), certificate by [SignPath Foundation](https://signpath.org).*
348
+ Until then the Windows `telegram.exe` is unsigned; macOS binaries are ad-hoc signed.
349
+
350
+ - Committers and reviewers: [@TheVilfer](https://github.com/TheVilfer)
351
+ - Approvers (each signed release): [@TheVilfer](https://github.com/TheVilfer)
352
+ - Privacy policy: [PRIVACY.md](PRIVACY.md). The CLI talks only to Telegram, to the invite broker
353
+ when you log in with an invite, and to the npm registry for a daily update check in a terminal
354
+ (off with `TG_NO_UPDATE_CHECK=1`).
355
+
307
356
  ## License
308
357
 
309
358
  MIT, see [LICENSE](LICENSE). Based on [skillhq/telegram](https://github.com/skillhq/telegram) by
package/README.ru.md CHANGED
@@ -65,9 +65,18 @@ $ telegram inbox -n 3
65
65
 
66
66
  ```bash
67
67
  brew install thevilfer/tap/better-tg-cli # отдельный бинарник, macOS и Linux
68
- npm install -g better-tg-cli # Node >= 20
68
+ npm install -g better-tg-cli # Node >= 20, любая ОС
69
69
  ```
70
70
 
71
+ На Windows (экспериментально) через [Scoop](https://scoop.sh) или npm:
72
+
73
+ ```powershell
74
+ scoop bucket add thevilfer https://github.com/TheVilfer/scoop-bucket
75
+ scoop install better-tg-cli
76
+ ```
77
+
78
+ `telegram.exe` для Windows не подписан, поэтому SmartScreen может предупредить при скачивании из релиза.
79
+
71
80
  `telegram update` обновляет CLI тем же способом, каким он был установлен. В терминале CLI раз в
72
81
  сутки проверяет, не вышла ли новая версия. Агенты и пайпы этого уведомления не видят, а
73
82
  `TG_NO_UPDATE_CHECK=1` отключает его совсем.
@@ -83,6 +92,7 @@ npm install -g better-tg-cli # Node >= 20
83
92
  |---|---|---|
84
93
  | [Homebrew](https://github.com/TheVilfer/homebrew-tap) | отдельный бинарник | `brew install thevilfer/tap/better-tg-cli` |
85
94
  | [npm](https://www.npmjs.com/package/better-tg-cli) | CLI и MCP-сервер (Node 20+) | `npm install -g better-tg-cli` |
95
+ | [Scoop](https://github.com/TheVilfer/scoop-bucket) (Windows, экспериментально) | отдельный `telegram.exe` | `scoop bucket add thevilfer https://github.com/TheVilfer/scoop-bucket`, затем `scoop install better-tg-cli` |
86
96
  | [GitHub Releases](https://github.com/TheVilfer/better-tg-cli/releases) | бинарники и SHA256SUMS | скачать вручную |
87
97
  | Плагин Claude Code | скилл и MCP-сервер | [см. ниже](#плагин-для-claude-code) |
88
98
  | Расширение Claude Desktop | MCP-сервер на встроенном Node из Claude | [скачать `.mcpb`](https://github.com/TheVilfer/better-tg-cli/releases/latest/download/better-tg-cli.mcpb) и открыть |
@@ -106,6 +116,15 @@ npm install -g better-tg-cli # Node >= 20
106
116
  MCP-сервер запускается через `npx`, так что хватит Node 20+. Один раз войдите в терминале:
107
117
  `telegram auth --qr` (или `npx better-tg-cli auth --qr`).
108
118
 
119
+ ### Плагин для Codex
120
+
121
+ Тот же скилл и MCP-сервер в виде плагина Codex (он появится и в десктопном приложении ChatGPT):
122
+
123
+ ```bash
124
+ codex plugin marketplace add TheVilfer/better-tg-cli
125
+ codex plugin add better-tg-cli@better-tg-cli
126
+ ```
127
+
109
128
  ### Плагин для Grok Build
110
129
 
111
130
  [Grok Build](https://x.ai/cli) ставит тот же плагин, скилл и MCP-сервер вместе:
@@ -167,7 +186,9 @@ npx skills add TheVilfer/better-tg-cli -g -a claude-code -a codex -y
167
186
  KeePassXC) через `secret-tool`, для этого нужен пакет `libsecret-tools`. Сессия, которая уже лежит
168
187
  в конфиге, переедет туда сама. Если хранилища секретов нет, сессия лежит в
169
188
  `~/.config/tg/config.json5` (права 0600), а запись остаётся выключенной. На Linux
170
- `write-access on` подтверждается в терминале.
189
+ `write-access on` подтверждается в терминале. На Windows секреты лежат в
190
+ `%APPDATA%\tg\secrets.dpapi`, зашифрованные DPAPI для вашего пользователя Windows (расшифровать их
191
+ можете только вы на этой машине), а `write-access on` без терминала спрашивает в окне «Да/Нет».
171
192
 
172
193
  ## Использование
173
194
 
@@ -277,7 +298,9 @@ tailscale funnel --bg 8787 # или: cloudflared tunnel --url h
277
298
  Да, через `TG_PROFILE`: у каждого профиля свой вход, конфиг и записи в Keychain, например `TG_PROFILE=work telegram auth --qr`. Удобное переключение аккаунтов — в [#5](https://github.com/TheVilfer/better-tg-cli/issues/5).
278
299
 
279
300
  **Работает ли на Windows?**
280
- Пока нет. CLI собирается и проверяется на macOS и Linux и опирается на их хранилища секретов.
301
+ Да, экспериментально: `scoop install better-tg-cli` или npm. Секреты хранятся через Windows DPAPI,
302
+ тесты гоняются на Windows в CI, но вживую там проверено меньше, чем на macOS и Linux. О проблемах
303
+ пишите в issues.
281
304
 
282
305
  **Можно ли пользоваться из Grok Bot, ChatGPT или другого облачного агента?**
283
306
  Облачный агент не может запустить программу на вашем компьютере, поэтому поднимите MCP-сервер по HTTP и откройте к нему туннель. См. [Grok Bot](#grok-bot-удалённый-mcp-по-http).
@@ -294,16 +317,42 @@ tailscale funnel --bg 8787 # или: cloudflared tunnel --url h
294
317
  - тестовые серверы Telegram;
295
318
  - отладка в редакторе и тесты.
296
319
 
297
- Релиз выпускает `scripts/release.sh patch|minor|major`. Тег собирает бинарники и публикует их в
320
+ Релиз готовит `scripts/release.sh patch|minor|major` (PR с новой версией), после мержа `scripts/release.sh tag` ставит тег. Тег собирает бинарники и публикует их в
298
321
  GitHub Releases, в npm (trusted publishing с provenance), в Homebrew-тап и в MCP Registry. Подробнее в
299
322
  [CONTRIBUTING.md](CONTRIBUTING.md).
300
323
 
324
+ ## Удаление
325
+
326
+ 1. `telegram logout` удаляет сохранённую сессию. Чтобы завершить её и на стороне Telegram,
327
+ закройте её в Telegram → Настройки → Устройства.
328
+ 2. `telegram skill uninstall` убирает скилл из агентов, куда он был установлен.
329
+ 3. Удалите саму программу: `brew uninstall better-tg-cli`, `npm uninstall -g better-tg-cli` или
330
+ `scoop uninstall better-tg-cli`. Бинарник из Releases удаляется как обычный файл.
331
+ 4. Удалите папку настроек: `~/.config/tg` (`%APPDATA%\tg` на Windows) и `~/.config/tg-<профиль>`
332
+ для каждого `TG_PROFILE`, который вы использовали. На Windows вместе с ней удалится и файл секретов
333
+ DPAPI. На других системах api_hash и флаг write-access остаются в хранилище секретов: удалите
334
+ записи `tg-cli` в «Связке ключей» (или `secret-tool clear service tg-cli`) либо запись в 1Password.
335
+
301
336
  ## Приватность
302
337
 
303
338
  Аналитики нет. Единственный наш сервис — необязательный брокер инвайтов, и он не видит ни ваших
304
339
  сообщений, ни сессии. В [PRIVACY.md](PRIVACY.md) перечислены три хоста, с которыми общается CLI,
305
340
  и то, что он хранит локально.
306
341
 
342
+ ## Code signing policy
343
+
344
+ Бинарники для Windows собираются из этого репозитория только в GitHub Actions
345
+ (`.github/workflows/release.yml`), никогда не на личной машине. Мы подали заявку на бесплатную
346
+ подпись кода от SignPath Foundation; когда её одобрят, в релизах будет: *Free code signing provided
347
+ by [SignPath.io](https://about.signpath.io), certificate by [SignPath Foundation](https://signpath.org).*
348
+ Пока `telegram.exe` для Windows не подписан; бинарники для macOS подписаны ad-hoc.
349
+
350
+ - Коммиттеры и ревьюеры: [@TheVilfer](https://github.com/TheVilfer)
351
+ - Утверждают каждый подписанный релиз: [@TheVilfer](https://github.com/TheVilfer)
352
+ - Политика приватности: [PRIVACY.md](PRIVACY.md). CLI обращается только к Telegram, к брокеру
353
+ инвайтов при входе по инвайту и раз в день к npm-реестру за номером версии, если запущен в
354
+ терминале (отключается `TG_NO_UPDATE_CHECK=1`).
355
+
307
356
  ## Лицензия
308
357
 
309
358
  MIT, см. [LICENSE](LICENSE). Основано на [skillhq/telegram](https://github.com/skillhq/telegram)