pytgcli 0.11.1__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.1 → 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
@@ -22,7 +22,7 @@ jobs:
         python-version: ["3.12", "3.14"]
     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
         with:
           python-version: ${{ matrix.python-version }}
       - run: uv sync --group dev

{pytgcli-0.11.1 → 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.1 → pytgcli-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pytgcli
-Version: 0.11.1
+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.

{pytgcli-0.11.1 → 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.

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pytgcli"
-version = "0.11.1"
+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.1 → 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.1 → pytgcli-0.12.0}/src/tgcli/cli.py

@@ -11,6 +11,7 @@ from typing import Annotated
 
 import typer
 from rich.console import Console
+from rich.markup import escape
 from telethon.errors import UnauthorizedError
 
 
@@ -35,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")
 
@@ -142,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:
@@ -163,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(
-        "\nRegarding the ToS warning above: unofficial API clients are\n"
-        "under observation by Telegram. Normal interactive use (searching,\n"
+        "\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(
+        "\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"
@@ -179,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."""

{pytgcli-0.11.1 → pytgcli-0.12.0}/src/tgcli/client.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import json
 import os
+import platform
 import re
 import shutil
 import sys
@@ -9,6 +10,7 @@ import zipfile
 from collections.abc import Callable
 from datetime import datetime
 from difflib import get_close_matches
+from importlib.metadata import version
 
 from telethon import TelegramClient
 from telethon.errors import UsernameInvalidError
@@ -67,6 +69,8 @@ def create_client(config: TelegramConfig | None = None) -> TelegramClient:
         StringSession(session_str),
         config.api_id,
         config.api_hash,
+        device_model=platform.node().removesuffix(".local") or None,
+        app_version=version("pytgcli"),
     )
 
 

{pytgcli-0.11.1 → pytgcli-0.12.0}/src/tgcli/formatting.py

@@ -167,3 +167,29 @@ def format_auth_status(
         output.append(f"none ({session_store})\n", style="red")
 
     return output
+
+
+_HALF_BLOCKS = {
+    (True, True): "█",
+    (True, False): "▀",
+    (False, True): "▄",
+    (False, False): " ",
+}
+
+
+def format_qr(data: str) -> Text:
+    """Render data as a terminal QR code, two module rows per line."""
+    import qrcode
+
+    qr = qrcode.QRCode(border=4, error_correction=qrcode.constants.ERROR_CORRECT_L)
+    qr.add_data(data)
+    qr.make(fit=True)
+    matrix = qr.get_matrix()
+    if len(matrix) % 2:
+        matrix.append([False] * len(matrix[0]))
+    lines = [
+        "".join(_HALF_BLOCKS[(t, b)] for t, b in zip(top, bottom, strict=True))
+        for top, bottom in zip(matrix[::2], matrix[1::2], strict=True)
+    ]
+    # Pinned colors: dark themes would otherwise invert the code, which scanners reject.
+    return Text("\n".join(lines), style="black on white")