telegram-cli-local 0.1.0__tar.gz → 0.2.1__tar.gz

{telegram_cli_local-0.1.0 → telegram_cli_local-0.2.1}/.agents/skills/telegram-cli/SKILL.md

@@ -1,90 +1,26 @@
 ---
 name: telegram-cli
-description: Operate and develop this project's personal-account Telegram CLI (tcli). Use for chats, message search/history, plain or formatted sending, JSON automation, watching, configuration, login, and diagnostics.
+description: Use the personal-account Telegram CLI (tcli). Use for chats, message search/history, plain or formatted sending, JSON automation, watching, configuration, login, and diagnostics.
 ---
 
 # Telegram CLI
 
-This skill contains the complete project reference; no separate guide is required.
-The source repository contains `tg.py`, `requirements.txt`, and `pyproject.toml` at its root.
-An installed user skill is independent of the repository; do not infer a project path from its location.
-Use the installed `tcli` command from any directory. Run development and installation commands from the project root.
-Respond in the user's requested language; English CLI output does not require English conversation replies.
-Keep the Codex, Claude Code, and bundled `tcli_skills/SKILL.md` copies identical when updating them.
-
-## Project map
-
-A local Python 3.10+ CLI for one personal Telegram account, using Telethon and MTProto.
-No bot, HTTP server, application database, or FTP deployment is involved.
-
-| Location | Responsibility |
-| --- | --- |
-| `tg.py: parser()` | argparse commands, help text, examples, limits |
-| `tg.py: main()` | Help dispatch before credentials, paths, errors, asyncio entry point |
-| `validate_credentials()` / `load_credentials()` / `configure()` | Validate credentials, environment/file precedence, atomic local configuration |
-| `run()` | Connect, authenticate, execute commands, disconnect in finally |
-| `resolve_chat()` | me/@username via Telethon; numeric IDs and exact titles via dialogs |
-| `safe_text()` / `show_message()` | Strip terminal control characters and display messages |
-| `message_data()` | Serialize message fields for JSON and JSONL output |
-| `install_skills()` / `atomic_write()` | Offline user-skill installation, backups, and atomic file replacement |
-| `tcli_skills/` | Version and bundled portable SKILL.md included in wheels |
-| `pyproject.toml` | `tcli` entry point calling `tg:main`; dependencies from requirements.txt |
-| `tests/test_tg.py` | Offline unit tests and help subprocess checks |
-| `README.md` / `README.ru.md` | English and Russian user documentation |
-
-Use Semble to locate implementations when available, then read the matching functions and callers.
-Current code and command help take precedence over stale documentation.
-The CLI, developer documentation, and agent instructions are English; preserve Unicode chat names and messages.
+Use `tcli` to work with the user's personal Telegram account from any directory.
+Respond in the user's requested language; CLI output is English.
+Use `tcli help COMMAND` to check available options.
 
 ## Setup
 
 Install the published CLI with `pipx install telegram-cli-local`.
 Update it with `pipx upgrade telegram-cli-local`, then run `tcli skills install` to update user skills.
-Source installation from a clone is also supported as described below.
-`tcli --version` reports the CLI version.
-
-Install from this local project with `py -m pip install --user -e .` on Windows.
-The user scripts directory must be in PATH. If tcli is not found, run in PowerShell:
-
-```powershell
-$tcliScriptsDir = (py -c "import sysconfig; print(sysconfig.get_path('scripts', scheme='nt_user'))").Trim()
-$tcliUserPath = [Environment]::GetEnvironmentVariable('Path', 'User')
-if (($tcliUserPath -split ';') -notcontains $tcliScriptsDir) {
-    $tcliUpdatedPath = (($tcliUserPath + ';' + $tcliScriptsDir).Trim(';'))
-    [Environment]::SetEnvironmentVariable('Path', $tcliUpdatedPath, 'User')
-}
-$env:Path = $tcliScriptsDir + ';' + $env:Path
-```
-
-New terminals inherit the saved PATH; restart existing terminals or their parent application if needed.
-If pip is missing, run `py -m ensurepip --upgrade --user` before installing.
-Do not install an unrelated similarly named package from PyPI.
-Editable installation depends on the source folder; reinstall if it moves.
-The installed `tcli` command works outside the project root.
-
-For development, run from the project root:
-
-```powershell
-py -m venv .venv
-.\.venv\Scripts\python.exe -m pip install -e .
-.\.venv\Scripts\tcli.exe help
-.\.venv\Scripts\python.exe -X utf8 -m unittest discover -s tests -v
-```
-
-On POSIX use `python3 -m venv .venv`, `.venv/bin/python`, and `.venv/bin/tcli`.
-No activation is needed with those explicit paths.
-On this Windows machine, `py` is available; the system `python` alias may open Microsoft Store.
-If an agent process has an old PATH, refresh its environment or use the installed executable's full path.
+`tcli --version` reports the installed version.
 
 ## Help and commands
 
 `tcli`, `tcli help`, `tcli --help`, and `tcli -h` display general help and exit successfully.
 `tcli help send` is equivalent to `tcli send --help`; this applies to every subcommand.
 Help does not load credentials, create Telegram sessions, or connect to Telegram.
-Interactive general help (no arguments, help, --help, -h) checks PyPI for a newer stable x.y.z release.
-It uses a one-second network timeout and a 24-hour cache at data-directory/cache/update-check.json,
-including failed attempts. It only reports updates on stderr, never installs them automatically.
-Network/cache errors are silent. Redirected stdout, command-specific help, and --version skip checks.
+Interactive general help may report a newer release on stderr; it never installs updates automatically.
 Set TCLI_NO_UPDATE_CHECK=1 to disable checks and their cache writes entirely.
 Unknown commands, unknown help topics, and invalid arguments remain usage errors (exit 2).
 
@@ -98,6 +34,15 @@ Unknown commands, unknown help topics, and invalid arguments remain usage errors
 | `tcli send me "Text"` | Send literal text to Saved Messages |
 | `tcli send @username "Text"` | Send to a username |
 | `tcli send -- -1001234567890 "Text"` | Send by negative ID |
+| `tcli send me --attach photo.jpg --caption "Photo"` | Upload a photo, video, audio, or any Telegram-supported local file |
+| `tcli send me --attach archive.zip --as-file` | Force document upload; preserve the original file |
+| `tcli download me 123 --output photo.jpg` | Download the attachment from message 123 into a new local file |
+| `tcli read "Chat" --id 123 --json` | Get one message with reply and album IDs |
+| `tcli read "Chat" --media document --json` | Filter media using Telegram search |
+| `tcli send me --attach app.apk archive.zip --caption "App" --caption "Archive" --json` | Send files individually in order |
+| `tcli send me --attach first.jpg second.jpg --album --json` | Send 2-10 compatible attachments as one album |
+| `tcli download me 123 --album --output-dir downloads --json` | Download the album containing message 123 |
+| `tcli edit me 123 "Corrected text" --json` | Edit outgoing message text or attachment caption |
 | `tcli watch "Chat name"` | New messages until Ctrl+C; blocks the process |
 | `tcli logout` | Revoke this CLI session and remove its session file; keep API credentials |
 | `tcli doctor` | Validate effective credentials and session-file presence locally; show paths, never secret values |
@@ -119,16 +64,37 @@ Increase `chats --limit` if necessary. Do not invent IDs. Partial names and t.me
 Limits must be positive integers. `read` does not mark messages as read.
 
 Message output: `[local date and time] sender ID or you (#message ID): text`.
-Missing text displays `[media or service message]`.
+Downloadable media displays its type, filename (if available), MIME type, and size in bytes, alongside any caption.
+Other messages without text display `[media or service message]`.
 Human-readable output removes control characters. Optional JSON preserves original text using escaped
 Unicode/control characters. Chat fields: id, name, unread_count. Message fields: id, chat_id,
-date (ISO 8601 with offset), sender_id (nullable), out, text (empty when absent), has_media.
+date (ISO 8601 with offset), sender_id (nullable), out, text (empty when absent), has_media, media, reply_to_id, grouped_id.
+reply_to_id and grouped_id are null when absent; human output also shows these IDs.
+Use read --id with reply_to_id to retrieve the original message of a reply.
+`media` is null for messages without a downloadable photo/document; otherwise it contains
+type (photo, video, audio, voice, video_note, gif, sticker, document), name, mime_type, size (bytes),
+ext, width, height, duration (seconds). Unavailable metadata fields are null.
+Link previews and other Telegram media may have has_media=true with media=null.
 `chats --json` and `read --json` output arrays, including [] for no results.
 `watch --json` outputs JSONL with status/errors only on stderr.
 `read --search QUERY` uses Telegram text search in the selected chat; each page is oldest first.
 `--before ID` is exclusive; use the smallest returned ID for the next page, also with search.
 `--before` and `--reply-to` require positive message IDs from the same chat.
-`send` requires exactly one nonempty source: positional text, --stdin, or --file PATH.
+`send` requires exactly one source: positional text, --stdin, --file PATH, or --attach PATH.
+Text sources must be nonempty. --attach uploads one or more existing local files per command,
+including binary documents such as .exe, .apk, .zip; attachments are never decoded as text.
+Telethon selects photo/video/audio/document representation; --as-file forces a document.
+--caption supplies optional text with --attach only; --as-file and --album also require --attach.
+Repeat --caption in attachment order; missing captions are empty. Use --caption "" to skip one.
+Without --album, files are sent individually in order. --album sends 2-10 compatible attachments
+as a group via Telethon; incompatible Telegram album combinations may produce RPC errors.
+A single caption belongs to the first attachment. All paths and caption counts are checked before connecting.
+Captions support --format and --reply-to. File type and size limits are enforced by Telegram.
+`download CHAT ID --output PATH` saves the attachment of one message in that chat.
+Use IDs from read/watch. The destination parent must exist; existing files are never overwritten.
+Remote filenames are metadata only and never select a local path. Failed/cancelled downloads remove
+the partial destination. Download photos are Telegram's stored version, not necessarily the original.
+To view the content, open the downloaded file with a local application; the CLI displays metadata.
 Stdin/files use UTF-8 with optional BOM; whitespace and line breaks are preserved, blank input rejected
 before connecting. PowerShell pipelines must emit UTF-8 (set $OutputEncoding if necessary).
 --file sends text, not an attachment. All sources support --reply-to ID and --format plain|markdown|html.
@@ -138,19 +104,81 @@ HTML supports b/strong, i/em, u, s/del, code, pre, a href, blockquote (including
 and pre/code class="language-python" for code-block language. Use actual newlines, not br tags.
 The installed Telethon parser ignores unsupported HTML tags and does not support spoiler markup.
 Formatting may trim surrounding whitespace. Use HTML for nested formatting.
-No attachments, editing, deletion, or interactive conversation UI.
+No message deletion or interactive conversation UI.
 `doctor` is local, creates no files, and exits 1 for invalid credentials or missing session.
 File presence does not prove authorization. --connect can update the existing Telethon session.
-`watch` records the latest ID before announcing readiness, then polls every two seconds using
-min_id and reverse order with no fixed batch limit. It includes sends from another CLI process
-and Saved Messages. Session writes are committed before idle waits to release SQLite locks.
+`watch` shows new messages, including sends from another CLI process and Saved Messages.
 Messages deleted before polling cannot be seen. `watch` has no past history; prefer `read` for a one-time request.
 
+## Automation, context, filters, and editing
+
+`read CHAT --id ID` fetches one message or fails with message_not_found. JSON remains an array
+with one item. --id cannot combine with --around, --before, or search/media/filename filters; --limit applies only to history.
+`read --media photo|video|document|audio|voice|video_note|gif` uses native Telegram filters;
+audio means music. Filters combine with --search, --before, and --limit.
+Search follows Telegram text-search semantics, not local filename/extension matching.
+
+`edit CHAT ID TEXT`, `edit CHAT ID --file PATH`, or `edit CHAT ID --stdin` edits outgoing text
+or a caption. Exactly one nonblank UTF-8 text source is required. --format plain|markdown|html
+works as for send. Use a message ID from history and check that the message is outgoing before editing.
+Telegram enforces edit permissions and time limits; unchanged text can raise an RPC error.
+Editing does not replace attachments or clear captions with empty text.
+
+`download CHAT ID --album --output-dir DIR` downloads the album containing that message.
+--output-dir requires --album, excludes --output, and must already exist.
+Telegram albums have at most ten items; message IDs can have gaps.
+Save as <message_id><extension>, with .bin for missing/unsafe extensions; never use remote filenames.
+Existing destination files are never overwritten.
+Keep completed files on failure and remove the current partial file. Missing/deleted/inaccessible
+album items cannot be recovered. Download JSON keeps captions and grouped_id without sidecar files.
+
+With --json, send outputs {"ok": true, "messages": [message objects]}, edit outputs
+{"ok": true, "message": message object}, and download outputs {"ok": true, "files": [file objects]}.
+File fields: message_id, chat_id, path (absolute), text (caption), grouped_id (nullable).
+chats/read arrays and watch JSONL keep their existing shapes, with the added message fields.
+
+Handled errors for commands with --json go to stderr as one JSON object:
+{"ok": false, "error": {"code": "flood_wait", "message": "...", "retry_after": 17}}.
+retry_after is seconds for FloodWait, null otherwise. RPC errors include rpc_type and rpc_code.
+Codes: usage_error, invalid_input, configuration_error, unauthorized, chat_not_found, ambiguous_chat,
+message_not_found, not_outgoing, edit_failed, not_an_album, no_attachment, file_exists, flood_wait,
+rpc_error, network_error, io_error, database_error, cancelled.
+Argument errors exit 2; handled failures exit 1; interruption exits 130. Watch status stays plain text
+on stderr. After a partial operation, error JSON includes messages/files with confirmed completed results.
+Do not automatically retry uncertain send/edit failures: inspect history to avoid duplicate actions.
+
+## Filename search, surrounding context, forwarding, and progress
+
+`read CHAT --filename "*.apk" --scan-limit 1000 --limit 5 --json` matches original attachment
+names locally with case-insensitive glob patterns (*, ?, [abc]). Messages without names are skipped.
+--scan-limit (default 1000) bounds the newest messages inspected after Telegram search/media filters;
+--limit bounds matches. Results stay oldest first. Combine with --before, --search, or --media.
+No matches in the bounded scan do not prove absence across the whole chat. --scan-limit requires --filename.
+
+`read CHAT --around ID --context N` fetches the selected message and up to N neighbors on each side
+(default 5), ordered chronologically. IDs need not be consecutive. Missing anchor: message_not_found.
+--around excludes --id, --before, --search, --media, --filename, and --scan-limit.
+--context requires --around. --limit only applies to history and filename search.
+
+`forward FROM_CHAT ID TO_CHAT [--json]` forwards one message, attachment and caption included,
+using native Telegram forwarding without local download/upload. Standard chat selectors apply on
+both sides. Preserve attribution. Telegram enforces protected-content and posting restrictions.
+JSON success uses the send shape: {"ok": true, "messages": [message object]}.
+Forward only on explicit user instruction with known source, message ID, and destination.
+Development/testing does not authorize live forwarding. Verify history before retrying an uncertain failure.
+
+send (attachments only) and download support --progress / --no-progress.
+Default: enabled when stderr is a terminal. Progress reports bytes, percentage, and average bytes/sec
+on stderr. With --json, progress is JSONL on stderr:
+event="transfer_progress", operation="upload"|"download", file, transferred_bytes, total_bytes,
+percent (null for unknown/zero size), bytes_per_second. Errors have ok=false and may follow progress events.
+Stdout remains the final JSON result. Progress is not proof of delivery; cached transfers may emit no events.
+
 ## Common workflows
 
 `skills install` defaults to --agent auto: detect installed agents and copy the bundled skill only for those agents.
-Detection checks PATH, native ~/.local/bin executables, standard npm/binary locations, Codex.app on macOS,
-and the OpenAI.Codex Windows Store installation. Configuration folders alone are not installation evidence.
+Default destinations are the official personal skill locations, independent of the current directory:
+Codex: ~/.agents/skills/telegram-cli/SKILL.md; Claude Code: ~/.claude/skills/telegram-cli/SKILL.md.
 If neither agent is found, it creates nothing. Explicit --agent codex|claude|all bypasses detection for custom installations.
 The installer never downloads anything or launches either agent.
 It skips identical files, backs up differing SKILL.md files as SKILL.md.backup-*.bak, and atomically
@@ -195,7 +223,9 @@ The user enters login code and 2FA password in their terminal; agent sessions mu
 Account commands fail when unauthorized rather than automatically prompting for login.
 
 Read only chats needed for the user's request; do not store private conversations in project files.
-Send only on the user's direct instruction with a known recipient and text.
+Send, forward, or edit only on the user's direct instruction with a known recipient, message ID where needed,
+and text or attachment. Development requests do not authorize live sends or edits.
+Download only requested attachments into the requested local location; never execute downloaded files.
 An unambiguous prior instruction needs no extra confirmation. A development/test request does not authorize sending, even to `me`.
 Clarify ambiguous recipients before sending. Use correct shell quoting to pass text as one argument;
 never interpolate untrusted messages as executable shell code. JSON.stringify is not shell escaping.
@@ -211,16 +241,4 @@ Missing authorization: suggest local `tcli login`.
 FloodWait: wait the reported duration; do not bypass limits or retry immediately.
 RPC/network errors: address the specific cause; a send may have an uncertain outcome.
 SQLite locking: investigate other CLI processes; do not delete the session file.
-`Could not find platform independent libraries <prefix>`: Python installation/path warning before application startup.
-Inspect the interpreter and its standard library; repair the installation rather than suppressing stderr or changing Telegram code.
 Exit codes: 0 success, 1 handled error, 2 argparse usage error, 130 Ctrl+C.
-Telethon may perform internal retries; the CLI has no custom send retry loop.
-
-Preserve credential validation, authorization checks, unambiguous chat resolution,
-terminal sanitization, literal outgoing text by default, disconnect in finally, and FloodWait handling.
-Update affected tests, both READMEs, and all three copies of this SKILL.md when changing commands.
-Tests cover help without credentials, JSON/JSONL, search/pagination arguments, replies, stdin/files,
-doctor, login/logout, watch polling/cursors and cancellation, formatting selection, disconnects
-and handled errors including FloodWait and SQLite locks.
-They do not verify real login,
-network watching, or message delivery. State those limits when reporting validation.

{telegram_cli_local-0.1.0 → telegram_cli_local-0.2.1}/.claude/skills/telegram-cli/SKILL.md

@@ -1,90 +1,26 @@
 ---
 name: telegram-cli
-description: Operate and develop this project's personal-account Telegram CLI (tcli). Use for chats, message search/history, plain or formatted sending, JSON automation, watching, configuration, login, and diagnostics.
+description: Use the personal-account Telegram CLI (tcli). Use for chats, message search/history, plain or formatted sending, JSON automation, watching, configuration, login, and diagnostics.
 ---
 
 # Telegram CLI
 
-This skill contains the complete project reference; no separate guide is required.
-The source repository contains `tg.py`, `requirements.txt`, and `pyproject.toml` at its root.
-An installed user skill is independent of the repository; do not infer a project path from its location.
-Use the installed `tcli` command from any directory. Run development and installation commands from the project root.
-Respond in the user's requested language; English CLI output does not require English conversation replies.
-Keep the Codex, Claude Code, and bundled `tcli_skills/SKILL.md` copies identical when updating them.
-
-## Project map
-
-A local Python 3.10+ CLI for one personal Telegram account, using Telethon and MTProto.
-No bot, HTTP server, application database, or FTP deployment is involved.
-
-| Location | Responsibility |
-| --- | --- |
-| `tg.py: parser()` | argparse commands, help text, examples, limits |
-| `tg.py: main()` | Help dispatch before credentials, paths, errors, asyncio entry point |
-| `validate_credentials()` / `load_credentials()` / `configure()` | Validate credentials, environment/file precedence, atomic local configuration |
-| `run()` | Connect, authenticate, execute commands, disconnect in finally |
-| `resolve_chat()` | me/@username via Telethon; numeric IDs and exact titles via dialogs |
-| `safe_text()` / `show_message()` | Strip terminal control characters and display messages |
-| `message_data()` | Serialize message fields for JSON and JSONL output |
-| `install_skills()` / `atomic_write()` | Offline user-skill installation, backups, and atomic file replacement |
-| `tcli_skills/` | Version and bundled portable SKILL.md included in wheels |
-| `pyproject.toml` | `tcli` entry point calling `tg:main`; dependencies from requirements.txt |
-| `tests/test_tg.py` | Offline unit tests and help subprocess checks |
-| `README.md` / `README.ru.md` | English and Russian user documentation |
-
-Use Semble to locate implementations when available, then read the matching functions and callers.
-Current code and command help take precedence over stale documentation.
-The CLI, developer documentation, and agent instructions are English; preserve Unicode chat names and messages.
+Use `tcli` to work with the user's personal Telegram account from any directory.
+Respond in the user's requested language; CLI output is English.
+Use `tcli help COMMAND` to check available options.
 
 ## Setup
 
 Install the published CLI with `pipx install telegram-cli-local`.
 Update it with `pipx upgrade telegram-cli-local`, then run `tcli skills install` to update user skills.
-Source installation from a clone is also supported as described below.
-`tcli --version` reports the CLI version.
-
-Install from this local project with `py -m pip install --user -e .` on Windows.
-The user scripts directory must be in PATH. If tcli is not found, run in PowerShell:
-
-```powershell
-$tcliScriptsDir = (py -c "import sysconfig; print(sysconfig.get_path('scripts', scheme='nt_user'))").Trim()
-$tcliUserPath = [Environment]::GetEnvironmentVariable('Path', 'User')
-if (($tcliUserPath -split ';') -notcontains $tcliScriptsDir) {
-    $tcliUpdatedPath = (($tcliUserPath + ';' + $tcliScriptsDir).Trim(';'))
-    [Environment]::SetEnvironmentVariable('Path', $tcliUpdatedPath, 'User')
-}
-$env:Path = $tcliScriptsDir + ';' + $env:Path
-```
-
-New terminals inherit the saved PATH; restart existing terminals or their parent application if needed.
-If pip is missing, run `py -m ensurepip --upgrade --user` before installing.
-Do not install an unrelated similarly named package from PyPI.
-Editable installation depends on the source folder; reinstall if it moves.
-The installed `tcli` command works outside the project root.
-
-For development, run from the project root:
-
-```powershell
-py -m venv .venv
-.\.venv\Scripts\python.exe -m pip install -e .
-.\.venv\Scripts\tcli.exe help
-.\.venv\Scripts\python.exe -X utf8 -m unittest discover -s tests -v
-```
-
-On POSIX use `python3 -m venv .venv`, `.venv/bin/python`, and `.venv/bin/tcli`.
-No activation is needed with those explicit paths.
-On this Windows machine, `py` is available; the system `python` alias may open Microsoft Store.
-If an agent process has an old PATH, refresh its environment or use the installed executable's full path.
+`tcli --version` reports the installed version.
 
 ## Help and commands
 
 `tcli`, `tcli help`, `tcli --help`, and `tcli -h` display general help and exit successfully.
 `tcli help send` is equivalent to `tcli send --help`; this applies to every subcommand.
 Help does not load credentials, create Telegram sessions, or connect to Telegram.
-Interactive general help (no arguments, help, --help, -h) checks PyPI for a newer stable x.y.z release.
-It uses a one-second network timeout and a 24-hour cache at data-directory/cache/update-check.json,
-including failed attempts. It only reports updates on stderr, never installs them automatically.
-Network/cache errors are silent. Redirected stdout, command-specific help, and --version skip checks.
+Interactive general help may report a newer release on stderr; it never installs updates automatically.
 Set TCLI_NO_UPDATE_CHECK=1 to disable checks and their cache writes entirely.
 Unknown commands, unknown help topics, and invalid arguments remain usage errors (exit 2).
 
@@ -98,6 +34,15 @@ Unknown commands, unknown help topics, and invalid arguments remain usage errors
 | `tcli send me "Text"` | Send literal text to Saved Messages |
 | `tcli send @username "Text"` | Send to a username |
 | `tcli send -- -1001234567890 "Text"` | Send by negative ID |
+| `tcli send me --attach photo.jpg --caption "Photo"` | Upload a photo, video, audio, or any Telegram-supported local file |
+| `tcli send me --attach archive.zip --as-file` | Force document upload; preserve the original file |
+| `tcli download me 123 --output photo.jpg` | Download the attachment from message 123 into a new local file |
+| `tcli read "Chat" --id 123 --json` | Get one message with reply and album IDs |
+| `tcli read "Chat" --media document --json` | Filter media using Telegram search |
+| `tcli send me --attach app.apk archive.zip --caption "App" --caption "Archive" --json` | Send files individually in order |
+| `tcli send me --attach first.jpg second.jpg --album --json` | Send 2-10 compatible attachments as one album |
+| `tcli download me 123 --album --output-dir downloads --json` | Download the album containing message 123 |
+| `tcli edit me 123 "Corrected text" --json` | Edit outgoing message text or attachment caption |
 | `tcli watch "Chat name"` | New messages until Ctrl+C; blocks the process |
 | `tcli logout` | Revoke this CLI session and remove its session file; keep API credentials |
 | `tcli doctor` | Validate effective credentials and session-file presence locally; show paths, never secret values |
@@ -119,16 +64,37 @@ Increase `chats --limit` if necessary. Do not invent IDs. Partial names and t.me
 Limits must be positive integers. `read` does not mark messages as read.
 
 Message output: `[local date and time] sender ID or you (#message ID): text`.
-Missing text displays `[media or service message]`.
+Downloadable media displays its type, filename (if available), MIME type, and size in bytes, alongside any caption.
+Other messages without text display `[media or service message]`.
 Human-readable output removes control characters. Optional JSON preserves original text using escaped
 Unicode/control characters. Chat fields: id, name, unread_count. Message fields: id, chat_id,
-date (ISO 8601 with offset), sender_id (nullable), out, text (empty when absent), has_media.
+date (ISO 8601 with offset), sender_id (nullable), out, text (empty when absent), has_media, media, reply_to_id, grouped_id.
+reply_to_id and grouped_id are null when absent; human output also shows these IDs.
+Use read --id with reply_to_id to retrieve the original message of a reply.
+`media` is null for messages without a downloadable photo/document; otherwise it contains
+type (photo, video, audio, voice, video_note, gif, sticker, document), name, mime_type, size (bytes),
+ext, width, height, duration (seconds). Unavailable metadata fields are null.
+Link previews and other Telegram media may have has_media=true with media=null.
 `chats --json` and `read --json` output arrays, including [] for no results.
 `watch --json` outputs JSONL with status/errors only on stderr.
 `read --search QUERY` uses Telegram text search in the selected chat; each page is oldest first.
 `--before ID` is exclusive; use the smallest returned ID for the next page, also with search.
 `--before` and `--reply-to` require positive message IDs from the same chat.
-`send` requires exactly one nonempty source: positional text, --stdin, or --file PATH.
+`send` requires exactly one source: positional text, --stdin, --file PATH, or --attach PATH.
+Text sources must be nonempty. --attach uploads one or more existing local files per command,
+including binary documents such as .exe, .apk, .zip; attachments are never decoded as text.
+Telethon selects photo/video/audio/document representation; --as-file forces a document.
+--caption supplies optional text with --attach only; --as-file and --album also require --attach.
+Repeat --caption in attachment order; missing captions are empty. Use --caption "" to skip one.
+Without --album, files are sent individually in order. --album sends 2-10 compatible attachments
+as a group via Telethon; incompatible Telegram album combinations may produce RPC errors.
+A single caption belongs to the first attachment. All paths and caption counts are checked before connecting.
+Captions support --format and --reply-to. File type and size limits are enforced by Telegram.
+`download CHAT ID --output PATH` saves the attachment of one message in that chat.
+Use IDs from read/watch. The destination parent must exist; existing files are never overwritten.
+Remote filenames are metadata only and never select a local path. Failed/cancelled downloads remove
+the partial destination. Download photos are Telegram's stored version, not necessarily the original.
+To view the content, open the downloaded file with a local application; the CLI displays metadata.
 Stdin/files use UTF-8 with optional BOM; whitespace and line breaks are preserved, blank input rejected
 before connecting. PowerShell pipelines must emit UTF-8 (set $OutputEncoding if necessary).
 --file sends text, not an attachment. All sources support --reply-to ID and --format plain|markdown|html.
@@ -138,19 +104,81 @@ HTML supports b/strong, i/em, u, s/del, code, pre, a href, blockquote (including
 and pre/code class="language-python" for code-block language. Use actual newlines, not br tags.
 The installed Telethon parser ignores unsupported HTML tags and does not support spoiler markup.
 Formatting may trim surrounding whitespace. Use HTML for nested formatting.
-No attachments, editing, deletion, or interactive conversation UI.
+No message deletion or interactive conversation UI.
 `doctor` is local, creates no files, and exits 1 for invalid credentials or missing session.
 File presence does not prove authorization. --connect can update the existing Telethon session.
-`watch` records the latest ID before announcing readiness, then polls every two seconds using
-min_id and reverse order with no fixed batch limit. It includes sends from another CLI process
-and Saved Messages. Session writes are committed before idle waits to release SQLite locks.
+`watch` shows new messages, including sends from another CLI process and Saved Messages.
 Messages deleted before polling cannot be seen. `watch` has no past history; prefer `read` for a one-time request.
 
+## Automation, context, filters, and editing
+
+`read CHAT --id ID` fetches one message or fails with message_not_found. JSON remains an array
+with one item. --id cannot combine with --around, --before, or search/media/filename filters; --limit applies only to history.
+`read --media photo|video|document|audio|voice|video_note|gif` uses native Telegram filters;
+audio means music. Filters combine with --search, --before, and --limit.
+Search follows Telegram text-search semantics, not local filename/extension matching.
+
+`edit CHAT ID TEXT`, `edit CHAT ID --file PATH`, or `edit CHAT ID --stdin` edits outgoing text
+or a caption. Exactly one nonblank UTF-8 text source is required. --format plain|markdown|html
+works as for send. Use a message ID from history and check that the message is outgoing before editing.
+Telegram enforces edit permissions and time limits; unchanged text can raise an RPC error.
+Editing does not replace attachments or clear captions with empty text.
+
+`download CHAT ID --album --output-dir DIR` downloads the album containing that message.
+--output-dir requires --album, excludes --output, and must already exist.
+Telegram albums have at most ten items; message IDs can have gaps.
+Save as <message_id><extension>, with .bin for missing/unsafe extensions; never use remote filenames.
+Existing destination files are never overwritten.
+Keep completed files on failure and remove the current partial file. Missing/deleted/inaccessible
+album items cannot be recovered. Download JSON keeps captions and grouped_id without sidecar files.
+
+With --json, send outputs {"ok": true, "messages": [message objects]}, edit outputs
+{"ok": true, "message": message object}, and download outputs {"ok": true, "files": [file objects]}.
+File fields: message_id, chat_id, path (absolute), text (caption), grouped_id (nullable).
+chats/read arrays and watch JSONL keep their existing shapes, with the added message fields.
+
+Handled errors for commands with --json go to stderr as one JSON object:
+{"ok": false, "error": {"code": "flood_wait", "message": "...", "retry_after": 17}}.
+retry_after is seconds for FloodWait, null otherwise. RPC errors include rpc_type and rpc_code.
+Codes: usage_error, invalid_input, configuration_error, unauthorized, chat_not_found, ambiguous_chat,
+message_not_found, not_outgoing, edit_failed, not_an_album, no_attachment, file_exists, flood_wait,
+rpc_error, network_error, io_error, database_error, cancelled.
+Argument errors exit 2; handled failures exit 1; interruption exits 130. Watch status stays plain text
+on stderr. After a partial operation, error JSON includes messages/files with confirmed completed results.
+Do not automatically retry uncertain send/edit failures: inspect history to avoid duplicate actions.
+
+## Filename search, surrounding context, forwarding, and progress
+
+`read CHAT --filename "*.apk" --scan-limit 1000 --limit 5 --json` matches original attachment
+names locally with case-insensitive glob patterns (*, ?, [abc]). Messages without names are skipped.
+--scan-limit (default 1000) bounds the newest messages inspected after Telegram search/media filters;
+--limit bounds matches. Results stay oldest first. Combine with --before, --search, or --media.
+No matches in the bounded scan do not prove absence across the whole chat. --scan-limit requires --filename.
+
+`read CHAT --around ID --context N` fetches the selected message and up to N neighbors on each side
+(default 5), ordered chronologically. IDs need not be consecutive. Missing anchor: message_not_found.
+--around excludes --id, --before, --search, --media, --filename, and --scan-limit.
+--context requires --around. --limit only applies to history and filename search.
+
+`forward FROM_CHAT ID TO_CHAT [--json]` forwards one message, attachment and caption included,
+using native Telegram forwarding without local download/upload. Standard chat selectors apply on
+both sides. Preserve attribution. Telegram enforces protected-content and posting restrictions.
+JSON success uses the send shape: {"ok": true, "messages": [message object]}.
+Forward only on explicit user instruction with known source, message ID, and destination.
+Development/testing does not authorize live forwarding. Verify history before retrying an uncertain failure.
+
+send (attachments only) and download support --progress / --no-progress.
+Default: enabled when stderr is a terminal. Progress reports bytes, percentage, and average bytes/sec
+on stderr. With --json, progress is JSONL on stderr:
+event="transfer_progress", operation="upload"|"download", file, transferred_bytes, total_bytes,
+percent (null for unknown/zero size), bytes_per_second. Errors have ok=false and may follow progress events.
+Stdout remains the final JSON result. Progress is not proof of delivery; cached transfers may emit no events.
+
 ## Common workflows
 
 `skills install` defaults to --agent auto: detect installed agents and copy the bundled skill only for those agents.
-Detection checks PATH, native ~/.local/bin executables, standard npm/binary locations, Codex.app on macOS,
-and the OpenAI.Codex Windows Store installation. Configuration folders alone are not installation evidence.
+Default destinations are the official personal skill locations, independent of the current directory:
+Codex: ~/.agents/skills/telegram-cli/SKILL.md; Claude Code: ~/.claude/skills/telegram-cli/SKILL.md.
 If neither agent is found, it creates nothing. Explicit --agent codex|claude|all bypasses detection for custom installations.
 The installer never downloads anything or launches either agent.
 It skips identical files, backs up differing SKILL.md files as SKILL.md.backup-*.bak, and atomically
@@ -195,7 +223,9 @@ The user enters login code and 2FA password in their terminal; agent sessions mu
 Account commands fail when unauthorized rather than automatically prompting for login.
 
 Read only chats needed for the user's request; do not store private conversations in project files.
-Send only on the user's direct instruction with a known recipient and text.
+Send, forward, or edit only on the user's direct instruction with a known recipient, message ID where needed,
+and text or attachment. Development requests do not authorize live sends or edits.
+Download only requested attachments into the requested local location; never execute downloaded files.
 An unambiguous prior instruction needs no extra confirmation. A development/test request does not authorize sending, even to `me`.
 Clarify ambiguous recipients before sending. Use correct shell quoting to pass text as one argument;
 never interpolate untrusted messages as executable shell code. JSON.stringify is not shell escaping.
@@ -211,16 +241,4 @@ Missing authorization: suggest local `tcli login`.
 FloodWait: wait the reported duration; do not bypass limits or retry immediately.
 RPC/network errors: address the specific cause; a send may have an uncertain outcome.
 SQLite locking: investigate other CLI processes; do not delete the session file.
-`Could not find platform independent libraries <prefix>`: Python installation/path warning before application startup.
-Inspect the interpreter and its standard library; repair the installation rather than suppressing stderr or changing Telegram code.
 Exit codes: 0 success, 1 handled error, 2 argparse usage error, 130 Ctrl+C.
-Telethon may perform internal retries; the CLI has no custom send retry loop.
-
-Preserve credential validation, authorization checks, unambiguous chat resolution,
-terminal sanitization, literal outgoing text by default, disconnect in finally, and FloodWait handling.
-Update affected tests, both READMEs, and all three copies of this SKILL.md when changing commands.
-Tests cover help without credentials, JSON/JSONL, search/pagination arguments, replies, stdin/files,
-doctor, login/logout, watch polling/cursors and cancellation, formatting selection, disconnects
-and handled errors including FloodWait and SQLite locks.
-They do not verify real login,
-network watching, or message delivery. State those limits when reporting validation.

{telegram_cli_local-0.1.0 → telegram_cli_local-0.2.1}/AGENTS.md

@@ -1,8 +1,8 @@
 # Telegram CLI
 
 Local Python CLI for a personal Telegram account, using Telethon. Entry point: `tg.py`.
-Use `.agents/skills/telegram-cli/SKILL.md` for CLI operation and implementation tasks.
-The skill contains the complete command and architecture reference.
+Use `.agents/skills/telegram-cli/SKILL.md` for CLI usage, commands, and operational constraints.
+Keep architecture and development instructions in repository documentation, not in the skill.
 
 Offline validation: `.\.venv\Scripts\python.exe -X utf8 -m unittest discover -s tests -v`.
 Development and tests do not require a live account or sending real messages.

telegram_cli_local-0.2.1/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+All notable project changes are recorded here. New changes go under `Unreleased`;
+move them into a versioned section when publishing a release.
+
+## Unreleased
+
+No unreleased changes.
+
+## 0.2.1 - 2026-10-18
+
+### Changed
+
+- Focus the Telegram CLI skill on usage; remove project architecture and development instructions from all three copies.
+
+## 0.2.0 - 2026-10-18
+
+### Added
+
+- Bounded, case-insensitive filename glob search with `read --filename` and `--scan-limit`.
+- Conversation context with `read --around ID --context N`, using history order even when IDs have gaps.
+- Native forwarding of messages and attachments with `forward FROM_CHAT ID TO_CHAT`, including JSON results.
+- Automatic terminal upload/download progress, explicit `--progress` / `--no-progress`, JSONL progress
+  events on stderr, byte counts, percentages, average transfer speed, and size-weighted album progress.
+- Offline regression tests for filename search, context, forwarding restrictions, progress throttling,
+  album byte accounting, and clean JSON stdout.
+- Include this changelog in source distributions and check new command help in clean wheel installations.
+
+- Upload local photos, videos, audio, and arbitrary binary documents (including
+  `.exe`, `.apk`, and `.zip`) with `send --attach`; use `--as-file` to force document upload.
+- Attachment captions with text formatting and reply targets; repeat `--caption`
+  to provide a separate caption for each attachment.
+- Send multiple files individually in order, or group 2-10 compatible attachments
+  with `send --album`.
+- Download individual attachments by message ID with `download --output` and
+  download entire albums with `download --album --output-dir`.
+- Safe downloads: exclusive file creation, collision checks, ID-based album filenames,
+  safe extensions, and removal of the current partial file after failure or cancellation.
+- Display attachment type, filename, MIME type, and size in `read` and `watch`;
+  expose dimensions, duration, and other metadata in JSON.
+- Read a specific message with `read --id`; include reply and album IDs in message output.
+- Filter history with `read --media photo|video|document|audio|voice|video_note|gif`,
+  combined with Telegram text search and pagination.
+- Edit outgoing message text or attachment captions with `edit`, using positional
+  text, UTF-8 files, or stdin and optional Markdown/HTML formatting.
+- JSON results for sending, editing, and downloading, including captions and album
+  IDs in downloaded-file records.
+- Structured JSON errors on stderr with stable codes, FloodWait retry delays,
+  RPC details, and confirmed completed results after partial multi-file operations.
+- Offline tests for binary uploads, metadata, JSON contracts, filters, edits,
+  ordered files and albums, validation, safe downloads, cancellation, and partial failures.
+- This changelog and a requirement to update it alongside future changes.
+
+### Changed
+
+- Explain in both READMEs that the project was created specifically to help AI agents
+  manage Telegram chats effectively.
+- Expand English and Russian documentation and synchronize all three bundled/project
+  skill copies with the new commands and automation workflows.
+- Clarify the existing official user-skill destinations in installer help and documentation:
+  `~/.agents/skills/telegram-cli/SKILL.md` for Codex and
+  `~/.claude/skills/telegram-cli/SKILL.md` for Claude Code.
+  Default installation still targets detected agents and backs up differing skills.
+
+### Compatibility
+
+- `send --file` still sends UTF-8 file contents as text; `--attach` uploads binary files.
+- Existing `chats`/`read` JSON arrays and `watch` JSONL retain their shapes, with
+  additional message fields. Human-readable output remains the default.
+- Message deletion, inline media playback, and automatic retries remain unsupported.