pytgcli 0.9.1__tar.gz → 0.11.0__tar.gz

{pytgcli-0.9.1 → pytgcli-0.11.0}/.github/workflows/ci.yml

@@ -10,7 +10,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
       - run: uv sync --group dev
       - run: uv run ruff check
       - run: uv run ruff format --check
@@ -22,7 +22,7 @@ jobs:
         python-version: ["3.12", "3.13"]
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
       - run: uv python install ${{ matrix.python-version }}
       - run: uv sync --group dev
       - run: uv run pytest

{pytgcli-0.9.1 → pytgcli-0.11.0}/.github/workflows/publish.yml

@@ -33,7 +33,7 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ github.ref_name }}
-      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
       - run: uv build
       - uses: actions/upload-artifact@v7
         with:
@@ -76,7 +76,7 @@ jobs:
         with:
           name: dist
           path: dist
-      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
       - run: uv publish --trusted-publishing always dist/*
 
   update-homebrew-tap:
@@ -88,14 +88,15 @@ jobs:
       contents: read
     env:
       TAP_REPO: tksohishi/homebrew-tap
-      TAP_TOKEN: ${{ secrets.TAP_GH_TOKEN }}
     steps:
-      - name: Validate tap token
-        run: |
-          if [ -z "${TAP_TOKEN}" ]; then
-            echo "TAP_GH_TOKEN is required to update homebrew-tap."
-            exit 1
-          fi
+      - name: Mint tap token
+        id: tap-token
+        uses: actions/create-github-app-token@v3
+        with:
+          app-id: ${{ secrets.TAP_APP_ID }}
+          private-key: ${{ secrets.TAP_APP_PRIVATE_KEY }}
+          owner: tksohishi
+          repositories: homebrew-tap
 
       - name: Resolve PyPI source artifact
         env:
@@ -121,7 +122,7 @@ jobs:
 
       - name: Update formula in tap repo
         run: |
-          git clone "https://x-access-token:${TAP_TOKEN}@github.com/${TAP_REPO}.git" tap-repo
+          git clone "https://x-access-token:${{ steps.tap-token.outputs.token }}@github.com/${TAP_REPO}.git" tap-repo
           python3 <<'PY'
           import os
           import re

{pytgcli-0.9.1 → pytgcli-0.11.0}/AGENTS.md

@@ -9,6 +9,7 @@ src/tgcli/
   client.py       # Telethon wrapper (search, read, context)
   config.py       # Config loading (TOML + env vars)
   formatting.py   # Pure output formatting functions (no I/O)
+  media.py        # Attachment safety rules: extension allowlist, magic bytes (stdlib only)
   session.py      # Keychain-backed StringSession via keyring (cross-platform)
   update.py       # Update checking, install method detection (stdlib only)
 tests/              # pytest + pytest-asyncio, Telethon fully mocked

{pytgcli-0.9.1 → pytgcli-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: pytgcli
-Version: 0.9.1
+Version: 0.11.0
 Summary: CLI tool to read Telegram messages from the terminal
 Project-URL: Repository, https://github.com/tksohishi/tgcli
 Author: Takeshi
@@ -24,13 +24,13 @@ Description-Content-Type: text/markdown
 
 # ✈️ tgcli — Telegram for your terminal and your AI agents.
 
-Give AI agents (Claude Code, Codex, Cursor, etc.) direct access to your Telegram conversations. Structured JSONL output, minimal command surface, fuzzy name resolution. Works equally well for humans with `--pretty`.
+Give AI agents (Claude Code, Codex, Cursor, etc.) direct access to your Telegram conversations. Structured JSONL output, minimal command surface, partial chat name matching. Works equally well for humans with `--pretty`.
 
 ## Features
 
 - **JSONL by default** — one JSON object per line; agents parse it natively, scripts pipe it freely
 - **Minimal surface** — a handful of commands; easy for agents to discover and invoke
-- **Fuzzy resolution** — chat and user names match by display name (no numeric IDs required)
+- **Chat name resolution**: exact display names take priority; a unique substring also matches
 - **`--pretty` for humans** — Rich tables when you want to read output yourself
 - **Agent-friendly session storage** — Telethon session key stored in a local `0600` file by default; keychain remains available as a legacy option
 
@@ -91,6 +91,12 @@ tg read "Finance Team" -q "deadline" --from "Alice" --after 2025-01-01
 tg context "Finance Team" 12345
 ```
 
+### 5. Download Attachments
+
+```bash
+tg media "Finance Team" 12345 --out ./downloads
+```
+
 ## Use with AI Agents
 
 Once authenticated, any AI coding agent with shell access can use tgcli directly. A few examples:
@@ -110,9 +116,12 @@ The agent runs `tg read "Alice" -q "deployment" --after 2025-02-14` and surfaces
 **Pipe into scripts:**
 
 ```bash
+set -o pipefail
 tg read "Alerts" --limit 100 | jq 'select(.text | test("ERROR"))'
 ```
 
+`pipefail` preserves a failed `tg read` exit status when `jq` succeeds. A chat lookup failure exits with code 1 and writes a human-readable error plus one JSON error line to stderr. Agents should check the exit status before treating empty stdout as “no messages.”
+
 No wrapper libraries or API adapters needed. The structured output and simple command surface mean agents can use tgcli out of the box.
 
 ## Commands
@@ -132,16 +141,41 @@ Explicit subcommands:
 
 List your Telegram chats. Returns JSONL by default.
 
+Each JSON object includes `id`, the Telethon dialog entity's numeric ID. Pass it to `read`, `context`, or `media` to skip name matching entirely:
+
+```bash
+tg chats --filter "Alice"
+tg read 123456789 --limit 20
+```
+
 | Flag       | Description                  |
 |------------|------------------------------|
-| `--filter` | Fuzzy filter by chat name    |
-| `--limit`  | Max chats to list (default 100) |
+| `--filter` | Case-insensitive substring filter by chat name |
+| `--limit`  | Max dialogs to scan before filtering (default 100) |
 | `--pretty` | Rich table output instead of JSONL |
 
+Increase `--limit` if a chat is outside the scanned set.
+
 ### `tg read <chat>`
 
 Read recent messages from a chat. Returns JSONL by default, newest first.
 
+`<chat>` accepts a display name, `@username`, phone number, `me`, or numeric ID. Display names use case-insensitive exact matching first, then substring matching. A single substring match resolves automatically, so `tg read "Alice Morgan"` can open a DM named `Alice Morgan | Example Team`. It prints `Resolved "Alice Morgan" -> "Alice Morgan | Example Team"` on stderr, keeping stdout clean for pipes. Exact matches produce no resolution notice. Multiple substring matches fail with candidate names listed one per line. If no candidates exist, the error suggests `tg chats --filter`.
+
+These lookup rules also apply to `context` and `media`. Numeric IDs, including negative group/channel IDs, skip name matching entirely. Put `--` before a negative positional ID so the CLI does not parse it as an option:
+
+```bash
+tg read --limit 20 -- -1001234567890
+```
+
+Lookup failures exit with code 1 and print both a human-readable message and a single JSON line to stderr. For an ambiguous name, the JSON looks like:
+
+```json
+{"error": "chat_not_found", "query": "Alice", "candidates": ["Alice Morgan | Example Team", "Alice Chen"]}
+```
+
+When no substring matches, similar spellings are offered as suggestions without opening a chat. `candidates` is an empty list when there are no suggestions.
+
 | Flag           | Description                            |
 |----------------|----------------------------------------|
 | `--query`/`-q` | Filter messages by text                |
@@ -152,6 +186,22 @@ Read recent messages from a chat. Returns JSONL by default, newest first.
 | `--before`     | Only messages before date (YYYY-MM-DD) |
 | `--pretty`     | Rich table output instead of JSONL     |
 
+JSONL fields: `id`, `text`, `chat_name`, `sender_name`, `sender_username`, `sender_id`, `date`, `reply_to_msg_id`, `media_type`, `media_filename`. `media_type` is `null` or one of `photo`, `document`, `video`, `voice`, `sticker`, `webpage`, `other`; `media_filename` is the document's original filename when present. `--pretty` marks attachments with a `[photo]`-style tag.
+
+### `tg media <chat> <message_id>`
+
+Download the attachment of one message. Prints a single JSON line with `id`, `path`, and `media_type`. Fails when the message has no downloadable media (webpage previews count as no media) or the id is not found.
+
+Only known media and document types are saved (images, video, audio, PDF, office files, text). Archives (zip, 7z, tar, gz, rar) need `--allow-archives`. Executables, scripts, installers, shortcuts, disk images, HTML, SVG, and XML are refused by extension and mime type. After the transfer, the file's leading and trailing bytes are checked too: Windows, ELF, and Mach-O binaries, shebang scripts, Windows shortcuts, cabinet and installer packages, DMG and ISO images, and archives or compound files renamed to a document extension are deleted and reported. Office documents with macros, RTF, and CSV are still saved; they are documents, not programs, so open them with the same care as any attachment. Attachments are refused before transfer when the reported size exceeds `--max-size` MB (default 100), and the transfer itself is cut off at that limit.
+
+tgcli chooses the saved filename itself: `<message_id>_<sanitized original name>`, or `<media_type>_<message_id>.<ext>` when the message has no filename. It downloads into a staging file it created, never overwrites an existing file, and never follows a symlink in the output directory.
+
+| Flag               | Description                            |
+|--------------------|----------------------------------------|
+| `--out`            | Directory to save into (default cwd)   |
+| `--allow-archives` | Also download zip/7z/tar/gz/rar files  |
+| `--max-size`       | Size limit in MB (default 100)         |
+
 ### `tg update`
 
 Upgrade tgcli to the latest version. Detects the install method and runs the right command (or tells you what to run for Homebrew installs).

{pytgcli-0.9.1 → pytgcli-0.11.0}/README.md

@@ -1,12 +1,12 @@
 # ✈️ tgcli — Telegram for your terminal and your AI agents.
 
-Give AI agents (Claude Code, Codex, Cursor, etc.) direct access to your Telegram conversations. Structured JSONL output, minimal command surface, fuzzy name resolution. Works equally well for humans with `--pretty`.
+Give AI agents (Claude Code, Codex, Cursor, etc.) direct access to your Telegram conversations. Structured JSONL output, minimal command surface, partial chat name matching. Works equally well for humans with `--pretty`.
 
 ## Features
 
 - **JSONL by default** — one JSON object per line; agents parse it natively, scripts pipe it freely
 - **Minimal surface** — a handful of commands; easy for agents to discover and invoke
-- **Fuzzy resolution** — chat and user names match by display name (no numeric IDs required)
+- **Chat name resolution**: exact display names take priority; a unique substring also matches
 - **`--pretty` for humans** — Rich tables when you want to read output yourself
 - **Agent-friendly session storage** — Telethon session key stored in a local `0600` file by default; keychain remains available as a legacy option
 
@@ -67,6 +67,12 @@ tg read "Finance Team" -q "deadline" --from "Alice" --after 2025-01-01
 tg context "Finance Team" 12345
 ```
 
+### 5. Download Attachments
+
+```bash
+tg media "Finance Team" 12345 --out ./downloads
+```
+
 ## Use with AI Agents
 
 Once authenticated, any AI coding agent with shell access can use tgcli directly. A few examples:
@@ -86,9 +92,12 @@ The agent runs `tg read "Alice" -q "deployment" --after 2025-02-14` and surfaces
 **Pipe into scripts:**
 
 ```bash
+set -o pipefail
 tg read "Alerts" --limit 100 | jq 'select(.text | test("ERROR"))'
 ```
 
+`pipefail` preserves a failed `tg read` exit status when `jq` succeeds. A chat lookup failure exits with code 1 and writes a human-readable error plus one JSON error line to stderr. Agents should check the exit status before treating empty stdout as “no messages.”
+
 No wrapper libraries or API adapters needed. The structured output and simple command surface mean agents can use tgcli out of the box.
 
 ## Commands
@@ -108,16 +117,41 @@ Explicit subcommands:
 
 List your Telegram chats. Returns JSONL by default.
 
+Each JSON object includes `id`, the Telethon dialog entity's numeric ID. Pass it to `read`, `context`, or `media` to skip name matching entirely:
+
+```bash
+tg chats --filter "Alice"
+tg read 123456789 --limit 20
+```
+
 | Flag       | Description                  |
 |------------|------------------------------|
-| `--filter` | Fuzzy filter by chat name    |
-| `--limit`  | Max chats to list (default 100) |
+| `--filter` | Case-insensitive substring filter by chat name |
+| `--limit`  | Max dialogs to scan before filtering (default 100) |
 | `--pretty` | Rich table output instead of JSONL |
 
+Increase `--limit` if a chat is outside the scanned set.
+
 ### `tg read <chat>`
 
 Read recent messages from a chat. Returns JSONL by default, newest first.
 
+`<chat>` accepts a display name, `@username`, phone number, `me`, or numeric ID. Display names use case-insensitive exact matching first, then substring matching. A single substring match resolves automatically, so `tg read "Alice Morgan"` can open a DM named `Alice Morgan | Example Team`. It prints `Resolved "Alice Morgan" -> "Alice Morgan | Example Team"` on stderr, keeping stdout clean for pipes. Exact matches produce no resolution notice. Multiple substring matches fail with candidate names listed one per line. If no candidates exist, the error suggests `tg chats --filter`.
+
+These lookup rules also apply to `context` and `media`. Numeric IDs, including negative group/channel IDs, skip name matching entirely. Put `--` before a negative positional ID so the CLI does not parse it as an option:
+
+```bash
+tg read --limit 20 -- -1001234567890
+```
+
+Lookup failures exit with code 1 and print both a human-readable message and a single JSON line to stderr. For an ambiguous name, the JSON looks like:
+
+```json
+{"error": "chat_not_found", "query": "Alice", "candidates": ["Alice Morgan | Example Team", "Alice Chen"]}
+```
+
+When no substring matches, similar spellings are offered as suggestions without opening a chat. `candidates` is an empty list when there are no suggestions.
+
 | Flag           | Description                            |
 |----------------|----------------------------------------|
 | `--query`/`-q` | Filter messages by text                |
@@ -128,6 +162,22 @@ Read recent messages from a chat. Returns JSONL by default, newest first.
 | `--before`     | Only messages before date (YYYY-MM-DD) |
 | `--pretty`     | Rich table output instead of JSONL     |
 
+JSONL fields: `id`, `text`, `chat_name`, `sender_name`, `sender_username`, `sender_id`, `date`, `reply_to_msg_id`, `media_type`, `media_filename`. `media_type` is `null` or one of `photo`, `document`, `video`, `voice`, `sticker`, `webpage`, `other`; `media_filename` is the document's original filename when present. `--pretty` marks attachments with a `[photo]`-style tag.
+
+### `tg media <chat> <message_id>`
+
+Download the attachment of one message. Prints a single JSON line with `id`, `path`, and `media_type`. Fails when the message has no downloadable media (webpage previews count as no media) or the id is not found.
+
+Only known media and document types are saved (images, video, audio, PDF, office files, text). Archives (zip, 7z, tar, gz, rar) need `--allow-archives`. Executables, scripts, installers, shortcuts, disk images, HTML, SVG, and XML are refused by extension and mime type. After the transfer, the file's leading and trailing bytes are checked too: Windows, ELF, and Mach-O binaries, shebang scripts, Windows shortcuts, cabinet and installer packages, DMG and ISO images, and archives or compound files renamed to a document extension are deleted and reported. Office documents with macros, RTF, and CSV are still saved; they are documents, not programs, so open them with the same care as any attachment. Attachments are refused before transfer when the reported size exceeds `--max-size` MB (default 100), and the transfer itself is cut off at that limit.
+
+tgcli chooses the saved filename itself: `<message_id>_<sanitized original name>`, or `<media_type>_<message_id>.<ext>` when the message has no filename. It downloads into a staging file it created, never overwrites an existing file, and never follows a symlink in the output directory.
+
+| Flag               | Description                            |
+|--------------------|----------------------------------------|
+| `--out`            | Directory to save into (default cwd)   |
+| `--allow-archives` | Also download zip/7z/tar/gz/rar files  |
+| `--max-size`       | Size limit in MB (default 100)         |
+
 ### `tg update`
 
 Upgrade tgcli to the latest version. Detects the install method and runs the right command (or tells you what to run for Homebrew installs).

{pytgcli-0.9.1 → pytgcli-0.11.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pytgcli"
-version = "0.9.1"
+version = "0.11.0"
 description = "CLI tool to read Telegram messages from the terminal"
 readme = "README.md"
 license = "MIT"

{pytgcli-0.9.1 → pytgcli-0.11.0}/src/tgcli/cli.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import asyncio
+import json
 import os
 import subprocess
 from datetime import UTC, datetime
@@ -23,11 +24,13 @@ app = typer.Typer(
         "Read Telegram messages from the terminal.\n\n"
         "Default output is JSONL. Use --pretty for human-readable output.\n\n"
         "Message JSONL fields: id, text, chat_name, sender_name, "
-        "sender_username, sender_id, date, reply_to_msg_id. "
+        "sender_username, sender_id, date, reply_to_msg_id, media_type, "
+        "media_filename. "
         "sender_username may be null; sender_id is the most stable sender key.\n\n"
         "Common flow: `tg chats` to find chat names, `tg read <chat>` to fetch "
         "or filter messages, `tg context <chat> <message_id>` to inspect nearby "
-        "messages, `tg auth` for login and status."
+        "messages, `tg media <chat> <message_id>` to download an attachment, "
+        "`tg auth` for login and status."
     )
 )
 auth_app = typer.Typer(
@@ -239,17 +242,43 @@ def _parse_date(value: str) -> datetime:
     return datetime.strptime(value, "%Y-%m-%d").replace(tzinfo=UTC)
 
 
+def _report_chat_resolution_error(error) -> None:
+    typer.echo(str(error), err=True)
+    typer.echo(
+        json.dumps(
+            {
+                "error": "chat_not_found",
+                "query": error.query,
+                "candidates": error.candidates,
+            },
+            ensure_ascii=False,
+        ),
+        err=True,
+    )
+
+
 @app.command()
 def chats(
     filter_: Annotated[
-        str | None, typer.Option("--filter", help="Fuzzy filter by chat name.")
+        str | None,
+        typer.Option(
+            "--filter", help="Case-insensitive substring filter by chat name."
+        ),
     ] = None,
-    limit: Annotated[int, typer.Option(help="Max chats to list.")] = 100,
+    limit: Annotated[
+        int, typer.Option(help="Max dialogs to scan before filtering.")
+    ] = 100,
     pretty: Annotated[
         bool, typer.Option("--pretty", help="Rich table output.")
     ] = False,
 ) -> None:
-    """List your Telegram chats."""
+    """List your Telegram chats.
+
+    JSONL includes id (Telethon dialog entity ID), name, chat_type,
+    unread_count, pinned, and date. Pass id to read, context, or media to
+    skip name matching entirely. Negative group/channel IDs are also accepted;
+    put options before -- and the negative ID after it: tg read -- -1001234567890.
+    """
     from tgcli.client import create_client, list_chats
 
     async def _run():
@@ -289,9 +318,19 @@ def chats(
     help=(
         "Read recent messages from a chat. Newest first by default (--head for "
         "oldest).\n\n"
+        "Chat names match case-insensitively: exact first, then a unique "
+        "substring. Substring matches print the resolved name on stderr. "
+        "Ambiguous or missing names exit 1 with a human-readable "
+        "error and one JSON line on stderr (error, query, candidates).\n\n"
+        "Pass an id from `tg chats` to skip name matching entirely. "
+        "Negative group/channel IDs are accepted: "
+        "`tg read --limit 20 -- -1001234567890`.\n\n"
         "Default JSONL includes id, text, chat_name, sender_name, "
-        "sender_username, sender_id, date, and reply_to_msg_id. "
-        "sender_username may be null; sender_id is the most stable sender key.\n\n"
+        "sender_username, sender_id, date, reply_to_msg_id, media_type, and "
+        "media_filename. sender_username may be null; sender_id is the most "
+        "stable sender key. media_type is null or one of photo, document, video, "
+        "voice, sticker, webpage, other; media_filename is the document's "
+        "original filename when present.\n\n"
         "--from accepts me, @username, bare username, numeric user ID, phone, "
         "or exact display name. Display names can be ambiguous; prefer username "
         "or numeric ID for automation.\n\n"
@@ -300,7 +339,9 @@ def chats(
     )
 )
 def read(
-    chat: Annotated[str, typer.Argument(help="Chat or person to read messages from.")],
+    chat: Annotated[
+        str, typer.Argument(help="Chat name, id, @username, phone, or me.")
+    ],
     query: Annotated[
         str | None, typer.Option("--query", "-q", help="Filter messages by text.")
     ] = None,
@@ -329,7 +370,7 @@ def read(
     ] = False,
 ) -> None:
     """Read recent messages from a chat."""
-    from tgcli.client import create_client, read_messages
+    from tgcli.client import ChatResolutionError, create_client, read_messages
 
     try:
         after_dt = _parse_date(after) if after else None
@@ -362,6 +403,9 @@ def read(
     except UnauthorizedError:
         stderr.print("[red]Not authenticated.[/red] Run `tg auth login` first.")
         raise typer.Exit(2)
+    except ChatResolutionError as e:
+        _report_chat_resolution_error(e)
+        raise typer.Exit(1)
     except Exception as e:
         stderr.print(f"[red]Read failed:[/red] {e}")
         raise typer.Exit(1)
@@ -384,8 +428,12 @@ def read(
 @app.command(
     help=(
         "View a message with surrounding context.\n\n"
-        "Default JSONL uses the same message fields as `read` and adds boolean "
-        "flags such as target and replied_to on relevant lines."
+        "Chat names use exact matching first, then a unique case-insensitive "
+        "substring. Pass an id from `tg chats` to skip name matching. "
+        "For negative IDs, put options before -- and the ID after it.\n\n"
+        "Default JSONL uses the same message fields as `read` (including "
+        "media_type and media_filename) and adds boolean flags such as target "
+        "and replied_to on relevant lines."
     )
 )
 def context(
@@ -399,7 +447,7 @@ def context(
     ] = False,
 ) -> None:
     """View a message with surrounding context."""
-    from tgcli.client import create_client, get_context
+    from tgcli.client import ChatResolutionError, create_client, get_context
 
     async def _run():
         client = create_client()
@@ -415,6 +463,9 @@ def context(
     except UnauthorizedError:
         stderr.print("[red]Not authenticated.[/red] Run `tg auth login` first.")
         raise typer.Exit(2)
+    except ChatResolutionError as e:
+        _report_chat_resolution_error(e)
+        raise typer.Exit(1)
     except Exception as e:
         stderr.print(f"[red]Context fetch failed:[/red] {e}")
         raise typer.Exit(1)
@@ -439,3 +490,70 @@ def context(
                     replied_to=(msg.id == replied_to_id),
                 )
             )
+
+
+@app.command(
+    help=(
+        "Download the attachment of one message.\n\n"
+        "Chat names use exact matching first, then a unique case-insensitive "
+        "substring. Pass an id from `tg chats` to skip name matching. "
+        "For negative IDs, put options before -- and the ID after it.\n\n"
+        "Prints a single JSON line with id, path, and media_type. Fails when "
+        "the message has no downloadable media (webpage previews count as "
+        "no media) or the id is not found. Executables, scripts, installers, "
+        "and files whose content is an executable in disguise are refused. "
+        "Archives (zip, 7z, tar, ...) are refused unless --allow-archives is set. "
+        "The file is saved under a name tgcli picks (<message_id>_<original name>, "
+        "or <media_type>_<message_id>.<ext>), never overwriting an existing file."
+    )
+)
+def media(
+    chat: str,
+    message_id: int,
+    out: Annotated[
+        str,
+        typer.Option("--out", help="Directory to save into (default: cwd)."),
+    ] = ".",
+    allow_archives: Annotated[
+        bool,
+        typer.Option("--allow-archives", help="Also download zip/7z/tar archives."),
+    ] = False,
+    max_size: Annotated[
+        int,
+        typer.Option("--max-size", help="Refuse attachments larger than this many MB."),
+    ] = 100,
+) -> None:
+    """Download the attachment of one message."""
+    from tgcli.client import ChatResolutionError, create_client, download_media
+
+    os.makedirs(out, exist_ok=True)
+
+    async def _run():
+        client = create_client()
+        async with client:
+            return await download_media(
+                client,
+                chat,
+                message_id,
+                out,
+                allow_archives=allow_archives,
+                max_bytes=max_size * 1024 * 1024,
+            )
+
+    try:
+        path, media_type = asyncio.run(_run())
+    except SystemExit as e:
+        stderr.print(f"[red]Configuration error:[/red] {e}")
+        stderr.print("Run `tg auth` to set up.")
+        raise typer.Exit(1)
+    except UnauthorizedError:
+        stderr.print("[red]Not authenticated.[/red] Run `tg auth login` first.")
+        raise typer.Exit(2)
+    except ChatResolutionError as e:
+        _report_chat_resolution_error(e)
+        raise typer.Exit(1)
+    except Exception as e:
+        stderr.print(f"[red]Download failed:[/red] {e}")
+        raise typer.Exit(1)
+
+    print(json.dumps({"id": message_id, "path": path, "media_type": media_type}))