better-tg-cli 0.25.0 → 0.25.2

package/README.md

@@ -28,7 +28,7 @@ that AI agents (Claude Code, Codex, …) can drive it cheaply and safely.
 $ 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?
+-1001234567 supergroup muted unread=41 Rust Seattle @rust_sea | 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?"}]}
@@ -41,6 +41,8 @@ $ telegram read @alice -n 1 --json
 > 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.
 
+**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)
+
 ## Why this fork
 
 A fork of [skillhq/telegram](https://github.com/skillhq/telegram), reworked for agents:
@@ -159,7 +161,8 @@ 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 send @alice "on my way"
+printf '%s' "$text" | telegram send @alice -  # long or multi-line text: from stdin, no quoting problems
 telegram reply "Chat" 812 "on it" --silent
 telegram click @SomeBot 4410 "Settings"       # press an inline button
 ```
@@ -229,6 +232,38 @@ tunnel URL plus `/mcp` (for example `https://<machine>.<tailnet>.ts.net/mcp`) an
 for your tailnet first. A `cloudflared` quick tunnel gets a new URL on every start. Read "Remote
 MCP over HTTP" in [SECURITY.md](SECURITY.md) first.
 
+## FAQ
+
+**Will Telegram ban my account?**
+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.
+
+**Is this a bot?**
+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.
+
+**Can an agent send messages on its own?**
+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).
+
+**Does reading mark messages as read?**
+No. `read`, `inbox` and `search` leave chats unread. Only `telegram mark-read` marks them.
+
+**Do I need my own API keys?**
+Yes, from [my.telegram.org/apps](https://my.telegram.org/apps). They are free and take a minute to create. If the maintainer gave you an invite, `telegram auth --invite --qr` logs you in without them.
+
+**Where is my session stored, and who can see my messages?**
+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).
+
+**Can I use several accounts?**
+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).
+
+**Does it work on Windows?**
+Not yet. It is built and tested on macOS and Linux, and relies on their secret stores.
+
+**Can I use it from Grok Bot, ChatGPT or another cloud agent?**
+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).
+
+**How do I update?**
+Run `telegram update`. It uses the same channel you installed from: Homebrew, npm or a release binary.
+
 ## Development
 
 [DEVELOPMENT.md](DEVELOPMENT.md) covers:

package/README.ru.md

@@ -28,7 +28,7 @@
 $ telegram inbox -n 3
 48 unread in 7 chats (showing 3)
 1234567890 user unread=2 Алиса @alice | в 7 в силе?
--1001234567 supergroup muted unread=41 Rust Moscow @rust_msk | кто уже пробовал 1.90?
+-1001234567 supergroup muted unread=41 Rust Seattle @rust_sea | кто уже пробовал 1.90?
 -1009876543 channel unread=5 Changelog | вышла v2.4
 ```
 
@@ -40,6 +40,8 @@ $ telegram inbox -n 3
 > она не нужна. Прежде чем разрешать агенту писать, прочитайте [SECURITY.md](SECURITY.md). Авторы
 > не отвечают за ограниченные аккаунты.
 
+**Содержание:** [Чем этот форк лучше](#чем-этот-форк-лучше) · [Установка](#установка) · [Вход](#вход) · [Использование](#использование) · [MCP-сервер](#mcp-сервер) · [FAQ](#faq) · [Разработка](#разработка) · [Приватность](#приватность) · [Лицензия](#лицензия)
+
 ## Чем этот форк лучше
 
 Это форк [skillhq/telegram](https://github.com/skillhq/telegram), переделанный под агентов:
@@ -159,7 +161,8 @@ telegram download "Чат" 812                   # сохранить вложе
 telegram sync --chat "Чат" --output ./export --resume   # инкрементальная выгрузка в markdown
 
 telegram write-access on --for 1h             # подтверждает человек
-printf '%s' "$text" | telegram send @alice -  # текст из stdin, без проблем с кавычками
+telegram send @alice "уже еду"
+printf '%s' "$text" | telegram send @alice -  # длинный или многострочный текст: из stdin, без проблем с кавычками
 telegram reply "Чат" 812 "беру" --silent
 telegram click @SomeBot 4410 "Настройки"      # нажать инлайн-кнопку
 ```
@@ -230,6 +233,38 @@ tailscale funnel --bg 8787                  # или: cloudflared tunnel --url h
 разрешить для вашего tailnet. Быстрый туннель `cloudflared` при каждом запуске получает новый
 адрес. Сначала прочитайте раздел «Remote MCP over HTTP» в [SECURITY.md](SECURITY.md).
 
+## FAQ
+
+**Не забанит ли Telegram мой аккаунт?**
+[Условия Telegram API](https://core.telegram.org/api/terms) разрешают пользоваться своим аккаунтом через сторонние клиенты. Ограничения получают за поведение, похожее на бота: массовые рассылки, массовые вступления и приглашения, спам, активность только что созданного аккаунта. Пользуйтесь так же, как пользовались бы самим Telegram. Скилл учит агентов обходить эти сценарии.
+
+**Это бот?**
+Нет. CLI входит от вашего имени по MTProto, как Telegram Desktop, и видит ровно то же, что и вы. Боты не читают ваши чаты, а этот клиент читает.
+
+**Может ли агент отправлять сообщения сам?**
+Только после того, как вы включите запись. `telegram write-access on` просит подтверждения в терминале или в диалоге macOS, на которое агент ответить не может. Дальше запись требует точно указанный чат, а каждая отправка пишется в журнал. В MCP запись вынесена в отдельный инструмент, и клиенты могут спрашивать вас перед каждым вызовом. Подробнее в [SECURITY.md](SECURITY.md).
+
+**Отмечает ли чтение сообщения прочитанными?**
+Нет. `read`, `inbox` и `search` оставляют чаты непрочитанными. Отмечает только `telegram mark-read`.
+
+**Нужны ли свои API-ключи?**
+Да, с [my.telegram.org/apps](https://my.telegram.org/apps). Они бесплатные, их создание занимает минуту. Если мейнтейнер дал вам инвайт, `telegram auth --invite --qr` войдёт без своих ключей.
+
+**Где хранится сессия и кто видит мои сообщения?**
+Сессия лежит в Keychain macOS, в Secret Service на Linux или в 1Password. CLI общается с Telegram напрямую, аналитики нет. Кроме Telegram, он ходит только в npm (раз в день за номером версии) и в сервис инвайтов при входе. Подробнее в [PRIVACY.md](PRIVACY.md).
+
+**Можно ли несколько аккаунтов?**
+Да, через `TG_PROFILE`: у каждого профиля свой вход, конфиг и записи в Keychain, например `TG_PROFILE=work telegram auth --qr`. Удобное переключение аккаунтов — в [#5](https://github.com/TheVilfer/better-tg-cli/issues/5).
+
+**Работает ли на Windows?**
+Пока нет. CLI собирается и проверяется на macOS и Linux и опирается на их хранилища секретов.
+
+**Можно ли пользоваться из Grok Bot, ChatGPT или другого облачного агента?**
+Облачный агент не может запустить программу на вашем компьютере, поэтому поднимите MCP-сервер по HTTP и откройте к нему туннель. См. [Grok Bot](#grok-bot-удалённый-mcp-по-http).
+
+**Как обновиться?**
+`telegram update`. Команда обновляет тем же способом, каким CLI был установлен: Homebrew, npm или бинарник из релиза.
+
 ## Разработка
 
 В [DEVELOPMENT.md](DEVELOPMENT.md) описаны: