pytgcli 0.11.0__tar.gz → 0.12.0__tar.gz

pytgcli-0.12.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @tksohishi

pytgcli-0.12.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,86 @@
+name: Bug report
+description: Something in tgcli doesn't work as expected
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting! If tgcli is useful to you, a ⭐ on the repo helps other people find it.
+
+        tgcli doesn't accept pull requests. A precise report is the fastest way to a fix.
+  - type: textarea
+    id: problem
+    attributes:
+      label: What happened
+      description: What you ran, what you expected, and what happened instead.
+      placeholder: |
+        I ran `tg auth login`, entered my phone number, and the verification code never arrived.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: The exact commands, in order. Replace chat names and IDs with placeholders if they are private.
+      render: shell
+    validations:
+      required: true
+  - type: textarea
+    id: output
+    attributes:
+      label: Output
+      description: The full output, including errors on stderr. Leave out QR codes (as text or screenshots) and tg://login URLs, and remove phone numbers, session strings, API hashes, verification codes, passwords and message contents.
+      render: text
+  - type: dropdown
+    id: impact
+    attributes:
+      label: Impact
+      options:
+        - Blocks me completely (can't log in or use tgcli at all)
+        - One command or feature is broken, others work
+        - Wrong or confusing output, with a workaround
+        - Minor annoyance
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: tgcli version
+      description: Output of `tg --version`
+    validations:
+      required: true
+  - type: dropdown
+    id: install
+    attributes:
+      label: Install method
+      options:
+        - uv tool install
+        - Homebrew
+        - pip / pipx
+        - From source
+    validations:
+      required: true
+  - type: input
+    id: os
+    attributes:
+      label: OS and Python version
+      placeholder: macOS 26.1, Python 3.13
+    validations:
+      required: true
+  - type: dropdown
+    id: host
+    attributes:
+      label: Where tgcli runs
+      description: Telegram treats datacenter IPs differently from home connections.
+      options:
+        - Personal computer on a home or office network
+        - VPS or cloud server
+        - CI or container
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: context
+    attributes:
+      label: Anything else
+      description: Session store (file or keychain), whether 2FA is on, proxies or VPNs, and anything you already tried.

pytgcli-0.12.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

pytgcli-0.12.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,35 @@
+name: Feature request
+description: Suggest something tgcli should do
+labels: [enhancement]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the idea! If tgcli is useful to you, a ⭐ on the repo helps other people find it.
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What you are trying to do and why tgcli can't do it today. Describe the need, not only the solution.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed behavior
+      description: The command, flag, or output you have in mind, if any.
+  - type: dropdown
+    id: importance
+    attributes:
+      label: How much it matters
+      options:
+        - I can't use tgcli for my use case without it
+        - It would save me real time
+        - Nice to have
+    validations:
+      required: true
+  - type: textarea
+    id: context
+    attributes:
+      label: Context
+      description: How you use tgcli (by hand, from an AI agent, in scripts), and any workaround you use now.

{pytgcli-0.11.0 → pytgcli-0.12.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@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
       - run: uv sync --group dev
       - run: uv run ruff check
       - run: uv run ruff format --check
@@ -19,10 +19,11 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.12", "3.13"]
+        python-version: ["3.12", "3.14"]
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
-      - run: uv python install ${{ matrix.python-version }}
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          python-version: ${{ matrix.python-version }}
       - run: uv sync --group dev
       - run: uv run pytest

{pytgcli-0.11.0 → pytgcli-0.12.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@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
       - run: uv build
       - uses: actions/upload-artifact@v7
         with:
@@ -76,7 +76,7 @@ jobs:
         with:
           name: dist
           path: dist
-      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
       - run: uv publish --trusted-publishing always dist/*
 
   update-homebrew-tap:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pytgcli
-Version: 0.11.0
+Version: 0.12.0
 Summary: CLI tool to read Telegram messages from the terminal
 Project-URL: Repository, https://github.com/tksohishi/tgcli
 Author: Takeshi
@@ -17,6 +17,7 @@ Classifier: Topic :: Communications :: Chat
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Requires-Dist: keyring>=25
+Requires-Dist: qrcode>=8
 Requires-Dist: rich>=13
 Requires-Dist: telethon>=1.42
 Requires-Dist: typer>=0.15
@@ -32,6 +33,7 @@ Give AI agents (Claude Code, Codex, Cursor, etc.) direct access to your Telegram
 - **Minimal surface** — a handful of commands; easy for agents to discover and invoke
 - **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
+- **QR login**: authorize by scanning a code from a device that is already logged in, for when Telegram never delivers a verification code
 - **Agent-friendly session storage** — Telethon session key stored in a local `0600` file by default; keychain remains available as a legacy option
 
 ## Installation
@@ -74,7 +76,7 @@ Create a Telegram API app at [my.telegram.org/apps](https://my.telegram.org/apps
 tg auth
 ```
 
-This walks you through setup: saves your API credentials to `~/.config/tgcli/config.toml`, then logs in with phone number + verification code. The Telegram session is stored at `~/.config/tgcli/session` by default.
+This walks you through setup: saves your API credentials to `~/.config/tgcli/config.toml`, then logs you in by QR code (scanned from a device where you are already logged in) or by phone number + verification code. If the verification code never arrives, which Telegram does for some IP ranges such as VPS hosts, use the QR method. The Telegram session is stored at `~/.config/tgcli/session` by default.
 
 ### 3. Read Messages
 
@@ -132,11 +134,20 @@ Smart entrypoint: creates config if missing, logs in if needed, shows status if
 
 Explicit subcommands:
 
+- `tg auth qr` - log in by scanning a QR code in Telegram > Settings > Devices > Link Desktop Device
 - `tg auth login` - interactive login (phone + code/2FA)
 - `tg auth logout` - remove the local session
 - `tg auth migrate-session` - copy a legacy keychain session to the local session file
 - `tg auth status` - show auth state
 
+#### `tg auth qr`
+
+Prints a QR code to stderr, plus a `tg://login` URL you can open instead if Telegram Desktop runs on the same machine. The code refreshes whenever it expires, until it is scanned or `--timeout` runs out. Accounts with Two-Step Verification are asked for that password after the scan, with up to 3 tries.
+
+| Flag        | Description                                               |
+|-------------|-----------------------------------------------------------|
+| `--timeout` | Seconds to wait for a scan before giving up (default 300) |
+
 ### `tg chats`
 
 List your Telegram chats. Returns JSONL by default.
@@ -178,14 +189,17 @@ When no substring matches, similar spellings are offered as suggestions without
 
 | Flag           | Description                            |
 |----------------|----------------------------------------|
-| `--query`/`-q` | Filter messages by text                |
+| `--query`/`-q` | Filter messages by text (client-side)  |
 | `--from`       | Filter by sender                       |
 | `--limit`      | Max messages (default 50)              |
+| `--scan`       | Max messages walked when filtering (default 2000) |
 | `--head`       | Oldest messages first                  |
 | `--after`      | Only messages after date (YYYY-MM-DD)  |
 | `--before`     | Only messages before date (YYYY-MM-DD) |
 | `--pretty`     | Rich table output instead of JSONL     |
 
+`--query` and `--from` filter client-side while walking back through the chat. The walk stops after `--scan` messages unless `--after` bounds it by date; when the cap is hit, matches found so far are printed and a `scan cap reached: ...` line goes to stderr (exit code 0). Narrow with `--after` or raise `--scan`.
+
 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>`

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

@@ -8,6 +8,7 @@ Give AI agents (Claude Code, Codex, Cursor, etc.) direct access to your Telegram
 - **Minimal surface** — a handful of commands; easy for agents to discover and invoke
 - **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
+- **QR login**: authorize by scanning a code from a device that is already logged in, for when Telegram never delivers a verification code
 - **Agent-friendly session storage** — Telethon session key stored in a local `0600` file by default; keychain remains available as a legacy option
 
 ## Installation
@@ -50,7 +51,7 @@ Create a Telegram API app at [my.telegram.org/apps](https://my.telegram.org/apps
 tg auth
 ```
 
-This walks you through setup: saves your API credentials to `~/.config/tgcli/config.toml`, then logs in with phone number + verification code. The Telegram session is stored at `~/.config/tgcli/session` by default.
+This walks you through setup: saves your API credentials to `~/.config/tgcli/config.toml`, then logs you in by QR code (scanned from a device where you are already logged in) or by phone number + verification code. If the verification code never arrives, which Telegram does for some IP ranges such as VPS hosts, use the QR method. The Telegram session is stored at `~/.config/tgcli/session` by default.
 
 ### 3. Read Messages
 
@@ -108,11 +109,20 @@ Smart entrypoint: creates config if missing, logs in if needed, shows status if
 
 Explicit subcommands:
 
+- `tg auth qr` - log in by scanning a QR code in Telegram > Settings > Devices > Link Desktop Device
 - `tg auth login` - interactive login (phone + code/2FA)
 - `tg auth logout` - remove the local session
 - `tg auth migrate-session` - copy a legacy keychain session to the local session file
 - `tg auth status` - show auth state
 
+#### `tg auth qr`
+
+Prints a QR code to stderr, plus a `tg://login` URL you can open instead if Telegram Desktop runs on the same machine. The code refreshes whenever it expires, until it is scanned or `--timeout` runs out. Accounts with Two-Step Verification are asked for that password after the scan, with up to 3 tries.
+
+| Flag        | Description                                               |
+|-------------|-----------------------------------------------------------|
+| `--timeout` | Seconds to wait for a scan before giving up (default 300) |
+
 ### `tg chats`
 
 List your Telegram chats. Returns JSONL by default.
@@ -154,14 +164,17 @@ When no substring matches, similar spellings are offered as suggestions without
 
 | Flag           | Description                            |
 |----------------|----------------------------------------|
-| `--query`/`-q` | Filter messages by text                |
+| `--query`/`-q` | Filter messages by text (client-side)  |
 | `--from`       | Filter by sender                       |
 | `--limit`      | Max messages (default 50)              |
+| `--scan`       | Max messages walked when filtering (default 2000) |
 | `--head`       | Oldest messages first                  |
 | `--after`      | Only messages after date (YYYY-MM-DD)  |
 | `--before`     | Only messages before date (YYYY-MM-DD) |
 | `--pretty`     | Rich table output instead of JSONL     |
 
+`--query` and `--from` filter client-side while walking back through the chat. The walk stops after `--scan` messages unless `--after` bounds it by date; when the cap is hit, matches found so far are printed and a `scan cap reached: ...` line goes to stderr (exit code 0). Narrow with `--after` or raise `--scan`.
+
 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>`

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pytgcli"
-version = "0.11.0"
+version = "0.12.0"
 description = "CLI tool to read Telegram messages from the terminal"
 readme = "README.md"
 license = "MIT"
@@ -26,6 +26,7 @@ dependencies = [
     "telethon>=1.42",
     "keyring>=25",
     "rich>=13",
+    "qrcode>=8",
 ]
 
 [project.urls]

{pytgcli-0.11.0 → pytgcli-0.12.0}/src/tgcli/auth.py

@@ -1,6 +1,13 @@
 from __future__ import annotations
 
+import time
+from collections.abc import Callable
+from datetime import UTC, datetime
+
+from telethon.errors import PasswordHashInvalidError, SessionPasswordNeededError
 from telethon.sessions import StringSession
+from telethon.tl.functions.account import GetPasswordRequest
+from telethon.tl.types.auth import LoginTokenMigrateTo, LoginTokenSuccess
 
 from tgcli.client import create_client
 from tgcli.config import load_session_store
@@ -18,6 +25,63 @@ async def login() -> None:
         await client.disconnect()
 
 
+async def login_qr(
+    on_url: Callable[[str], None],
+    password: Callable[[str | None], str],
+    timeout: float = 300.0,
+) -> None:
+    """QR login approved from an already authorized device. Saves the local session.
+
+    on_url is called with each tg://login URL, again whenever the token rotates.
+    password is called with the account's password hint, if it has one.
+    """
+    client = create_client()
+    try:
+        await client.connect()
+        if not await client.is_user_authorized():
+            await _wait_for_qr_scan(client, on_url, password, timeout)
+        save_session(StringSession.save(client.session))
+    finally:
+        await client.disconnect()
+
+
+async def _wait_for_qr_scan(client, on_url, password, timeout: float) -> None:
+    qr = await client.qr_login()
+    deadline = time.monotonic() + timeout
+    try:
+        while True:
+            on_url(qr.url)
+            ttl = (qr.expires - datetime.now(UTC)).total_seconds()
+            remaining = deadline - time.monotonic()
+            try:
+                # recreate() returns the same token until it expires: wait out the TTL.
+                await qr.wait(timeout=max(1.0, min(ttl, remaining)))
+                return
+            except TimeoutError:
+                if time.monotonic() >= deadline:
+                    raise TimeoutError(
+                        f"No device scanned the QR code within {timeout:.0f}s."
+                    ) from None
+            await qr.recreate()
+            # A scan that lands after wait() gave up is answered by recreate() instead.
+            # QRLogin exposes that answer only as _resp.
+            if isinstance(qr._resp, LoginTokenSuccess):
+                return
+            if isinstance(qr._resp, LoginTokenMigrateTo):
+                raise RuntimeError(
+                    "The code was scanned while it refreshed. Run `tg auth qr` again."
+                )
+    except SessionPasswordNeededError:
+        hint = (await client(GetPasswordRequest())).hint
+        for attempts_left in reversed(range(3)):
+            try:
+                await client.sign_in(password=password(hint))
+                return
+            except PasswordHashInvalidError:
+                if not attempts_left:
+                    raise
+
+
 async def logout() -> None:
     """Log out and remove the local session.
 

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

@@ -4,12 +4,14 @@ import asyncio
 import json
 import os
 import subprocess
+import sys
 from datetime import UTC, datetime
 from importlib.metadata import version
 from typing import Annotated
 
 import typer
 from rich.console import Console
+from rich.markup import escape
 from telethon.errors import UnauthorizedError
 
 
@@ -34,7 +36,11 @@ app = typer.Typer(
     )
 )
 auth_app = typer.Typer(
-    help="Manage Telegram authentication.", invoke_without_command=True
+    help=(
+        "Manage Telegram authentication.\n\n"
+        "Use `tg auth qr` when the phone verification code never arrives."
+    ),
+    invoke_without_command=True,
 )
 app.add_typer(auth_app, name="auth")
 
@@ -141,8 +147,18 @@ def auth_default(ctx: typer.Context) -> None:
         stdout.print("Run `tg auth logout` to log out.")
         return
 
-    # Step 3: not authenticated, run login
-    _run_login()
+    # Step 3: not authenticated, pick a login method
+    stderr.print("Choose a login method:")
+    stderr.print(r"  \[1] QR code, scanned from a device already logged in")
+    stderr.print(r"  \[2] Phone number + verification code")
+    method = typer.prompt("Method", default="1").strip().lower()
+    if method in {"1", "qr"}:
+        _run_qr_login()
+    elif method in {"2", "phone", "code"}:
+        _run_login()
+    else:
+        stderr.print("[red]Choose 1 or 2.[/red]")
+        raise typer.Exit(1)
 
 
 def _run_login() -> None:
@@ -162,9 +178,59 @@ def _run_login() -> None:
     except Exception as e:
         stderr.print(f"[red]Login failed:[/red] {e}")
         raise typer.Exit(1)
+    _print_login_success()
+
+
+def _run_qr_login(timeout: float = 300.0) -> None:
+    """Shared QR login flow for both `tg auth` and `tg auth qr`."""
+    from getpass import getpass
+
+    from tgcli.auth import login_qr
+    from tgcli.formatting import format_qr
+
+    stderr.print(
+        "\nOn a device where you are logged in, open Telegram > Settings >\n"
+        "Devices > Link Desktop Device and scan the code below. If Telegram\n"
+        "Desktop runs on this machine, you can open the tg://login URL instead.\n"
+    )
+
+    shown = 0
+
+    def show(url: str) -> None:
+        nonlocal shown
+        if shown:
+            stderr.print("[dim]Code expired. Fresh code:[/dim]")
+        shown += 1
+        stderr.print(format_qr(url))
+        stderr.print(f"[dim]{url}[/dim]")
+        stderr.print("[dim]Waiting for a scan. Ctrl-C aborts.[/dim]")
+
+    asked = 0
+
+    def password(hint: str | None) -> str:
+        nonlocal asked
+        if asked:
+            stderr.print(f"[red]Wrong password.[/red] {3 - asked} attempt(s) left.")
+        elif hint:
+            stderr.print(f"Password hint: {escape(hint)}")
+        asked += 1
+        return getpass("Two-Step Verification password: ")
+
+    try:
+        asyncio.run(login_qr(show, password, timeout=timeout))
+    except KeyboardInterrupt:
+        stderr.print("\nAborted.")
+        raise typer.Exit(1)
+    except Exception as e:
+        stderr.print(f"[red]Login failed:[/red] {e}")
+        raise typer.Exit(1)
+    _print_login_success()
+
+
+def _print_login_success() -> None:
     stderr.print(
-        "\nRegarding the ToS warning above: unofficial API clients are\n"
-        "under observation by Telegram. Normal interactive use (searching,\n"
+        "\nRemember Telegram's ToS: unofficial API clients are under\n"
+        "observation by Telegram. Normal interactive use (searching,\n"
         "reading your own messages) is fine. Avoid bulk scraping, spamming,\n"
         "or using results for AI/ML model training.\n"
         "Full terms: https://core.telegram.org/api/terms\n"
@@ -178,6 +244,21 @@ def login() -> None:
     _run_login()
 
 
+@auth_app.command("qr")
+def qr(
+    timeout: Annotated[
+        float,
+        typer.Option(min=1, help="Seconds to wait for a scan before giving up."),
+    ] = 300.0,
+) -> None:
+    """Log in by scanning a QR code from a device already logged in.
+
+    Use this when the phone verification code never arrives, which Telegram
+    does for some IP ranges such as VPS hosts.
+    """
+    _run_qr_login(timeout)
+
+
 @auth_app.command()
 def logout() -> None:
     """Remove the local session."""
@@ -334,6 +415,11 @@ def chats(
         "--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"
+        "--query and --from filter client-side while walking back through the "
+        "chat, so a term with few or no matches would otherwise scan the whole "
+        "history. The walk stops after --scan messages (default 2000) unless "
+        "--after bounds it by date. When the cap is hit, matches found so far are "
+        "printed and a `scan cap reached` line goes to stderr; exit code stays 0.\n\n"
         "Examples: `tg read Team --from takeshi55555`, "
         '`tg read Team --from @takeshi55555`, `tg read Team --from "Takeshi"`.'
     )
@@ -343,7 +429,15 @@ def read(
         str, typer.Argument(help="Chat name, id, @username, phone, or me.")
     ],
     query: Annotated[
-        str | None, typer.Option("--query", "-q", help="Filter messages by text.")
+        str | None,
+        typer.Option(
+            "--query",
+            "-q",
+            help=(
+                "Filter messages by text (client-side substring match, "
+                "case-insensitive). Bounded by --scan or --after."
+            ),
+        ),
     ] = None,
     from_: Annotated[
         str | None,
@@ -356,6 +450,17 @@ def read(
         ),
     ] = None,
     limit: Annotated[int, typer.Option(help="Max messages to return.")] = 50,
+    scan: Annotated[
+        int,
+        typer.Option(
+            "--scan",
+            min=1,
+            help=(
+                "Max messages to walk when --query or --from is set and --after "
+                "is not. Matches found before the cap are still printed."
+            ),
+        ),
+    ] = 2000,
     head: Annotated[
         bool, typer.Option("--head", help="Oldest messages first.")
     ] = False,
@@ -380,6 +485,12 @@ def read(
         stderr.print("Expected format: YYYY-MM-DD")
         raise typer.Exit(1)
 
+    scan_cap: tuple[int, datetime | None] | None = None
+
+    def _on_scan_cap(scanned: int, last_date: datetime | None) -> None:
+        nonlocal scan_cap
+        scan_cap = (scanned, last_date)
+
     async def _run():
         client = create_client()
         async with client:
@@ -392,6 +503,8 @@ def read(
                 after=after_dt,
                 before=before_dt,
                 reverse=head,
+                scan=scan,
+                on_scan_cap=_on_scan_cap,
             )
 
     try:
@@ -412,9 +525,7 @@ def read(
 
     if not results:
         stdout.print("No messages found.")
-        return
-
-    if pretty:
+    elif pretty:
         from tgcli.formatting import format_search_results
 
         stdout.print(format_search_results(results))
@@ -424,6 +535,15 @@ def read(
         for msg in results:
             print(format_message_jsonl(msg))
 
+    if scan_cap:
+        scanned, last_date = scan_cap
+        back_to = last_date.astimezone().strftime("%Y-%m-%d") if last_date else "?"
+        print(
+            f"scan cap reached: {scanned} messages read back to {back_to}; "
+            "narrow with --after or raise --scan",
+            file=sys.stderr,
+        )
+
 
 @app.command(
     help=(