pytgcli 0.8.2__tar.gz → 0.9.0__tar.gz

{pytgcli-0.8.2 → 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.9.0/.github/workflows/publish.yml

@@ -0,0 +1,162 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          ref: ${{ github.ref_name }}
+      - name: Verify tag matches pyproject version
+        run: |
+          TAG_VERSION="${{ github.ref_name }}"
+          TAG_VERSION="${TAG_VERSION#v}"
+          PROJECT_VERSION="$(python3 -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")"
+          if [ "$TAG_VERSION" != "$PROJECT_VERSION" ]; then
+            echo "Tag version ($TAG_VERSION) does not match pyproject version ($PROJECT_VERSION)."
+            exit 1
+          fi
+
+  build:
+    needs: verify
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          ref: ${{ github.ref_name }}
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+      - run: uv build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/*
+
+  github-release:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+      - name: Create GitHub release and upload assets
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if gh release view "${{ github.ref_name }}" --repo "${{ github.repository }}" > /dev/null 2>&1; then
+            echo "Release ${{ github.ref_name }} already exists."
+          else
+            gh release create "${{ github.ref_name }}" \
+              --repo "${{ github.repository }}" \
+              --title "${{ github.ref_name }}" \
+              --notes "Automated release for ${{ github.ref_name }}"
+          fi
+          gh release upload "${{ github.ref_name }}" dist/* --repo "${{ github.repository }}" --clobber
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+      - run: uv publish --trusted-publishing always dist/*
+
+  update-homebrew-tap:
+    needs:
+      - github-release
+      - publish-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      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: Resolve PyPI source artifact
+        env:
+          VERSION: ${{ github.ref_name }}
+        run: |
+          export TAG_VERSION="${VERSION#v}"
+          python3 <<'PY'
+          import json
+          import os
+          import urllib.request
+
+          version = os.environ["TAG_VERSION"]
+          url = f"https://pypi.org/pypi/pytgcli/{version}/json"
+          with urllib.request.urlopen(url) as response:
+            data = json.load(response)
+
+          sdist = next(item for item in data["urls"] if item["packagetype"] == "sdist")
+          with open(os.environ["GITHUB_ENV"], "a", encoding="utf-8") as env_file:
+            env_file.write(f"TGCLI_VERSION={version}\n")
+            env_file.write(f"TGCLI_SDIST_URL={sdist['url']}\n")
+            env_file.write(f"TGCLI_SDIST_SHA256={sdist['digests']['sha256']}\n")
+          PY
+
+      - name: Update formula in tap repo
+        run: |
+          git clone "https://x-access-token:${TAP_TOKEN}@github.com/${TAP_REPO}.git" tap-repo
+          python3 <<'PY'
+          import os
+          import re
+          from pathlib import Path
+
+          formula_path = Path("tap-repo/Formula/tgcli.rb")
+          content = formula_path.read_text(encoding="utf-8")
+          content, url_replacements = re.subn(
+            r'^  url ".*"$',
+            f'  url "{os.environ["TGCLI_SDIST_URL"]}"',
+            content,
+            count=1,
+            flags=re.MULTILINE,
+          )
+          content, sha_replacements = re.subn(
+            r'^  sha256 ".*"$',
+            f'  sha256 "{os.environ["TGCLI_SDIST_SHA256"]}"',
+            content,
+            count=1,
+            flags=re.MULTILINE,
+          )
+          if url_replacements != 1 or sha_replacements != 1:
+            raise RuntimeError("Failed to patch tgcli.rb top-level url/sha256")
+          formula_path.write_text(content, encoding="utf-8")
+          PY
+
+      - name: Commit and push formula update
+        run: |
+          cd tap-repo
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add Formula/tgcli.rb
+          if git diff --cached --quiet; then
+            echo "No formula changes to push."
+            exit 0
+          fi
+          git commit -m "chore: update tgcli formula to v${TGCLI_VERSION}"
+          git push origin main

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytgcli
-Version: 0.8.2
+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.2 → 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.2 → pytgcli-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pytgcli"
-version = "0.8.2"
+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.2 → 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.2 → 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.2 → 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