PyPI - telegram-cli-local - Versions diffs - 0.3.0__tar.gz → 0.5.0__tar.gz - Mend

telegram-cli-local 0.3.0tar.gz → 0.5.0tar.gz

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 (30) hide show

{telegram_cli_local-0.3.0 → telegram_cli_local-0.5.0}/.agents/skills/telegram-cli/SKILL.md RENAMED Viewed

@@ -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,12 +34,16 @@ 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` |
 | Download one attachment | `tcli download me 123 --output archive.zip --json` |
 | Configure API credentials locally | `tcli config` |
-| Sign in interactively in the user's terminal | `tcli login` |
+| Sign in interactively in the user's terminal | `tcli login` or `tcli login --qr` |
 | Check local setup, optionally connectivity | `tcli doctor` or `tcli doctor --connect` |
 | End this CLI session when requested | `tcli logout` |
 | Refresh supported agent skills offline | `tcli skills install --agent all` |
@@ -48,10 +52,41 @@ 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`.
+Phone login reports where Telegram sent the code. If it does not arrive, run `tcli login --qr`
+in a terminal and scan it in Telegram mobile under Settings > Devices > Link Desktop Device.
+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 +305,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.5.0}/.claude/skills/telegram-cli/SKILL.md RENAMED Viewed

@@ -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,12 +34,16 @@ 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` |
 | Download one attachment | `tcli download me 123 --output archive.zip --json` |
 | Configure API credentials locally | `tcli config` |
-| Sign in interactively in the user's terminal | `tcli login` |
+| Sign in interactively in the user's terminal | `tcli login` or `tcli login --qr` |
 | Check local setup, optionally connectivity | `tcli doctor` or `tcli doctor --connect` |
 | End this CLI session when requested | `tcli logout` |
 | Refresh supported agent skills offline | `tcli skills install --agent all` |
@@ -48,10 +52,41 @@ 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`.
+Phone login reports where Telegram sent the code. If it does not arrive, run `tcli login --qr`
+in a terminal and scan it in Telegram mobile under Settings > Devices > Link Desktop Device.
+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 +305,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.5.0}/CHANGELOG.md RENAMED Viewed

@@ -7,6 +7,25 @@ move them into a versioned section when publishing a release.
 No unreleased changes.
+## 0.5.0 - 2026-11-11
+- Show the delivery method chosen by Telegram during phone login.
+- Add `login --qr` for sign-in with an already authorized Telegram mobile app.
+- Pipeline up to four upload blocks per attachment to reduce time spent waiting for Telegram.
+## 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.5.0}/PKG-INFO RENAMED Viewed

@@ -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.5.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,9 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: Telethon==1.45.0
+Requires-Dist: qrcode==8.2
+Provides-Extra: fast
+Requires-Dist: cryptg<0.7,>=0.5.2; extra == "fast"
 Dynamic: license-file
 <div align="center">
@@ -50,8 +53,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 +74,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
@@ -268,6 +326,10 @@ tcli login
 It does not connect to Telegram. Run it again to replace credentials; invalid input leaves existing settings intact.
 `login` asks for your international phone number, Telegram login code, and 2FA password if enabled.
+The CLI displays the delivery method chosen by Telegram. If Telegram sends an in-app code,
+open the service chat named **Telegram** on an already signed-in device.
+If the code does not arrive, run `tcli login --qr` in a terminal and scan the QR code in the
+Telegram mobile app under **Settings → Devices → Link Desktop Device**.
 Code and password input is hidden. The session is saved for later commands.
 ### 3. Read and send
@@ -331,7 +393,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 by phone or with `--qr`; use `--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 +547,39 @@ 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.
+For local attachments larger than 512 KiB, `send --attach` keeps up to four 512 KiB blocks
+in flight over one Telegram connection. This also applies to individual files in an album.
+Progress counts acknowledged bytes, and the CLI submits the message after all its blocks are saved.
+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 +746,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.5.0/README.md RENAMED Viewed

@@ -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
@@ -268,6 +301,10 @@ tcli login
 It does not connect to Telegram. Run it again to replace credentials; invalid input leaves existing settings intact.
 `login` asks for your international phone number, Telegram login code, and 2FA password if enabled.
+The CLI displays the delivery method chosen by Telegram. If Telegram sends an in-app code,
+open the service chat named **Telegram** on an already signed-in device.
+If the code does not arrive, run `tcli login --qr` in a terminal and scan the QR code in the
+Telegram mobile app under **Settings → Devices → Link Desktop Device**.
 Code and password input is hidden. The session is saved for later commands.
 ### 3. Read and send
@@ -331,7 +368,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 by phone or with `--qr`; use `--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 +522,39 @@ 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.
+For local attachments larger than 512 KiB, `send --attach` keeps up to four 512 KiB blocks
+in flight over one Telegram connection. This also applies to individual files in an album.
+Progress counts acknowledged bytes, and the CLI submits the message after all its blocks are saved.
+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 +721,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__tar.gz → 0.5.0__tar.gz

telegram-cli-local 0.3.0tar.gz → 0.5.0tar.gz