telegram-cli-local 0.3.0__tar.gz → 0.4.0__tar.gz

{telegram_cli_local-0.3.0 → telegram_cli_local-0.4.0}/.agents/skills/telegram-cli/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: telegram-cli
-description: Use the personal-account Telegram CLI (tcli) for chat discovery, filtered history, topics, reply chains, exports, messages and attachments, scheduling, live updates, JSON automation, and account diagnostics.
+description: Use Telegram CLI (tcli) with named user or bot sessions for messages, attachments, deletion, history, live updates, JSON automation and diagnostics.
 ---
 
 # Telegram CLI
 
-Use the installed `tcli` command from any directory. It acts as the user's personal Telegram account,
-not a bot. Respond in the user's language; CLI output and these instructions are English.
+Use the installed `tcli` command from any directory with a user or bot account.
+Respond in the user's language; CLI output and these instructions are English.
 Do not infer a repository path from the skill's installation directory.
 
 ## Choose the command
@@ -34,6 +34,10 @@ If unavailable, inspect `tcli help`; do not assume newer commands exist based on
 | Observe future messages and edits | `tcli watch "Chat" --edits --json` |
 | Send literal text | `tcli send me "Text" --json` |
 | Edit outgoing text or an attachment caption | `tcli edit me 123 "Corrected text" --json` |
+| Delete specific messages for everyone | `tcli delete me 123 124 --json` |
+| List local session files offline | `tcli sessions --json` |
+| Sign in to a named user session | `tcli --session work login` |
+| Sign in to a separate bot session | `tcli --session assistant login --bot` |
 | Forward with attribution | `tcli forward "Source" 123 "Destination" --json` |
 | Inspect pending scheduled messages | `tcli scheduled me --json` |
 | Cancel specific scheduled messages | `tcli scheduled me --cancel 123 124 --json` |
@@ -48,10 +52,39 @@ All example names, IDs, links and paths are placeholders. Resolve actual targets
 Use `read` for one-time requests; start `watch` only for ongoing observation.
 Use `thread` for the parent chain and `--around` for chronological neighbors; these are different views.
 
+## Sessions, bots and deletion
+
+Select the authorized account with `--session NAME` before or after the command; default is `default`.
+Do not assume a different named session belongs to the same person or bot. `sessions --json` lists
+local file presence only, without checking identity or authorization; `doctor --connect` shows user/bot type.
+Names use 1-32 lowercase ASCII letters/digits, underscores or hyphens, starting with letter/digit.
+The default keeps the old account.session; others use sessions/NAME/account.session in the data directory.
+API configuration is shared. Logout affects only the selected session. Do not copy or delete session files.
+
+`login --bot` prompts locally with hidden input or reads TG_BOT_TOKEN. API_ID/API_HASH are still required.
+Never collect bot tokens in chat or put them in command arguments. Existing login is reused;
+changing account/type requires another session name. Never log out an unrelated account to switch.
+Bots use MTProto, not HTTP Bot API. Bot capabilities in this CLI:
+
+- Send text/files/albums, forward, edit outgoing messages and delete specified IDs within Telegram permissions.
+- Read known IDs (`read --id`), follow `thread`, single download/resume and info, subject to access.
+- Watch live new/edit events only; no history polling or replay guarantee. Privacy mode affects group events.
+- No chats list, title selection, Saved Messages (`me`), history/search/export, pinned/topics/scheduled commands,
+  send --schedule, album/batch download. These modes fail with bot_unsupported.
+- Use a known numeric chat ID or @username. A raw ID without a cached entity/access hash may fail.
+  Bots cannot initiate arbitrary private conversations; users must contact/add the bot first.
+
+`delete CHAT ID [ID ...]` is irreversible, deletes for everyone and has no extra prompt.
+Execute only for the user's explicitly authorized session, chat and IDs. The CLI checks every ID
+belongs to the selected chat before deleting; missing or mismatched IDs abort without deletion.
+`{ok:true,requested_ids:[...]}` means the server accepted the request, not proof for each ID.
+Large requests can partially succeed; after uncertain failure inspect accessible IDs before retrying.
+Use scheduled --cancel for pending scheduled IDs, not delete.
+
 ## Authorization and private data
 
 - Read only the chats and history needed for the user's request. A request to read or develop the CLI
-  does not authorize sends, forwards, edits, scheduling or cancellation, including in Saved Messages.
+  does not authorize sends, forwards, edits, deletes, scheduling or cancellation, including in Saved Messages.
 - For a write, use the user's authorized recipient, content and message ID where applicable. Existing
   unambiguous authorization remains valid; do not ask for the same permission again. Clarify a genuinely
   ambiguous recipient, time or action before executing that part.
@@ -270,6 +303,8 @@ JSON contains resulting plain text, not formatting entities or the original Mark
 | `download` | {ok:true,files:[...]} |
 | `export` | {ok:true,path,count} |
 | `scheduled --cancel` | {ok:true,cancelled_ids:[...]} |
+| `delete` | {ok:true,requested_ids:[...]} |
+| `sessions` | Array of {name,path}; file presence only |
 
 Download file records contain message_id, chat_id, absolute path, text (caption), grouped_id.
 Errors with `--json` or `read --jsonl` go to stderr as {ok:false,error:{code,message,retry_after,...}}.

{telegram_cli_local-0.3.0 → telegram_cli_local-0.4.0}/.claude/skills/telegram-cli/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: telegram-cli
-description: Use the personal-account Telegram CLI (tcli) for chat discovery, filtered history, topics, reply chains, exports, messages and attachments, scheduling, live updates, JSON automation, and account diagnostics.
+description: Use Telegram CLI (tcli) with named user or bot sessions for messages, attachments, deletion, history, live updates, JSON automation and diagnostics.
 ---
 
 # Telegram CLI
 
-Use the installed `tcli` command from any directory. It acts as the user's personal Telegram account,
-not a bot. Respond in the user's language; CLI output and these instructions are English.
+Use the installed `tcli` command from any directory with a user or bot account.
+Respond in the user's language; CLI output and these instructions are English.
 Do not infer a repository path from the skill's installation directory.
 
 ## Choose the command
@@ -34,6 +34,10 @@ If unavailable, inspect `tcli help`; do not assume newer commands exist based on
 | Observe future messages and edits | `tcli watch "Chat" --edits --json` |
 | Send literal text | `tcli send me "Text" --json` |
 | Edit outgoing text or an attachment caption | `tcli edit me 123 "Corrected text" --json` |
+| Delete specific messages for everyone | `tcli delete me 123 124 --json` |
+| List local session files offline | `tcli sessions --json` |
+| Sign in to a named user session | `tcli --session work login` |
+| Sign in to a separate bot session | `tcli --session assistant login --bot` |
 | Forward with attribution | `tcli forward "Source" 123 "Destination" --json` |
 | Inspect pending scheduled messages | `tcli scheduled me --json` |
 | Cancel specific scheduled messages | `tcli scheduled me --cancel 123 124 --json` |
@@ -48,10 +52,39 @@ All example names, IDs, links and paths are placeholders. Resolve actual targets
 Use `read` for one-time requests; start `watch` only for ongoing observation.
 Use `thread` for the parent chain and `--around` for chronological neighbors; these are different views.
 
+## Sessions, bots and deletion
+
+Select the authorized account with `--session NAME` before or after the command; default is `default`.
+Do not assume a different named session belongs to the same person or bot. `sessions --json` lists
+local file presence only, without checking identity or authorization; `doctor --connect` shows user/bot type.
+Names use 1-32 lowercase ASCII letters/digits, underscores or hyphens, starting with letter/digit.
+The default keeps the old account.session; others use sessions/NAME/account.session in the data directory.
+API configuration is shared. Logout affects only the selected session. Do not copy or delete session files.
+
+`login --bot` prompts locally with hidden input or reads TG_BOT_TOKEN. API_ID/API_HASH are still required.
+Never collect bot tokens in chat or put them in command arguments. Existing login is reused;
+changing account/type requires another session name. Never log out an unrelated account to switch.
+Bots use MTProto, not HTTP Bot API. Bot capabilities in this CLI:
+
+- Send text/files/albums, forward, edit outgoing messages and delete specified IDs within Telegram permissions.
+- Read known IDs (`read --id`), follow `thread`, single download/resume and info, subject to access.
+- Watch live new/edit events only; no history polling or replay guarantee. Privacy mode affects group events.
+- No chats list, title selection, Saved Messages (`me`), history/search/export, pinned/topics/scheduled commands,
+  send --schedule, album/batch download. These modes fail with bot_unsupported.
+- Use a known numeric chat ID or @username. A raw ID without a cached entity/access hash may fail.
+  Bots cannot initiate arbitrary private conversations; users must contact/add the bot first.
+
+`delete CHAT ID [ID ...]` is irreversible, deletes for everyone and has no extra prompt.
+Execute only for the user's explicitly authorized session, chat and IDs. The CLI checks every ID
+belongs to the selected chat before deleting; missing or mismatched IDs abort without deletion.
+`{ok:true,requested_ids:[...]}` means the server accepted the request, not proof for each ID.
+Large requests can partially succeed; after uncertain failure inspect accessible IDs before retrying.
+Use scheduled --cancel for pending scheduled IDs, not delete.
+
 ## Authorization and private data
 
 - Read only the chats and history needed for the user's request. A request to read or develop the CLI
-  does not authorize sends, forwards, edits, scheduling or cancellation, including in Saved Messages.
+  does not authorize sends, forwards, edits, deletes, scheduling or cancellation, including in Saved Messages.
 - For a write, use the user's authorized recipient, content and message ID where applicable. Existing
   unambiguous authorization remains valid; do not ask for the same permission again. Clarify a genuinely
   ambiguous recipient, time or action before executing that part.
@@ -270,6 +303,8 @@ JSON contains resulting plain text, not formatting entities or the original Mark
 | `download` | {ok:true,files:[...]} |
 | `export` | {ok:true,path,count} |
 | `scheduled --cancel` | {ok:true,cancelled_ids:[...]} |
+| `delete` | {ok:true,requested_ids:[...]} |
+| `sessions` | Array of {name,path}; file presence only |
 
 Download file records contain message_id, chat_id, absolute path, text (caption), grouped_id.
 Errors with `--json` or `read --jsonl` go to stderr as {ok:false,error:{code,message,retry_after,...}}.

{telegram_cli_local-0.3.0 → telegram_cli_local-0.4.0}/CHANGELOG.md

@@ -7,6 +7,19 @@ move them into a versioned section when publishing a release.
 
 No unreleased changes.
 
+## 0.4.0 - 2026-10-25
+
+### Added
+
+- Add `delete CHAT ID...` with full chat-membership preflight and revoke-for-everyone semantics.
+- Add named `--session` selection and offline `sessions` listing, preserving the existing default session.
+- Support hidden-token bot login, direct bot peer resolution and live event-based bot watch;
+  reject unsupported bot modes with actionable errors and document capabilities and restrictions.
+- Add a percentage bar that redraws in terminals for uploads, albums and downloads, keeping
+  redirected output line-based and JSON progress unchanged. End interrupted bars before errors.
+- Add the optional `fast` extra with native cryptg encryption and an offline correctness/speed
+  benchmark, plus workflow performance guidance in both READMEs.
+
 ## 0.3.0 - 2026-10-19
 
 ### Changed

{telegram_cli_local-0.3.0 → telegram_cli_local-0.4.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: telegram-cli-local
-Version: 0.3.0
-Summary: Telegram CLI for a personal account
+Version: 0.4.0
+Summary: Telegram CLI for user and bot accounts with named sessions
 Author: BYxarek
 License-Expression: Apache-2.0
 Project-URL: Repository, https://github.com/BYxarek/telegram-cli
@@ -18,6 +18,8 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: Telethon==1.45.0
+Provides-Extra: fast
+Requires-Dist: cryptg<0.7,>=0.5.2; extra == "fast"
 Dynamic: license-file
 
 <div align="center">
@@ -50,8 +52,8 @@ tcli watch "Work chat"        # Follow new messages
 ```
 
 `tcli` is a local Python CLI built with [Telethon](https://docs.telethon.dev/).
-It uses the Telegram API and acts as your personal account. You need your own
-`API_ID` and `API_HASH`; no bot token is used.
+It uses Telegram's MTProto API with a personal account or a bot. Both modes require your own
+`API_ID` and `API_HASH`; bot login additionally requires a BotFather token.
 
 ## Features
 
@@ -71,8 +73,63 @@ are removed from displayed messages.
 
 ### Current scope
 
-One local account session, text and attachments, human-readable output, and optional JSON.
-Message deletion and a full-screen interface are not available.
+Named local user/bot sessions, text and attachments, message deletion, human-readable output,
+and optional JSON. A full-screen interface is not available.
+
+## Sessions, bots and deletion
+
+```console
+tcli config
+tcli --session work login
+tcli --session assistant login --bot
+tcli sessions --json
+tcli --session work delete me 123 124 --json
+tcli --session assistant send @example_channel "Status update"
+tcli --session assistant watch @example_channel --edits --json
+```
+
+Examples are placeholders; do not execute sends or deletes without explicit authorization.
+`--session NAME` can precede or follow the command. Names contain 1-32 lowercase ASCII
+letters/digits, underscores or hyphens, starting with a letter/digit; Windows device names
+are rejected. `default` keeps the existing `account.session`. Other sessions live under
+`sessions/NAME/account.session` in the same local data directory. API configuration is shared;
+`config` updates it for all sessions. `sessions` lists local file presence offline, not account
+identity or authorization. `doctor --connect` shows the selected account type. `logout` revokes
+only the selected session. Use different session names for different accounts, and avoid
+concurrent processes on the same session. Choosing a new name does not copy existing authorization.
+
+`login --bot` reads a token via hidden input or `TG_BOT_TOKEN`, only during login. It does not
+store the token in config or accept it as a command-line argument. Existing authorized sessions
+are reused; login never switches accounts in place. A different account type requires another
+session name. Tokens and session files grant account access; never commit or share them.
+
+| Operation | Bot session |
+| --- | --- |
+| Send text/files/albums, forward, edit outgoing messages | Supported, subject to Telegram access and posting permissions |
+| Delete specific IDs | Supported within Telegram permissions; deleting others' messages may require admin rights |
+| `read --id`, `thread`, single `download` including `--resume`, `info` | Supported for accessible known messages/chats; Telegram may reject requests |
+| `watch`, `watch --edits` | Live MTProto events only; no history polling or replay guarantee after downtime |
+| `chats`, history reads/search/export, `pinned`, `topics`, `scheduled`, `send --schedule`, album/batch download | Rejected with `bot_unsupported` in this CLI |
+| Chat selectors | Known numeric ID or `@username`; titles and `me` are rejected |
+
+A bot has no Saved Messages and cannot initiate private conversations with arbitrary users:
+the user must first contact it or add it to a group. Groups/channels must grant the necessary
+rights. Group privacy mode affects incoming updates. A numeric peer must already be known to
+the selected session, usually from an update; a raw ID alone does not supply an access hash.
+This uses Telethon/MTProto, not the HTTP Bot API; HTTP Bot API file-size limits are not CLI limits.
+See [Telegram's bot FAQ](https://core.telegram.org/bots/faq),
+[history restriction](https://core.telegram.org/method/messages.getHistory), and
+[known-message retrieval](https://core.telegram.org/method/messages.getMessages).
+
+`delete CHAT ID [ID ...]` deletes for everyone (`revoke=True`), without an extra prompt.
+All requested messages are fetched and checked against the selected chat before any deletion;
+a missing ID or a different chat aborts the operation. Duplicate IDs are removed. This check
+is necessary because [Telethon does not validate the chat for deletion](https://docs.telethon.dev/en/stable/modules/client.html#telethon.client.messages.MessageMethods.delete_messages).
+JSON success is `{ok:true,requested_ids:[...]}`: Telegram accepted the request, but does not
+provide per-ID proof of deletion. Telegram determines permissions and message restrictions.
+Large sets may use several server requests and partially succeed before a failure; an uncertain
+network result is not proof that nothing was deleted. Deletion cannot be undone. Scheduled
+messages still use `scheduled --cancel`, not `delete`.
 
 ## Extended history and automation
 
@@ -331,7 +388,9 @@ the CLI displays metadata. Deletion and inline media playback are not supported.
 | Command | Purpose |
 | --- | --- |
 | `tcli config` | Save or replace API credentials |
-| `tcli login` | Sign in to your personal account |
+| `tcli login` | Sign in to a user account; add `--bot` for a bot |
+| `tcli sessions --json` | List local named session files offline |
+| `tcli delete CHAT ID [ID ...]` | Delete the selected messages for everyone |
 | `tcli chats --limit 100` | List up to 100 chats; default: 50 |
 | `tcli read "Chat" --limit 20` | Read recent messages; default: 20 |
 | `tcli send "Chat" "Text"` | Send one plain-text message |
@@ -483,12 +542,37 @@ Upload/download progress is enabled automatically when stderr is a terminal. `--
 it when redirected; `--no-progress` disables it. These flags apply to attachment sends and downloads.
 Progress includes transferred/total bytes, percentage, and average bytes per second; album upload
 progress is weighted by local file sizes. Updates are throttled to twice per second, plus completion.
+Human output includes a bar such as `[##########----------] 50.0%`. In a terminal it redraws
+in place; redirected output uses separate lines. Unknown sizes have an empty bar without a percentage.
 With `--json`, stderr receives JSONL events with `event="transfer_progress"`, `operation`, `file`,
 `transferred_bytes`, `total_bytes`, `percent` (null for unknown/zero size), and `bytes_per_second`.
 Errors are still JSON objects on stderr; distinguish them from progress by `ok=false`.
 Stdout contains only the final result. Progress measures transfer work, not confirmed delivery;
 cached uploads may produce no progress events.
 
+### Performance
+
+Install the optional native encryption accelerator from a source checkout:
+
+```console
+python -m pip install -e ".[fast]"
+python scripts/benchmark_crypto.py
+```
+
+Telethon automatically uses `cryptg` when installed, reducing encryption/decryption CPU work
+without changing message handling. The offline benchmark compares the existing fallback with
+cryptg on synthetic data and checks identical ciphertext and successful decryption; its speedup
+is for AES only, not end-to-end Telegram throughput. The base installation remains usable without it.
+See [Telethon's transfer FAQ](https://docs.telethon.dev/en/stable/quick-references/faq.html#file-download-is-slow-or-sending-files-takes-too-long).
+
+For faster workflows, forward existing Telegram attachments instead of downloading and uploading
+them again, use `--jsonl` for large history reads, and apply server-side date/sender/media filters
+before filename matching. Keep filename scan bounds as small as the task allows. Disable progress
+with `--no-progress` when measuring transfer speed. Avoid concurrent CLI processes on one session.
+Parallel transfers need separate measurement and careful FloodWait handling; they are not enabled.
+Resumable downloads already use Telethon's maximum default request size (512 KiB).
+Plain text has no byte-transfer callback: the CLI reports the confirmed message ID after sending.
+
 ### Text formatting
 
 ```console
@@ -655,7 +739,8 @@ Increase `--limit` if your chat is not in the first page.
 **Telegram asks you to wait?** Wait for the reported FloodWait period.
 After a connection failure, check recent history before retrying a send to avoid duplicates.
 
-**Can I use a bot?** This CLI supports personal accounts only.
+**Can I use a bot?** Yes: use a separate `--session NAME` and `login --bot`. See the capabilities
+and restrictions under [Sessions, bots and deletion](#sessions-bots-and-deletion).
 
 **Can I still run the Python file?** Yes: `python tg.py ...` from the project root
 with dependencies installed uses the same commands.

telegram_cli_local-0.3.0/telegram_cli_local.egg-info/PKG-INFO → telegram_cli_local-0.4.0/README.md

@@ -1,25 +1,3 @@
-Metadata-Version: 2.4
-Name: telegram-cli-local
-Version: 0.3.0
-Summary: Telegram CLI for a personal account
-Author: BYxarek
-License-Expression: Apache-2.0
-Project-URL: Repository, https://github.com/BYxarek/telegram-cli
-Project-URL: Issues, https://github.com/BYxarek/telegram-cli/issues
-Keywords: telegram,cli,telethon,agent-skills
-Classifier: Development Status :: 4 - Beta
-Classifier: Environment :: Console
-Classifier: Intended Audience :: End Users/Desktop
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Topic :: Communications :: Chat
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: Telethon==1.45.0
-Dynamic: license-file
-
 <div align="center">
 
 # tcli · Telegram in your terminal
@@ -50,8 +28,8 @@ tcli watch "Work chat"        # Follow new messages
 ```
 
 `tcli` is a local Python CLI built with [Telethon](https://docs.telethon.dev/).
-It uses the Telegram API and acts as your personal account. You need your own
-`API_ID` and `API_HASH`; no bot token is used.
+It uses Telegram's MTProto API with a personal account or a bot. Both modes require your own
+`API_ID` and `API_HASH`; bot login additionally requires a BotFather token.
 
 ## Features
 
@@ -71,8 +49,63 @@ are removed from displayed messages.
 
 ### Current scope
 
-One local account session, text and attachments, human-readable output, and optional JSON.
-Message deletion and a full-screen interface are not available.
+Named local user/bot sessions, text and attachments, message deletion, human-readable output,
+and optional JSON. A full-screen interface is not available.
+
+## Sessions, bots and deletion
+
+```console
+tcli config
+tcli --session work login
+tcli --session assistant login --bot
+tcli sessions --json
+tcli --session work delete me 123 124 --json
+tcli --session assistant send @example_channel "Status update"
+tcli --session assistant watch @example_channel --edits --json
+```
+
+Examples are placeholders; do not execute sends or deletes without explicit authorization.
+`--session NAME` can precede or follow the command. Names contain 1-32 lowercase ASCII
+letters/digits, underscores or hyphens, starting with a letter/digit; Windows device names
+are rejected. `default` keeps the existing `account.session`. Other sessions live under
+`sessions/NAME/account.session` in the same local data directory. API configuration is shared;
+`config` updates it for all sessions. `sessions` lists local file presence offline, not account
+identity or authorization. `doctor --connect` shows the selected account type. `logout` revokes
+only the selected session. Use different session names for different accounts, and avoid
+concurrent processes on the same session. Choosing a new name does not copy existing authorization.
+
+`login --bot` reads a token via hidden input or `TG_BOT_TOKEN`, only during login. It does not
+store the token in config or accept it as a command-line argument. Existing authorized sessions
+are reused; login never switches accounts in place. A different account type requires another
+session name. Tokens and session files grant account access; never commit or share them.
+
+| Operation | Bot session |
+| --- | --- |
+| Send text/files/albums, forward, edit outgoing messages | Supported, subject to Telegram access and posting permissions |
+| Delete specific IDs | Supported within Telegram permissions; deleting others' messages may require admin rights |
+| `read --id`, `thread`, single `download` including `--resume`, `info` | Supported for accessible known messages/chats; Telegram may reject requests |
+| `watch`, `watch --edits` | Live MTProto events only; no history polling or replay guarantee after downtime |
+| `chats`, history reads/search/export, `pinned`, `topics`, `scheduled`, `send --schedule`, album/batch download | Rejected with `bot_unsupported` in this CLI |
+| Chat selectors | Known numeric ID or `@username`; titles and `me` are rejected |
+
+A bot has no Saved Messages and cannot initiate private conversations with arbitrary users:
+the user must first contact it or add it to a group. Groups/channels must grant the necessary
+rights. Group privacy mode affects incoming updates. A numeric peer must already be known to
+the selected session, usually from an update; a raw ID alone does not supply an access hash.
+This uses Telethon/MTProto, not the HTTP Bot API; HTTP Bot API file-size limits are not CLI limits.
+See [Telegram's bot FAQ](https://core.telegram.org/bots/faq),
+[history restriction](https://core.telegram.org/method/messages.getHistory), and
+[known-message retrieval](https://core.telegram.org/method/messages.getMessages).
+
+`delete CHAT ID [ID ...]` deletes for everyone (`revoke=True`), without an extra prompt.
+All requested messages are fetched and checked against the selected chat before any deletion;
+a missing ID or a different chat aborts the operation. Duplicate IDs are removed. This check
+is necessary because [Telethon does not validate the chat for deletion](https://docs.telethon.dev/en/stable/modules/client.html#telethon.client.messages.MessageMethods.delete_messages).
+JSON success is `{ok:true,requested_ids:[...]}`: Telegram accepted the request, but does not
+provide per-ID proof of deletion. Telegram determines permissions and message restrictions.
+Large sets may use several server requests and partially succeed before a failure; an uncertain
+network result is not proof that nothing was deleted. Deletion cannot be undone. Scheduled
+messages still use `scheduled --cancel`, not `delete`.
 
 ## Extended history and automation
 
@@ -331,7 +364,9 @@ the CLI displays metadata. Deletion and inline media playback are not supported.
 | Command | Purpose |
 | --- | --- |
 | `tcli config` | Save or replace API credentials |
-| `tcli login` | Sign in to your personal account |
+| `tcli login` | Sign in to a user account; add `--bot` for a bot |
+| `tcli sessions --json` | List local named session files offline |
+| `tcli delete CHAT ID [ID ...]` | Delete the selected messages for everyone |
 | `tcli chats --limit 100` | List up to 100 chats; default: 50 |
 | `tcli read "Chat" --limit 20` | Read recent messages; default: 20 |
 | `tcli send "Chat" "Text"` | Send one plain-text message |
@@ -483,12 +518,37 @@ Upload/download progress is enabled automatically when stderr is a terminal. `--
 it when redirected; `--no-progress` disables it. These flags apply to attachment sends and downloads.
 Progress includes transferred/total bytes, percentage, and average bytes per second; album upload
 progress is weighted by local file sizes. Updates are throttled to twice per second, plus completion.
+Human output includes a bar such as `[##########----------] 50.0%`. In a terminal it redraws
+in place; redirected output uses separate lines. Unknown sizes have an empty bar without a percentage.
 With `--json`, stderr receives JSONL events with `event="transfer_progress"`, `operation`, `file`,
 `transferred_bytes`, `total_bytes`, `percent` (null for unknown/zero size), and `bytes_per_second`.
 Errors are still JSON objects on stderr; distinguish them from progress by `ok=false`.
 Stdout contains only the final result. Progress measures transfer work, not confirmed delivery;
 cached uploads may produce no progress events.
 
+### Performance
+
+Install the optional native encryption accelerator from a source checkout:
+
+```console
+python -m pip install -e ".[fast]"
+python scripts/benchmark_crypto.py
+```
+
+Telethon automatically uses `cryptg` when installed, reducing encryption/decryption CPU work
+without changing message handling. The offline benchmark compares the existing fallback with
+cryptg on synthetic data and checks identical ciphertext and successful decryption; its speedup
+is for AES only, not end-to-end Telegram throughput. The base installation remains usable without it.
+See [Telethon's transfer FAQ](https://docs.telethon.dev/en/stable/quick-references/faq.html#file-download-is-slow-or-sending-files-takes-too-long).
+
+For faster workflows, forward existing Telegram attachments instead of downloading and uploading
+them again, use `--jsonl` for large history reads, and apply server-side date/sender/media filters
+before filename matching. Keep filename scan bounds as small as the task allows. Disable progress
+with `--no-progress` when measuring transfer speed. Avoid concurrent CLI processes on one session.
+Parallel transfers need separate measurement and careful FloodWait handling; they are not enabled.
+Resumable downloads already use Telethon's maximum default request size (512 KiB).
+Plain text has no byte-transfer callback: the CLI reports the confirmed message ID after sending.
+
 ### Text formatting
 
 ```console
@@ -655,7 +715,8 @@ Increase `--limit` if your chat is not in the first page.
 **Telegram asks you to wait?** Wait for the reported FloodWait period.
 After a connection failure, check recent history before retrying a send to avoid duplicates.
 
-**Can I use a bot?** This CLI supports personal accounts only.
+**Can I use a bot?** Yes: use a separate `--session NAME` and `login --bot`. See the capabilities
+and restrictions under [Sessions, bots and deletion](#sessions-bots-and-deletion).
 
 **Can I still run the Python file?** Yes: `python tg.py ...` from the project root
 with dependencies installed uses the same commands.

{telegram_cli_local-0.3.0 → telegram_cli_local-0.4.0}/README.ru.md

@@ -27,8 +27,8 @@ tcli watch 'Рабочий чат'
 ```
 
 `tcli` — небольшой локальный клиент на Python и [Telethon](https://docs.telethon.dev/).
-Он использует Telegram API и действует от вашего имени. Для работы нужны личный
-Telegram-аккаунт и собственные `API_ID` / `API_HASH`.
+Он использует Telegram MTProto API с личным аккаунтом или ботом. В обоих режимах нужны
+собственные `API_ID` / `API_HASH`; для входа ботом также требуется токен BotFather.
 
 ## Возможности
 
@@ -48,8 +48,64 @@ Telegram-аккаунт и собственные `API_ID` / `API_HASH`.
 
 ### Текущие ограничения
 
-Поддерживаются текст, вложения и одна локальная сессия аккаунта.
-Нет удаления сообщений и полноэкранного интерфейса.
+Поддерживаются текст, вложения, удаление сообщений и именованные сессии пользователей и ботов.
+Полноэкранного интерфейса нет.
+
+## Сессии, боты и удаление сообщений
+
+```console
+tcli config
+tcli --session work login
+tcli --session assistant login --bot
+tcli sessions --json
+tcli --session work delete me 123 124 --json
+tcli --session assistant send @example_channel "Обновление статуса"
+tcli --session assistant watch @example_channel --edits --json
+```
+
+Получатели и ID в примерах условные. Отправка и удаление требуют явного поручения пользователя.
+`--session ИМЯ` можно ставить перед командой или после неё. Имя: 1-32 строчные латинские буквы,
+цифры, `_` или `-`, первый символ — буква или цифра; зарезервированные имена Windows запрещены.
+Сессия `default` сохраняет прежний `account.session`. Остальные хранятся в
+`sessions/ИМЯ/account.session` внутри каталога данных CLI. API-настройки общие: `config` меняет
+их для всех сессий. `sessions` без сети показывает наличие файлов, а не личность или авторизацию.
+`doctor --connect` показывает тип аккаунта. `logout` отзывает только выбранную сессию.
+Для разных аккаунтов выбирайте разные имена; не запускайте одновременно несколько процессов
+с одной сессией. Новое имя не копирует авторизацию старой сессии.
+
+`login --bot` принимает токен скрытым вводом или из `TG_BOT_TOKEN` только при входе.
+Токен не записывается в config и не передаётся аргументом командной строки. Для бота по-прежнему
+нужны `API_ID` и `API_HASH`. Уже авторизованная сессия используется повторно; вход не заменяет
+аккаунт внутри неё. При другом типе аккаунта требуется отдельное имя сессии.
+Токены и файлы сессий дают доступ к аккаунту: не публикуйте и не коммитьте их.
+
+| Операция | Работа через бота |
+| --- | --- |
+| Отправка текста, файлов и альбомов, пересылка, правка исходящих | Поддерживается с учётом доступа и права отправки |
+| Удаление по ID | В пределах прав Telegram; для чужих сообщений могут требоваться права администратора |
+| `read --id`, `thread`, одиночный `download`, включая `--resume`, `info` | Для доступных известных сообщений и чатов; сервер может отказать |
+| `watch`, `watch --edits` | Только события MTProto, без опроса истории и гарантированного восстановления после простоя |
+| `chats`, чтение/поиск/экспорт истории, `pinned`, `topics`, `scheduled`, `send --schedule`, скачивание альбомом/пакетом | В этом CLI отклоняются с `bot_unsupported` |
+| Выбор чата | Известный числовой ID или `@username`; названия и `me` недоступны |
+
+У бота нет Избранного. Он не может первым писать произвольному пользователю: пользователь должен
+сначала обратиться к боту или добавить его в группу. В группах и каналах нужны соответствующие
+права; privacy mode влияет на входящие события в группах. Числовой ID должен быть уже известен
+выбранной сессии, например из события: сам ID не содержит access hash.
+Используется Telethon/MTProto, а не HTTP Bot API; лимиты размера файлов HTTP Bot API не являются
+лимитами CLI. Источники: [FAQ Telegram](https://core.telegram.org/bots/faq),
+[ограничение истории](https://core.telegram.org/method/messages.getHistory),
+[получение известных сообщений](https://core.telegram.org/method/messages.getMessages).
+
+`delete ЧАТ ID [ID ...]` удаляет сообщения для всех (`revoke=True`) без дополнительного вопроса.
+До удаления CLI получает все указанные сообщения и проверяет принадлежность выбранному чату.
+Отсутствующий ID или другой чат прерывает операцию; повторы ID исключаются. Такая проверка нужна,
+поскольку [Telethon сам не проверяет чат при удалении](https://docs.telethon.dev/en/stable/modules/client.html#telethon.client.messages.MessageMethods.delete_messages).
+JSON-ответ `{ok:true,requested_ids:[...]}` означает принятие запроса сервером, а не отдельное
+подтверждение каждого удалённого ID. Права и ограничения сообщений проверяет Telegram.
+Большой список может обрабатываться несколькими запросами и частично выполниться до ошибки;
+сетевой сбой не доказывает, что ничего не удалено. Отменить удаление нельзя.
+Для отложенных сообщений используйте `scheduled --cancel`.
 Доступны ответы на сообщения и JSON-вывод для автоматизации.
 
 ## Расширенная история и автоматизация
@@ -309,7 +365,9 @@ tcli download me 123 --output photo.jpg
 | `tcli` / `tcli help` | Показывает общую справку, первые шаги и примеры |
 | `tcli help send` | Показывает справку по конкретной команде |
 | `tcli config` | Сохраняет или заменяет API-данные |
-| `tcli login` | Выполняет вход в личный аккаунт |
+| `tcli login` | Вход в аккаунт пользователя; `--bot` для бота |
+| `tcli sessions --json` | Список локальных именованных сессий без сети |
+| `tcli delete CHAT ID [ID ...]` | Удаление выбранных сообщений для всех |
 | `tcli chats --limit 100` | Показывает до 100 чатов; по умолчанию — 50 |
 | `tcli read 'Чат' --limit 20` | Читает последние сообщения; по умолчанию — 20 |
 | `tcli send 'Чат' 'Текст'` | Отправляет текстовое сообщение |
@@ -464,6 +522,8 @@ tcli download me 123 --output archive.zip --progress --json
 
 Прогресс загрузки и скачивания включён автоматически, когда stderr подключён к терминалу.
 `--progress` включает его при перенаправлении, `--no-progress` отключает.
+Текстовый вывод содержит полосу `[##########----------] 50.0%`: в терминале она обновляется
+на месте, при перенаправлении — отдельными строками. При неизвестном размере процент не выводится.
 Флаги доступны для отправки вложений и скачивания. Выводятся переданные/общие байты,
 процент и средняя скорость в байтах в секунду. Прогресс отправки альбома учитывает размеры файлов.
 Обновления ограничены двумя в секунду, кроме завершения. С `--json` в stderr идут JSONL-события:
@@ -473,6 +533,30 @@ tcli download me 123 --output archive.zip --progress --json
 В stdout остаётся только итоговый результат. Прогресс передачи не подтверждает доставку;
 при использовании кэша события могут отсутствовать.
 
+### Производительность
+
+Установка из исходников с нативным ускорителем шифрования:
+
+```console
+python -m pip install -e ".[fast]"
+python scripts/benchmark_crypto.py
+```
+
+Telethon автоматически использует установленный `cryptg`, снижая нагрузку на процессор при
+шифровании и расшифровке. Локальный бенчмарк сравнивает прежний механизм с cryptg на искусственных
+данных, проверяет совпадение шифротекста и расшифровку. Коэффициент ускорения относится только
+к AES, а не к скорости передачи через Telegram. Базовая установка работает и без ускорителя.
+См. [рекомендации Telethon](https://docs.telethon.dev/en/stable/quick-references/faq.html#file-download-is-slow-or-sending-files-takes-too-long).
+
+Для ускорения работы пересылайте существующие вложения через `forward`, используйте `--jsonl`
+для большой истории и серверные фильтры даты, отправителя и типа медиа перед поиском по имени файла.
+Ограничивайте объём сканирования необходимым минимумом. Для замера скорости отключайте вывод
+через `--no-progress`. Избегайте одновременных процессов CLI с одной сессией.
+Параллельные передачи требуют отдельных замеров и обработки FloodWait; они не включены.
+Докачивание уже использует максимальный стандартный размер запроса Telethon — 512 КиБ.
+У обычного текста нет callback с количеством переданных байтов: после отправки CLI показывает
+подтверждённый ID сообщения.
+
 ### Оформление текста
 
 ```console
@@ -638,7 +722,8 @@ tests/                Проверки без реального аккаунт
 Если виртуальное окружение ссылается на удалённую установку, пересоздайте его и установите проект заново.
 Не скрывайте stderr: там также выводятся настоящие ошибки CLI.
 
-**Можно ли использовать бота?** Этот CLI предназначен для личного аккаунта. Вход ботом не поддерживается.
+**Можно ли использовать бота?** Да: отдельная `--session ИМЯ` и `login --bot`.
+Возможности и ограничения перечислены в разделе «Сессии, боты и удаление сообщений».
 
 **Почему чат не найден?** Используйте точное название, `@username` или ID из `tcli chats`.
 Если нужного диалога нет в списке, увеличьте `--limit`.