better-tg-cli 0.39.5 → 0.40.0-rc.1

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.
package/README.es.md CHANGED
@@ -15,7 +15,7 @@
15
15
  [![license](https://img.shields.io/badge/license-MIT-000000?style=flat&colorA=000000&colorB=000000)](LICENSE)
16
16
 
17
17
  <p>
18
- <a href="#instalación">Instalación</a> · <a href="skills/better-tg-cli/reference.md">Referencia</a> · <a href="SECURITY.md">Seguridad</a> · <a href="https://github.com/TheVilfer/better-tg-cli/issues">Issues</a> · <a href="README.md">English</a> · <a href="README.ru.md">Русский</a>
18
+ <a href="#instalación">Instalación</a> · <a href="skills/better-tg-cli/SKILL.md">Referencia</a> · <a href="SECURITY.md">Seguridad</a> · <a href="https://github.com/TheVilfer/better-tg-cli/issues">Issues</a> · <a href="README.md">English</a> · <a href="README.ru.md">Русский</a>
19
19
  </p>
20
20
  </div>
21
21
 
@@ -65,7 +65,7 @@ Hecho para agentes:
65
65
  - **Tú apruebas cada mensaje.** Tras iniciar sesión, el agente te pregunta en el chat antes de
66
66
  cada envío, edición o borrado y te muestra el texto exacto; solo envía tras tu sí. Escribir sin
67
67
  preguntar (`write-access on`) requiere tu propia confirmación en un terminal o en un diálogo de
68
- macOS. Cada escritura se registra en `~/.config/tg/audit.jsonl`. Los secretos se guardan en el Keychain de macOS, en el Secret Service
68
+ macOS. Los comandos con registro de auditoría intentan anotar el resultado en `~/.config/tg/audit.jsonl` (la carpeta del perfil activo); una escritura detenida para aprobación o con la escritura desactivada termina antes, y no toda escritura tiene uno. Los secretos se guardan en el Keychain de macOS, en el Secret Service
69
69
  de Linux o en 1Password.
70
70
  - **Pequeño y autónomo.** El paquete de npm es un único archivo de 0,3 MB sin dependencias en tiempo
71
71
  de ejecución. Homebrew instala un binario independiente que no necesita Node.
@@ -94,6 +94,10 @@ brew install thevilfer/tap/better-tg-cli # binario independiente, macOS y Linu
94
94
  npm install -g better-tg-cli # Node >= 20, cualquier sistema operativo
95
95
  ```
96
96
 
97
+ Sin Homebrew, Node ni sudo (macOS, Linux): `curl -q --proto '=https' --tlsv1.2 -fsSL https://github.com/TheVilfer/better-tg-cli/releases/latest/download/install.sh | sh` deja el binario de la
98
+ versión en `~/.local/bin` tras comprobar su SHA-256 e imprime el resultado en JSON para agentes
99
+ ([detalles, uso desde scripts y agentes, y cómo pasar desde el script antiguo](docs/install.md)).
100
+
97
101
  En Windows (experimental), con [Scoop](https://scoop.sh) o npm:
98
102
 
99
103
  ```powershell
@@ -104,7 +108,9 @@ scoop install better-tg-cli
104
108
  El `telegram.exe` de Windows no tiene firma de código, así que SmartScreen puede mostrar una
105
109
  advertencia al descargarlo desde la release.
106
110
 
107
- `telegram update` actualiza una instalación existente, sea cual sea el método que usaste. En un
111
+ `telegram update` actualiza una instalación de Homebrew, Scoop, npm o un checkout de git. Un binario
112
+ del script de instalación se actualiza ejecutando el script otra vez; `telegram update` imprime ese
113
+ comando. No reemplaces ese binario a mano: el script guarda su SHA-256 y luego rechaza la ruta. En un
108
114
  terminal, el CLI busca nuevas versiones una vez al día. Los agentes y los pipes nunca ven ese aviso,
109
115
  y `TG_NO_UPDATE_CHECK=1` lo desactiva.
110
116
 
@@ -219,7 +225,9 @@ invitación: `--invite` y `TG_INVITE` siguen funcionando.
219
225
  La sesión se guarda en el Keychain de macOS (servicio `tg-cli`) o en 1Password con
220
226
  `--op-vault <vault>`. `telegram logout` la elimina. En Linux va al Secret Service (GNOME Keyring,
221
227
  KWallet, KeePassXC) a través de `secret-tool`, que necesita el paquete `libsecret-tools`. Una sesión
222
- ya guardada en el archivo de configuración se traslada allí automáticamente. Sin ningún almacén de
228
+ ya guardada en el archivo de configuración se usa desde allí tal cual, y `telegram check` lo indica;
229
+ el traslado al almacén de secretos llegará más adelante
230
+ ([#116](https://github.com/TheVilfer/better-tg-cli/issues/116)). Sin ningún almacén de
223
231
  secretos, la sesión se guarda en `~/.config/tg/config.json5` (modo 0600). En Linux sin un Secret
224
232
  Service que funcione (sin `secret-tool` o sin bus de sesión, como en los ordenadores de agentes en la
225
233
  nube) el modo de escritura también se guarda en un archivo normal del perfil, que protege de errores
@@ -248,9 +256,11 @@ telegram click @SomeBot 4410 "Settings" # pulsa un botón inline
248
256
  ```
249
257
 
250
258
  Los comandos de lectura aceptan `--json`, y algunos también `--markdown`. Consulta todos los comandos
251
- con `telegram help-all`. [reference.md](skills/better-tg-cli/reference.md) cubre el comportamiento que
252
- la lista de flags no puede explicar: formatos de salida, hilos, botones de bots, comandos de
253
- administración y resolución de problemas.
259
+ con `telegram help-all`. Los archivos de referencia del skill cubren el comportamiento que la lista de
260
+ flags no puede explicar: [lectura](skills/better-tg-cli/reading.md) (formatos de salida, hilos, búsqueda),
261
+ [escritura](skills/better-tg-cli/writing.md) (aprobaciones, botones de bots, administración),
262
+ [archivos y exportación](skills/better-tg-cli/files-live.md), [API](skills/better-tg-cli/api.md) y
263
+ [instalación y resolución de problemas](skills/better-tg-cli/setup.md).
254
264
 
255
265
  ## Servidor MCP
256
266
 
@@ -459,7 +469,9 @@ Tras `telegram onboard` ya está en modo `ask`: el agente te pregunta en el chat
459
469
  Algunos ordenadores de agentes en la nube solo dejan salir HTTPS, y eso corta el transporte TCP de Telegram. La CLI cambia entonces sola a MTProto sobre WebSocket (`wss://*.web.telegram.org`, el transporte de web.telegram.org) y lo recuerda para el perfil. `TG_TRANSPORT=tcp|wss|auto` elige el transporte a mano.
460
470
 
461
471
  **¿Cómo actualizo?**
462
- Ejecuta `telegram update`. Usa el mismo canal desde el que instalaste: Homebrew, npm o un binario de release.
472
+ Ejecuta `telegram update`. Usa el mismo canal desde el que instalaste: Homebrew, Scoop o npm. Si
473
+ instalaste con el script de instalación, vuelve a ejecutarlo (`telegram update` imprime el comando) y
474
+ no reemplaces el binario a mano.
463
475
  Si instalaste la skill de agente con `telegram skill install`, vuelve a ejecutarlo para actualizarla.
464
476
 
465
477
  ## Desarrollo
package/README.md CHANGED
@@ -15,7 +15,7 @@
15
15
  [![license](https://img.shields.io/badge/license-MIT-000000?style=flat&colorA=000000&colorB=000000)](LICENSE)
16
16
 
17
17
  <p>
18
- <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>
18
+ <a href="#install">Install</a> · <a href="skills/better-tg-cli/SKILL.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>
19
19
  </p>
20
20
  </div>
21
21
 
@@ -63,8 +63,9 @@ Made for agents:
63
63
  for Saved Messages.
64
64
  - **You approve every message.** After login the agent asks you in the chat before each send,
65
65
  edit or delete, and shows the exact text; it sends only after your yes. Writing without asking
66
- (`write-access on`) needs your own confirmation in a terminal or a macOS dialog. Every write is
67
- logged to `~/.config/tg/audit.jsonl`. Secrets live in the macOS Keychain, the
66
+ (`write-access on`) needs your own confirmation in a terminal or a macOS dialog. Commands with an
67
+ audit log try to record the result in `~/.config/tg/audit.jsonl` (the active profile's folder); a
68
+ write stopped for approval or with writes off ends before it, and not every write has one. Secrets live in the macOS Keychain, the
68
69
  Linux Secret Service or 1Password.
69
70
  - **Small and self-contained.** The npm package is one 0.3 MB file with zero runtime
70
71
  dependencies. Homebrew installs a standalone binary with no Node.
@@ -93,6 +94,10 @@ brew install thevilfer/tap/better-tg-cli # standalone binary, macOS and Linux
93
94
  npm install -g better-tg-cli # Node >= 20, any OS
94
95
  ```
95
96
 
97
+ No Homebrew, Node or sudo (macOS, Linux): `curl -q --proto '=https' --tlsv1.2 -fsSL https://github.com/TheVilfer/better-tg-cli/releases/latest/download/install.sh | sh` puts the release binary
98
+ in `~/.local/bin` after checking its SHA-256 and prints the result as JSON for agents
99
+ ([details, use from scripts and agents, moving from the old script](docs/install.md)).
100
+
96
101
  On Windows (experimental), with [Scoop](https://scoop.sh) or npm:
97
102
 
98
103
  ```powershell
@@ -102,7 +107,9 @@ scoop install better-tg-cli
102
107
 
103
108
  The Windows `telegram.exe` is not code-signed, so SmartScreen may warn about the release download.
104
109
 
105
- `telegram update` upgrades an existing install, whichever of these you used. On a terminal the CLI
110
+ `telegram update` upgrades an install from Homebrew, Scoop, npm or a git checkout. A binary from the
111
+ install script is updated by running the script again; `telegram update` prints that command for it.
112
+ Do not replace that binary by hand: the script records its SHA-256 and then refuses the path. On a terminal the CLI
106
113
  checks for new versions once a day. Agents and pipes never see that notice, and
107
114
  `TG_NO_UPDATE_CHECK=1` turns it off.
108
115
 
@@ -211,7 +218,9 @@ can be revoked. Before 0.37 the key was called an invite: `--invite` and `TG_INV
211
218
  The session is stored in the macOS Keychain (service `tg-cli`), or in 1Password with
212
219
  `--op-vault <vault>`. `telegram logout` removes it. On Linux it goes to the Secret Service (GNOME
213
220
  Keyring, KWallet, KeePassXC) through `secret-tool`, which needs the `libsecret-tools` package. A
214
- session already saved in the config file moves there automatically. Without any secret store, the
221
+ session already saved in the config file is used from there as is, and `telegram check` says so;
222
+ moving it into the secret store comes later
223
+ ([#116](https://github.com/TheVilfer/better-tg-cli/issues/116)). Without any secret store, the
215
224
  session is kept in `~/.config/tg/config.json5` (mode 0600). On Linux without a working Secret
216
225
  Service (no `secret-tool` or no session bus, as on cloud agent computers) the write mode is then kept
217
226
  in a plain file in the profile too, which guards against mistakes, not against an agent that can
@@ -258,9 +267,12 @@ telegram help get-config # telegram ping, telegram req-pq,
258
267
  Read commands take `--json`, and some also take `--markdown`. `read`/`get`/`search`/`inbox`/`watch`
259
268
  take `--full` (alias `--stats`) to include every per-message statistic (views, forwards, full
260
269
  reaction breakdown, comments, flags, rich media metadata) — default output is unchanged without it.
261
- See all commands with `telegram help-all`. [reference.md](skills/better-tg-cli/reference.md) covers the behaviour that the flag list can't
262
- explain: output shapes, threads, bot buttons, admin commands and troubleshooting. The generic
263
- `telegram api <namespace.Method>` reaches 100% of the Telegram client API, and every one of the 823
270
+ See all commands with `telegram help-all`. The agent skill's reference files cover the behaviour that the flag list can't
271
+ explain: [reading](skills/better-tg-cli/reading.md) (output shapes, threads, search), [writing](skills/better-tg-cli/writing.md)
272
+ (approvals, bot buttons, admin commands), [files and export](skills/better-tg-cli/files-live.md), [raw API](skills/better-tg-cli/api.md)
273
+ and [setup and troubleshooting](skills/better-tg-cli/setup.md). The generic
274
+ `telegram api <namespace.Method>` reaches 100% of the Telegram client API in a terminal (over MCP only
275
+ an allowlist of about a hundred methods runs, see [docs/api-coverage.md](docs/api-coverage.md)), and every one of the 823
264
276
  TL methods also has its own typed top-level command `telegram <namespace> <method>` (root methods
265
277
  like `telegram ping` too), generated from the schema with the same refusals and read/write guard as
266
278
  `api`. Where a namespace name collides with a curated command (`stats`, `stories`, `contacts`,
@@ -476,7 +488,9 @@ After `telegram onboard` it is already in mode `ask`: the agent asks you in the
476
488
  Some hosted agent computers let only HTTPS out, which drops Telegram's TCP transport. The CLI then switches to MTProto over WebSocket (`wss://*.web.telegram.org`, the transport of web.telegram.org) by itself and remembers it for the profile. `TG_TRANSPORT=tcp|wss|auto` picks the transport by hand.
477
489
 
478
490
  **How do I update?**
479
- Run `telegram update`. It uses the same channel you installed from: Homebrew, npm or a release binary.
491
+ Run `telegram update`. It uses the same channel you installed from: Homebrew, Scoop or npm. If you
492
+ installed with the install script, run that script again (`telegram update` prints the command), and
493
+ do not replace the binary by hand.
480
494
  If you installed the agent skill with `telegram skill install`, run that again to refresh it.
481
495
 
482
496
  ## Development
package/README.ru.md CHANGED
@@ -15,7 +15,7 @@
15
15
  [![license](https://img.shields.io/badge/license-MIT-000000?style=flat&colorA=000000&colorB=000000)](LICENSE)
16
16
 
17
17
  <p>
18
- <a href="#установка">Установка</a> · <a href="skills/better-tg-cli/reference.md">Справка</a> · <a href="SECURITY.md">Безопасность</a> · <a href="https://github.com/TheVilfer/better-tg-cli/issues">Issues</a> · <a href="README.md">English</a> · <a href="README.es.md">Español</a>
18
+ <a href="#установка">Установка</a> · <a href="skills/better-tg-cli/SKILL.md">Справка</a> · <a href="SECURITY.md">Безопасность</a> · <a href="https://github.com/TheVilfer/better-tg-cli/issues">Issues</a> · <a href="README.md">English</a> · <a href="README.es.md">Español</a>
19
19
  </p>
20
20
  </div>
21
21
 
@@ -63,7 +63,7 @@ $ telegram inbox -n 3
63
63
  - **Каждое сообщение одобряете вы.** После входа агент перед каждой отправкой, правкой или
64
64
  удалением спрашивает вас в чате и показывает точный текст; отправляет только после вашего «да».
65
65
  Писать без вопросов (`write-access on`) можно только после вашего подтверждения в терминале или
66
- в диалоге macOS. Каждая запись попадает в `~/.config/tg/audit.jsonl`. Секреты хранятся в
66
+ в диалоге macOS. Команды с аудитом пытаются записать результат в `~/.config/tg/audit.jsonl` (папка активного профиля); запись, остановленная ради подтверждения или при выключенной записи, завершается раньше журнала, и аудит есть не у каждой записи. Секреты хранятся в
67
67
  Keychain macOS, в Secret Service на Linux или в 1Password.
68
68
  - **Маленький и самодостаточный.** npm-пакет — один файл на 0,3 МБ без runtime-зависимостей.
69
69
  Homebrew ставит отдельный бинарник, которому не нужен Node.
@@ -92,6 +92,10 @@ brew install thevilfer/tap/better-tg-cli # отдельный бинарник
92
92
  npm install -g better-tg-cli # Node >= 20, любая ОС
93
93
  ```
94
94
 
95
+ Без Homebrew, Node и sudo (macOS, Linux): `curl -q --proto '=https' --tlsv1.2 -fsSL https://github.com/TheVilfer/better-tg-cli/releases/latest/download/install.sh | sh` кладёт бинарник релиза
96
+ в `~/.local/bin`, сверив SHA-256, и печатает итог в JSON для агентов
97
+ ([подробности, запуск из скриптов и агентов, переход со старого скрипта](docs/install.md)).
98
+
95
99
  На Windows (экспериментально) через [Scoop](https://scoop.sh) или npm:
96
100
 
97
101
  ```powershell
@@ -101,7 +105,9 @@ scoop install better-tg-cli
101
105
 
102
106
  `telegram.exe` для Windows не подписан, поэтому SmartScreen может предупредить при скачивании из релиза.
103
107
 
104
- `telegram update` обновляет CLI тем же способом, каким он был установлен. В терминале CLI раз в
108
+ `telegram update` обновляет установку из Homebrew, Scoop, npm или git-чекаута. Бинарник из
109
+ установочного скрипта обновляется повторным запуском скрипта; `telegram update` печатает для него эту
110
+ команду. Не заменяйте такой бинарник вручную: скрипт записал его SHA-256 и потом откажется трогать путь. В терминале CLI раз в
105
111
  сутки проверяет, не вышла ли новая версия. Агенты и пайпы этого уведомления не видят, а
106
112
  `TG_NO_UPDATE_CHECK=1` отключает его совсем.
107
113
 
@@ -210,7 +216,9 @@ npx skills add TheVilfer/better-tg-cli -g -a claude-code -a codex -y
210
216
  Сессия хранится в Keychain macOS (сервис `tg-cli`) или в 1Password с флагом `--op-vault <vault>`.
211
217
  `telegram logout` её удаляет. На Linux сессия хранится в Secret Service (GNOME Keyring, KWallet,
212
218
  KeePassXC) через `secret-tool`, для этого нужен пакет `libsecret-tools`. Сессия, которая уже лежит
213
- в конфиге, переедет туда сама. Если хранилища секретов нет, сессия лежит в
219
+ в конфиге, используется оттуда как есть, и `telegram check` об этом пишет; перенос в хранилище
220
+ секретов появится позже ([#116](https://github.com/TheVilfer/better-tg-cli/issues/116)). Если
221
+ хранилища секретов нет, сессия лежит в
214
222
  `~/.config/tg/config.json5` (права 0600). На Linux без работающего Secret Service (нет `secret-tool`
215
223
  или сессионной шины, как на облачных компьютерах агентов) режим записи тогда тоже хранится в
216
224
  обычном файле профиля: это защита от ошибок, но не от агента, который может править файлы. На Linux
@@ -238,8 +246,10 @@ telegram click @SomeBot 4410 "Настройки" # нажать инлай
238
246
  ```
239
247
 
240
248
  Команды чтения принимают `--json`, а некоторые и `--markdown`. Все команды выводит
241
- `telegram help-all`. В [reference.md](skills/better-tg-cli/reference.md) описано то, чего не видно по списку флагов:
242
- форматы вывода, треды, кнопки ботов, админские команды, решение проблем.
249
+ `telegram help-all`. Справочные файлы навыка описывают то, чего не видно по списку флагов:
250
+ [чтение](skills/better-tg-cli/reading.md) (форматы вывода, треды, поиск), [запись](skills/better-tg-cli/writing.md)
251
+ (подтверждения, кнопки ботов, админские команды), [файлы и экспорт](skills/better-tg-cli/files-live.md),
252
+ [API](skills/better-tg-cli/api.md), [установка и решение проблем](skills/better-tg-cli/setup.md).
243
253
 
244
254
  ## MCP-сервер
245
255
 
@@ -445,7 +455,9 @@ journalctl --user -u better-tg-cli-mcp.service -f
445
455
  Некоторые облачные компьютеры агентов выпускают наружу только HTTPS, и TCP-транспорт Telegram обрывается. Тогда CLI сам переключается на MTProto поверх WebSocket (`wss://*.web.telegram.org`, тот же транспорт, что у web.telegram.org) и запоминает это для профиля. Выбрать транспорт вручную можно через `TG_TRANSPORT=tcp|wss|auto`.
446
456
 
447
457
  **Как обновиться?**
448
- `telegram update`. Команда обновляет тем же способом, каким CLI был установлен: Homebrew, npm или бинарник из релиза.
458
+ `telegram update`. Команда обновляет тем же способом, каким CLI был установлен: Homebrew, Scoop или npm.
459
+ Если CLI ставился установочным скриптом, запустите скрипт ещё раз (`telegram update` напечатает
460
+ команду) и не заменяйте бинарник вручную.
449
461
  Если скилл для агентов ставили через `telegram skill install`, запустите её ещё раз, чтобы обновить скилл.
450
462
 
451
463
  ## Разработка