better-tg-cli 0.38.1 → 0.39.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.
package/README.es.md CHANGED
@@ -58,10 +58,10 @@ Un fork de [skillhq/telegram](https://github.com/skillhq/telegram), rehecho para
58
58
  - **Lecturas exactas.** Paginación real para `--since/--until`, `--unread`, hilos y comentarios de
59
59
  canales, temas de foros, `get` por ID, filtros de búsqueda por tipo, remitente o fecha, y `me` /
60
60
  `Избранное` para los Mensajes guardados.
61
- - **Seguro por defecto.** La cuenta es de solo lectura hasta que una persona ejecuta
62
- `write-access on [--for 1h]` y lo confirma en un prompt del terminal o en un diálogo de macOS, así
63
- que un agente no puede activarlo por su cuenta. Cada escritura se registra en
64
- `~/.config/tg/audit.jsonl`. Los secretos se guardan en el Keychain de macOS, en el Secret Service
61
+ - **Tú apruebas cada mensaje.** Tras iniciar sesión, el agente te pregunta en el chat antes de
62
+ cada envío, edición o borrado y te muestra el texto exacto; solo envía tras tu sí. Escribir sin
63
+ preguntar (`write-access on`) requiere tu propia confirmación en un terminal o en un diálogo de
64
+ macOS. Cada escritura se registra en `~/.config/tg/audit.jsonl`. Los secretos se guardan en el Keychain de macOS, en el Secret Service
65
65
  de Linux o en 1Password.
66
66
  - **Pequeño y autónomo.** El paquete de npm es un único archivo de 0,3 MB sin dependencias en tiempo
67
67
  de ejecución. Homebrew instala un binario independiente que no necesita Node.
@@ -213,7 +213,8 @@ telegram get "Chat" 812 813 # mensajes exactos por ID
213
213
  telegram download "Chat" 812 # guarda el archivo adjunto
214
214
  telegram sync --chat "Chat" --output ./export --resume # exportación incremental a markdown
215
215
 
216
- telegram write-access on --for 1h # esto lo confirma una persona
216
+ telegram write-access ask # cada escritura espera tu sí en el chat (por defecto tras onboard)
217
+ telegram write-access on --for 1h # o: escribir sin preguntar durante una hora
217
218
  telegram send @alice "on my way"
218
219
  printf '%s' "$text" | telegram send @alice - # texto largo o de varias líneas: desde stdin, sin problemas de comillas
219
220
  telegram reply "Chat" 812 "on it" --silent
@@ -296,7 +297,7 @@ Usar tu propia cuenta desde un cliente de terceros está permitido por los [tér
296
297
  No. Inicia sesión como tú por MTProto, igual que Telegram Desktop, y ve exactamente lo que ves tú. Los bots no pueden leer tus chats; esto sí.
297
298
 
298
299
  **¿Puede un agente enviar mensajes por su cuenta?**
299
- Solo después de que actives la escritura. `telegram write-access on` te pide que lo confirmes en el terminal o en un diálogo de macOS, algo que un agente no puede responder. A partir de ahí, las escrituras necesitan un chat exacto y cada una queda registrada. Por MCP, escribir es una herramienta aparte que los clientes pueden pedirte que apruebes cada vez. Los detalles están en [SECURITY.md](SECURITY.md).
300
+ No debería. Tras iniciar sesión el perfil está en modo `ask`: antes de cada escritura el agente te muestra en el chat la acción exacta y solo la envía tras tu sí, y el código que recibe por ese sí funciona una vez y solo para ese texto. Por MCP, los clientes que admiten elicitation te preguntan en su propio diálogo. Todo esto depende de que el agente siga sus instrucciones: un agente con una terminal en tu usuario puede leer la sesión del Keychain y actuar en tu nombre, así que dale solo chats de confianza o conéctalo solo por MCP. `write-access on` (sin preguntar) requiere tu confirmación en un terminal o en un diálogo de macOS. Más detalles en [SECURITY.md](SECURITY.md).
300
301
 
301
302
  **¿Leer marca los mensajes como leídos?**
302
303
  No. `read`, `inbox` y `search` dejan los chats sin leer. Solo `telegram mark-read` los marca.
@@ -318,6 +319,9 @@ Linux. Por favor, informa de los problemas en los issues.
318
319
  **¿Puedo usarlo desde Grok Bot, ChatGPT u otro agente en la nube?**
319
320
  Los agentes en la nube no pueden iniciar un programa en tu ordenador, así que ejecuta el servidor MCP por HTTP y accede a él a través de un túnel. Consulta [Grok Bot](#grok-bot-mcp-remoto-por-http).
320
321
 
322
+ **¿Cómo permito escribir en Grok Bot u otro agente en la nube?**
323
+ Tras `telegram onboard` ya está en modo `ask`: el agente te pregunta en el chat antes de cada escritura. Si dice que la escritura está desactivada, pídele que ejecute `telegram write-access ask`; ahí funciona tal cual. Solo `telegram write-access on --for 1h` (sin preguntar) necesita tu elección: esos ordenadores no tienen almacén de secretos ni una terminal para ti, así que abre una página en el navegador del propio agente donde eliges. Ejecutarlo en tu terminal no sirve: cambia la CLI de tu ordenador, no la del agente. El agente no debe intentar instalar un llavero allí: sin sesión de escritorio no funciona. En esos ordenadores el ajuste está en un archivo normal, que protege de errores pero no de un agente malicioso.
324
+
321
325
  **El inicio de sesión falla con «NetSocket was closed» en un ordenador en la nube (Grok Bot y otros).**
322
326
  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.
323
327
 
package/README.md CHANGED
@@ -57,9 +57,10 @@ A fork of [skillhq/telegram](https://github.com/skillhq/telegram), reworked for
57
57
  - **Exact reads.** Real pagination for `--since/--until`, `--unread`, threads and channel
58
58
  comments, forum topics, `get` by ID, search filters by type, sender or date, and `me` / `Избранное`
59
59
  for Saved Messages.
60
- - **Safe by default.** The account is read-only until a human runs `write-access on [--for 1h]`
61
- and confirms it in a terminal prompt or a macOS dialog, so an agent cannot switch it on itself.
62
- Every write is logged to `~/.config/tg/audit.jsonl`. Secrets live in the macOS Keychain, the
60
+ - **You approve every message.** After login the agent asks you in the chat before each send,
61
+ edit or delete, and shows the exact text; it sends only after your yes. Writing without asking
62
+ (`write-access on`) needs your own confirmation in a terminal or a macOS dialog. Every write is
63
+ logged to `~/.config/tg/audit.jsonl`. Secrets live in the macOS Keychain, the
63
64
  Linux Secret Service or 1Password.
64
65
  - **Small and self-contained.** The npm package is one 0.3 MB file with zero runtime
65
66
  dependencies. Homebrew installs a standalone binary with no Node.
@@ -212,7 +213,8 @@ telegram stats "Mock News" --graphs # full channel stats + growth grap
212
213
  telegram sessions ; telegram stars # active login sessions; Telegram Stars balance & transactions
213
214
  telegram invites "Team" --requests # a chat's invite links, or its pending join requests
214
215
 
215
- telegram write-access on --for 1h # a human confirms this
216
+ telegram write-access ask # each write waits for your yes in the chat (default after onboard)
217
+ telegram write-access on --for 1h # or: writes without asking, for an hour
216
218
  telegram send @alice "on my way"
217
219
  printf '%s' "$text" | telegram send @alice - # long or multi-line text: from stdin, no quoting problems
218
220
  telegram reply "Chat" 812 "on it" --silent
@@ -315,7 +317,7 @@ Using your own account from a third-party client is allowed by the [Telegram API
315
317
  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.
316
318
 
317
319
  **Can an agent send messages on its own?**
318
- 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).
320
+ Not by design. After login the profile is in mode `ask`: before each write the agent shows you the exact action in the chat and sends only after your yes, and the code it gets for that yes works once, for that exact text. Over MCP, clients that support elicitation ask you in their own dialog instead. This relies on the agent following its instructions: an agent that has a shell on your user account can read the session from the Keychain and act as you, so give such agents only chats you trust, or connect them through MCP only. `write-access on` (no questions) needs your confirmation in a terminal or a macOS dialog. Details are in [SECURITY.md](SECURITY.md).
319
321
 
320
322
  **Does reading mark messages as read?**
321
323
  No. `read`, `inbox` and `search` leave chats unread. Only `telegram mark-read` marks them.
@@ -337,6 +339,9 @@ report problems in the issues.
337
339
  **Can I use it from Grok Bot, ChatGPT or another cloud agent?**
338
340
  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).
339
341
 
342
+ **How do I allow writes on Grok Bot or another cloud agent?**
343
+ After `telegram onboard` it is already in mode `ask`: the agent asks you in the chat before each write. If it says writes are off, ask it to run `telegram write-access ask`; that works there as is. Only `telegram write-access on --for 1h` (no questions) needs your choice: those computers have no secret store and no terminal for you, so it opens a page in the agent's own browser where you choose. Running the command in your own terminal doesn't help: it changes the CLI on your computer, not the agent's. The agent should not try to install a keyring there; it can't work without a desktop session. On such computers the setting sits in a plain file, which protects against mistakes but not against a hostile agent.
344
+
340
345
  **Login fails with "NetSocket was closed" on a cloud computer (Grok Bot and others).**
341
346
  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.
342
347
 
package/README.ru.md CHANGED
@@ -56,9 +56,10 @@ $ telegram inbox -n 3
56
56
  - **Точное чтение.** `--since` и `--until` честно листают историю. Работают `--unread`, треды и
57
57
  комментарии в каналах, темы форумов, `get` по ID, поиск по типу, отправителю и дате. `me` и
58
58
  `Избранное` означают «Избранное».
59
- - **Безопасность по умолчанию.** Аккаунт открыт только на чтение, пока человек не выполнит
60
- `write-access on [--for 1h]` и не подтвердит это в терминале или в диалоге macOS. Сам агент
61
- запись не включит. Каждая запись попадает в `~/.config/tg/audit.jsonl`. Секреты хранятся в
59
+ - **Каждое сообщение одобряете вы.** После входа агент перед каждой отправкой, правкой или
60
+ удалением спрашивает вас в чате и показывает точный текст; отправляет только после вашего «да».
61
+ Писать без вопросов (`write-access on`) можно только после вашего подтверждения в терминале или
62
+ в диалоге macOS. Каждая запись попадает в `~/.config/tg/audit.jsonl`. Секреты хранятся в
62
63
  Keychain macOS, в Secret Service на Linux или в 1Password.
63
64
  - **Маленький и самодостаточный.** npm-пакет — один файл на 0,3 МБ без runtime-зависимостей.
64
65
  Homebrew ставит отдельный бинарник, которому не нужен Node.
@@ -203,7 +204,8 @@ telegram get "Чат" 812 813 # конкретные сооб
203
204
  telegram download "Чат" 812 # сохранить вложение
204
205
  telegram sync --chat "Чат" --output ./export --resume # инкрементальная выгрузка в markdown
205
206
 
206
- telegram write-access on --for 1h # подтверждает человек
207
+ telegram write-access ask # каждая запись ждёт вашего «да» в чате (по умолчанию после onboard)
208
+ telegram write-access on --for 1h # или: запись без вопросов на час
207
209
  telegram send @alice "уже еду"
208
210
  printf '%s' "$text" | telegram send @alice - # длинный или многострочный текст: из stdin, без проблем с кавычками
209
211
  telegram reply "Чат" 812 "беру" --silent
@@ -285,7 +287,7 @@ tailscale funnel --bg 8787 # или: cloudflared tunnel --url h
285
287
  Нет. CLI входит от вашего имени по MTProto, как Telegram Desktop, и видит ровно то же, что и вы. Боты не читают ваши чаты, а этот клиент читает.
286
288
 
287
289
  **Может ли агент отправлять сообщения сам?**
288
- Только после того, как вы включите запись. `telegram write-access on` просит подтверждения в терминале или в диалоге macOS, на которое агент ответить не может. Дальше запись требует точно указанный чат, а каждая отправка пишется в журнал. В MCP запись вынесена в отдельный инструмент, и клиенты могут спрашивать вас перед каждым вызовом. Подробнее в [SECURITY.md](SECURITY.md).
290
+ Не должен. После входа профиль в режиме `ask`: перед каждой записью агент показывает вам в чате точное действие и отправляет только после вашего «да», а код, который он получает под это «да», срабатывает один раз и только для этого текста. Через MCP клиенты с поддержкой elicitation спрашивают вас в своём окне. Всё это держится на том, что агент слушается инструкций: агент с доступом к терминалу под вашим пользователем может прочитать сессию из Keychain и действовать от вашего имени, поэтому давайте таким агентам только доверенные чаты или подключайте их только через MCP. `write-access on` (без вопросов) требует вашего подтверждения в терминале или в диалоге macOS. Подробности в [SECURITY.md](SECURITY.md).
289
291
 
290
292
  **Отмечает ли чтение сообщения прочитанными?**
291
293
  Нет. `read`, `inbox` и `search` оставляют чаты непрочитанными. Отмечает только `telegram mark-read`.
@@ -307,6 +309,9 @@ tailscale funnel --bg 8787 # или: cloudflared tunnel --url h
307
309
  **Можно ли пользоваться из Grok Bot, ChatGPT или другого облачного агента?**
308
310
  Облачный агент не может запустить программу на вашем компьютере, поэтому поднимите MCP-сервер по HTTP и откройте к нему туннель. См. [Grok Bot](#grok-bot-удалённый-mcp-по-http).
309
311
 
312
+ **Как разрешить запись в Grok Bot или другом облачном агенте?**
313
+ После `telegram onboard` там уже режим `ask`: агент спрашивает вас в чате перед каждой записью. Если он пишет, что запись выключена, попросите его выполнить `telegram write-access ask`, это работает там как есть. Только `telegram write-access on --for 1h` (без вопросов) требует вашего выбора: на таких компьютерах нет хранилища секретов и терминала для вас, поэтому команда открывает страницу в браузере самого агента, где вы выбираете. Запускать команду в своём терминале бесполезно: она меняет CLI на вашем компьютере, а не у агента. Ставить там связку ключей агенту не нужно: без рабочего стола она не заработает. Настройка на таких компьютерах лежит в обычном файле, это защита от ошибок, но не от злонамеренного агента.
314
+
310
315
  **Вход падает с «NetSocket was closed» на облачном компьютере (Grok Bot и другие).**
311
316
  Некоторые облачные компьютеры агентов выпускают наружу только HTTPS, и TCP-транспорт Telegram обрывается. Тогда CLI сам переключается на MTProto поверх WebSocket (`wss://*.web.telegram.org`, тот же транспорт, что у web.telegram.org) и запоминает это для профиля. Выбрать транспорт вручную можно через `TG_TRANSPORT=tcp|wss|auto`.
312
317