pytgcli 0.8.3__tar.gz → 0.9.0__tar.gz

{pytgcli-0.8.3 → pytgcli-0.9.0}/.github/workflows/ci.yml

@@ -10,7 +10,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.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.13"]
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
       - run: uv python install ${{ matrix.python-version }}
       - run: uv sync --group dev
       - run: uv run pytest

{pytgcli-0.8.3 → pytgcli-0.9.0}/.github/workflows/publish.yml

@@ -33,9 +33,9 @@ jobs:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           ref: ${{ github.ref_name }}
-      - uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
       - run: uv build
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: dist
           path: dist/*
@@ -46,7 +46,7 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist
@@ -72,11 +72,11 @@ jobs:
       id-token: write
       contents: read
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist
-      - uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
       - run: uv publish --trusted-publishing always dist/*
 
   update-homebrew-tap:

{pytgcli-0.8.3 → pytgcli-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytgcli
-Version: 0.8.3
+Version: 0.9.0
 Summary: CLI tool to read Telegram messages from the terminal
 Project-URL: Repository, https://github.com/tksohishi/tgcli
 Author: Takeshi
@@ -31,7 +31,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
 - **Fuzzy resolution** — chat and user names match by display name (no numeric IDs required)
 - **`--pretty` for humans** — Rich tables when you want to read output yourself
-- **Secure session storage** — Telethon session key stored in system keychain via `keyring`
+- **Agent-friendly session storage** — Telethon session key stored in a local `0600` file by default; keychain remains available as a legacy option
 
 ## Installation
 
@@ -73,7 +73,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.
+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.
 
 ### 3. Read Messages
 
@@ -123,7 +123,8 @@ Smart entrypoint: creates config if missing, logs in if needed, shows status if
 Explicit subcommands:
 
 - `tg auth login` - interactive login (phone + code/2FA)
-- `tg auth logout` - remove session from system keychain
+- `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 chats`
@@ -172,9 +173,20 @@ Config lives at `~/.config/tgcli/config.toml`:
 ```toml
 api_id = 123456
 api_hash = "your_api_hash"
+session_store = "file"
 ```
 
-Alternatively, set `TELEGRAM_API_ID` and `TELEGRAM_API_HASH` environment variables.
+`session_store` can be `file` or `keychain`. `file` is the default and stores the Telegram session at `~/.config/tgcli/session` with mode `0600`. `keychain` keeps the legacy system keychain behavior; it may trigger OS password prompts and will be removed in a future major release.
+
+To migrate an existing keychain session to the file backend:
+
+```bash
+tg auth migrate-session
+```
+
+Add `--delete-keychain` to remove the keychain entry after a successful migration.
+
+Alternatively, set `TELEGRAM_API_ID`, `TELEGRAM_API_HASH`, and optionally `TGCLI_SESSION_STORE` environment variables.
 
 ## Contributing
 

{pytgcli-0.8.3 → pytgcli-0.9.0}/README.md

@@ -8,7 +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
 - **Fuzzy resolution** — chat and user names match by display name (no numeric IDs required)
 - **`--pretty` for humans** — Rich tables when you want to read output yourself
-- **Secure session storage** — Telethon session key stored in system keychain via `keyring`
+- **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 +50,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.
+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.
 
 ### 3. Read Messages
 
@@ -100,7 +100,8 @@ Smart entrypoint: creates config if missing, logs in if needed, shows status if
 Explicit subcommands:
 
 - `tg auth login` - interactive login (phone + code/2FA)
-- `tg auth logout` - remove session from system keychain
+- `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 chats`
@@ -149,9 +150,20 @@ Config lives at `~/.config/tgcli/config.toml`:
 ```toml
 api_id = 123456
 api_hash = "your_api_hash"
+session_store = "file"
 ```
 
-Alternatively, set `TELEGRAM_API_ID` and `TELEGRAM_API_HASH` environment variables.
+`session_store` can be `file` or `keychain`. `file` is the default and stores the Telegram session at `~/.config/tgcli/session` with mode `0600`. `keychain` keeps the legacy system keychain behavior; it may trigger OS password prompts and will be removed in a future major release.
+
+To migrate an existing keychain session to the file backend:
+
+```bash
+tg auth migrate-session
+```
+
+Add `--delete-keychain` to remove the keychain entry after a successful migration.
+
+Alternatively, set `TELEGRAM_API_ID`, `TELEGRAM_API_HASH`, and optionally `TGCLI_SESSION_STORE` environment variables.
 
 ## Contributing
 

{pytgcli-0.8.3 → pytgcli-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pytgcli"
-version = "0.8.3"
+version = "0.9.0"
 description = "CLI tool to read Telegram messages from the terminal"
 readme = "README.md"
 license = "MIT"
@@ -44,6 +44,9 @@ tg = "tgcli.cli:app"
 [tool.hatch.build.targets.wheel]
 packages = ["src/tgcli"]
 
+[tool.uv]
+cache-dir = "tmp/uv-cache"
+
 [tool.ruff]
 target-version = "py312"
 
@@ -55,3 +58,4 @@ select = ["E", "F", "I", "S", "UP"]
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
+testpaths = ["tests"]

{pytgcli-0.8.3 → pytgcli-0.9.0}/src/tgcli/auth.py

@@ -3,11 +3,12 @@ from __future__ import annotations
 from telethon.sessions import StringSession
 
 from tgcli.client import create_client
-from tgcli.session import delete_session, load_session, save_session
+from tgcli.config import load_session_store
+from tgcli.session import delete_session, load_session, save_session, session_path
 
 
 async def login() -> None:
-    """Interactive login: phone + code/2FA. Saves session to system keychain."""
+    """Interactive login: phone + code/2FA. Saves the local session."""
     client = create_client()
     try:
         await client.start(phone=lambda: input("Phone number: "))
@@ -18,7 +19,7 @@ async def login() -> None:
 
 
 async def logout() -> None:
-    """Log out and remove session from system keychain.
+    """Log out and remove the local session.
 
     Always deletes the local session, even if the remote logout fails.
     """
@@ -35,18 +36,43 @@ async def logout() -> None:
     delete_session()
 
 
+def migrate_session(*, delete_keychain: bool = False) -> dict[str, object]:
+    """Copy the legacy keychain session to the file backend."""
+    legacy_session = load_session(store="keychain")
+    if not legacy_session:
+        return {
+            "migrated": False,
+            "deleted_keychain": False,
+            "path": session_path(),
+        }
+
+    save_session(legacy_session, store="file")
+    deleted_keychain = False
+    if delete_keychain:
+        delete_session(store="keychain")
+        deleted_keychain = True
+
+    return {
+        "migrated": True,
+        "deleted_keychain": deleted_keychain,
+        "path": session_path(),
+    }
+
+
 async def get_status() -> dict:
     """Return auth status info.
 
     Returns dict with keys: authenticated, phone, session_exists.
     """
-    session_exists = load_session() is not None
+    session_store = load_session_store()
+    session_exists = load_session(store=session_store) is not None
 
     if not session_exists:
         return {
             "authenticated": False,
             "phone": None,
             "session_exists": False,
+            "session_store": session_store,
         }
 
     client = create_client()
@@ -70,4 +96,5 @@ async def get_status() -> dict:
         "authenticated": authorized,
         "phone": phone,
         "session_exists": session_exists,
+        "session_store": session_store,
     }

{pytgcli-0.8.3 → pytgcli-0.9.0}/src/tgcli/cli.py

@@ -18,7 +18,18 @@ def _version_callback(value: bool) -> None:
         raise typer.Exit()
 
 
-app = typer.Typer(help="Read Telegram messages from the terminal.")
+app = typer.Typer(
+    help=(
+        "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 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."
+    )
+)
 auth_app = typer.Typer(
     help="Manage Telegram authentication.", invoke_without_command=True
 )
@@ -166,7 +177,7 @@ def login() -> None:
 
 @auth_app.command()
 def logout() -> None:
-    """Remove session from system keychain."""
+    """Remove the local session."""
     from tgcli.auth import logout as _logout
 
     try:
@@ -177,6 +188,34 @@ def logout() -> None:
         raise typer.Exit(1)
 
 
+@auth_app.command("migrate-session")
+def migrate_session(
+    delete_keychain: Annotated[
+        bool,
+        typer.Option(
+            "--delete-keychain",
+            help="Delete the legacy keychain session after a successful migration.",
+        ),
+    ] = False,
+) -> None:
+    """Copy the legacy keychain session to the local session file."""
+    from tgcli.auth import migrate_session as _migrate_session
+
+    try:
+        result = _migrate_session(delete_keychain=delete_keychain)
+    except Exception as e:
+        stderr.print(f"[red]Migration failed:[/red] {e}")
+        raise typer.Exit(1)
+
+    if not result["migrated"]:
+        stderr.print("No keychain session found.")
+        raise typer.Exit(1)
+
+    stdout.print(f"Session migrated to {result['path']}.")
+    if result["deleted_keychain"]:
+        stdout.print("Deleted legacy keychain session.")
+
+
 @auth_app.command()
 def status() -> None:
     """Show current auth state."""
@@ -246,14 +285,34 @@ def chats(
             print(format_chat_jsonl(chat))
 
 
-@app.command()
+@app.command(
+    help=(
+        "Read recent messages from a chat. Newest first by default (--head for "
+        "oldest).\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"
+        "--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"
+        "Examples: `tg read Team --from takeshi55555`, "
+        '`tg read Team --from @takeshi55555`, `tg read Team --from "Takeshi"`.'
+    )
+)
 def read(
     chat: Annotated[str, typer.Argument(help="Chat or person to read messages from.")],
     query: Annotated[
         str | None, typer.Option("--query", "-q", help="Filter messages by text.")
     ] = None,
     from_: Annotated[
-        str | None, typer.Option("--from", help="Filter by sender.")
+        str | None,
+        typer.Option(
+            "--from",
+            help=(
+                "Filter by sender: me, @username, bare username, numeric user ID, "
+                "phone, or exact display name."
+            ),
+        ),
     ] = None,
     limit: Annotated[int, typer.Option(help="Max messages to return.")] = 50,
     head: Annotated[
@@ -269,7 +328,7 @@ def read(
         bool, typer.Option("--pretty", help="Rich table output instead of JSONL.")
     ] = False,
 ) -> None:
-    """Read recent messages from a chat. Newest first by default (--head for oldest)."""
+    """Read recent messages from a chat."""
     from tgcli.client import create_client, read_messages
 
     try:
@@ -322,7 +381,13 @@ def read(
             print(format_message_jsonl(msg))
 
 
-@app.command()
+@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."
+    )
+)
 def context(
     chat: str,
     message_id: int,

{pytgcli-0.8.3 → pytgcli-0.9.0}/src/tgcli/client.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import re
 from datetime import datetime
 
 from telethon import TelegramClient
@@ -9,11 +10,13 @@ from tgcli.config import TelegramConfig, load_config
 from tgcli.formatting import ChatData, MessageData
 from tgcli.session import load_session
 
+_USERNAME_RE = re.compile(r"^[A-Za-z][A-Za-z0-9_]{4,31}$")
+
 
 def create_client(config: TelegramConfig | None = None) -> TelegramClient:
     """Create a TelegramClient using stored session and config."""
     config = config or load_config()
-    session_str = load_session() or ""
+    session_str = load_session(store=config.session_store) or ""
     return TelegramClient(
         StringSession(session_str),
         config.api_id,
@@ -31,6 +34,27 @@ def _get_name(entity) -> str:
     return " ".join(p for p in parts if p) or "Unknown"
 
 
+def _get_username(entity) -> str | None:
+    if entity is None:
+        return None
+    return getattr(entity, "username", None)
+
+
+def _get_sender_id(msg, sender) -> int | None:
+    sender_id = getattr(msg, "sender_id", None)
+    if sender_id is not None:
+        return sender_id
+    if sender is None:
+        return None
+    return getattr(sender, "id", None)
+
+
+def _is_entity_reference(value: str) -> bool:
+    if value.startswith("@") or value.startswith("+") or value.lstrip("-").isdigit():
+        return True
+    return bool(_USERNAME_RE.fullmatch(value))
+
+
 async def _resolve_entity(client: TelegramClient, name: str):
     """Resolve a name to a Telethon entity.
 
@@ -56,13 +80,51 @@ async def _resolve_entity(client: TelegramClient, name: str):
     )
 
 
-def _msg_to_data(msg, chat_name: str, sender_name: str) -> MessageData:
+async def _resolve_sender(client: TelegramClient, chat_entity, value: str):
+    """Resolve a sender filter within a chat."""
+    if value.lower() == "me":
+        return await client.get_me()
+
+    sender_ref = value.strip()
+    if _is_entity_reference(sender_ref):
+        try:
+            return await client.get_entity(sender_ref)
+        except Exception:  # noqa: S110
+            pass
+
+    participant_search = sender_ref[1:] if sender_ref.startswith("@") else sender_ref
+    username_query = participant_search.lower()
+    display_matches = []
+    async for participant in client.iter_participants(
+        chat_entity, search=participant_search
+    ):
+        username = _get_username(participant)
+        if username and username.lower() == username_query:
+            return participant
+        if _get_name(participant).lower() == sender_ref.lower():
+            display_matches.append(participant)
+
+    if len(display_matches) == 1:
+        return display_matches[0]
+    if len(display_matches) > 1:
+        raise ValueError(
+            f'Found multiple senders named "{value}". Use a username or numeric ID.'
+        )
+    raise ValueError(
+        f'Cannot find sender "{value}" in this chat. Use username, numeric ID, '
+        "or exact display name."
+    )
+
+
+def _msg_to_data(msg, chat_name: str, sender) -> MessageData:
     return MessageData(
         id=msg.id,
         text=msg.text or "",
         chat_name=chat_name,
-        sender_name=sender_name,
+        sender_name=_get_name(sender),
         date=msg.date,
+        sender_username=_get_username(sender),
+        sender_id=_get_sender_id(msg, sender),
         reply_to_msg_id=msg.reply_to.reply_to_msg_id if msg.reply_to else None,
     )
 
@@ -128,7 +190,7 @@ async def read_messages(
 
     from_user = None
     if from_:
-        from_user = await _resolve_entity(client, from_)
+        from_user = await _resolve_sender(client, entity, from_)
 
     filtering = bool(query or from_user)
     filter_query = query.lower() if query else None
@@ -156,7 +218,7 @@ async def read_messages(
             continue
 
         sender = await msg.get_sender()
-        results.append(_msg_to_data(msg, chat_name, _get_name(sender)))
+        results.append(_msg_to_data(msg, chat_name, sender))
         if len(results) >= limit:
             break
 
@@ -205,7 +267,7 @@ async def get_context(
     messages: list[MessageData] = []
     for msg in messages_raw:
         sender = await msg.get_sender()
-        messages.append(_msg_to_data(msg, chat_name, _get_name(sender)))
+        messages.append(_msg_to_data(msg, chat_name, sender))
 
     # Find the replied-to message if applicable
     replied_to = None
@@ -215,6 +277,6 @@ async def get_context(
         reply_msg = await client.get_messages(entity, ids=reply_id)
         if reply_msg:
             sender = await reply_msg.get_sender()
-            replied_to = _msg_to_data(reply_msg, chat_name, _get_name(sender))
+            replied_to = _msg_to_data(reply_msg, chat_name, sender)
 
     return messages, message_id, replied_to

{pytgcli-0.8.3 → pytgcli-0.9.0}/src/tgcli/config.py

@@ -4,14 +4,38 @@ import os
 import tomllib
 from dataclasses import dataclass
 from pathlib import Path
+from typing import Literal, cast
 
-CONFIG_PATH = Path.home() / ".config" / "tgcli" / "config.toml"
+CONFIG_DIR = Path.home() / ".config" / "tgcli"
+CONFIG_PATH = CONFIG_DIR / "config.toml"
+SessionStore = Literal["file", "keychain"]
 
 
 @dataclass(frozen=True)
 class TelegramConfig:
     api_id: int
     api_hash: str
+    session_store: SessionStore = "file"
+
+
+def _parse_session_store(value: object) -> SessionStore:
+    store = str(value or "file").lower()
+    if store not in {"file", "keychain"}:
+        raise ValueError('session_store must be "file" or "keychain"')
+    return cast(SessionStore, store)
+
+
+def load_session_store(config_path: Path | None = None) -> SessionStore:
+    """Load the configured session backend without requiring API credentials."""
+    path = config_path or CONFIG_PATH
+    raw_store: object = None
+
+    if path.exists():
+        with open(path, "rb") as f:
+            data = tomllib.load(f)
+        raw_store = data.get("session_store")
+
+    return _parse_session_store(os.environ.get("TGCLI_SESSION_STORE", raw_store))
 
 
 def load_config(config_path: Path | None = None) -> TelegramConfig:
@@ -25,6 +49,7 @@ def load_config(config_path: Path | None = None) -> TelegramConfig:
     path = config_path or CONFIG_PATH
     api_id: str | None = None
     api_hash: str | None = None
+    session_store: SessionStore = "file"
 
     if path.exists():
         with open(path, "rb") as f:
@@ -36,6 +61,8 @@ def load_config(config_path: Path | None = None) -> TelegramConfig:
         if raw_hash is not None:
             api_hash = str(raw_hash)
 
+    session_store = load_session_store(path)
+
     if api_id is None:
         api_id = os.environ.get("TELEGRAM_API_ID")
     if api_hash is None:
@@ -48,7 +75,9 @@ def load_config(config_path: Path | None = None) -> TelegramConfig:
             "TELEGRAM_API_ID / TELEGRAM_API_HASH env vars."
         )
 
-    return TelegramConfig(api_id=int(api_id), api_hash=api_hash)
+    return TelegramConfig(
+        api_id=int(api_id), api_hash=api_hash, session_store=session_store
+    )
 
 
 def write_config(api_id: int, api_hash: str, config_path: Path | None = None) -> Path:
@@ -58,5 +87,7 @@ def write_config(api_id: int, api_hash: str, config_path: Path | None = None) ->
     """
     path = config_path or CONFIG_PATH
     path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(f'api_id = {api_id}\napi_hash = "{api_hash}"\n')
+    path.write_text(
+        f'api_id = {api_id}\napi_hash = "{api_hash}"\nsession_store = "file"\n'
+    )
     return path

{pytgcli-0.8.3 → pytgcli-0.9.0}/src/tgcli/formatting.py

@@ -24,6 +24,8 @@ class MessageData:
     chat_name: str
     sender_name: str
     date: datetime
+    sender_username: str | None = None
+    sender_id: int | None = None
     reply_to_msg_id: int | None = None
 
 
@@ -127,6 +129,7 @@ def format_auth_status(
     authenticated: bool,
     phone: str | None = None,
     session_exists: bool = False,
+    session_store: str = "file",
 ) -> Text:
     """Build a Rich Text for auth status display."""
     output = Text()
@@ -144,8 +147,11 @@ def format_auth_status(
 
     output.append("Session: ", style="bold")
     if session_exists:
-        output.append("stored in system keychain\n", style="green")
+        if session_store == "keychain":
+            output.append("stored in keychain\n", style="green")
+        else:
+            output.append("stored locally\n", style="green")
     else:
-        output.append("none\n", style="red")
+        output.append(f"none ({session_store})\n", style="red")
 
     return output