pytgcli 0.7.0__tar.gz

pytgcli-0.7.0/.github/dependabot.yml

@@ -0,0 +1,15 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      python-deps:
+        patterns:
+          - "*"
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly

pytgcli-0.7.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0
+      - run: uv sync --group dev
+      - run: uv run ruff check
+      - run: uv run ruff format --check
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0
+      - run: uv python install ${{ matrix.python-version }}
+      - run: uv sync --group dev
+      - run: uv run pytest

pytgcli-0.7.0/.github/workflows/publish.yml

@@ -0,0 +1,17 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0
+      - run: uv build
+      - run: uv publish --trusted-publishing always

pytgcli-0.7.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+.coverage
+htmlcov/
+.env
+.env.*
+!.env.example
+.DS_Store
+tmp/
+.claude/

pytgcli-0.7.0/.pre-commit-config.yaml

@@ -0,0 +1,12 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.2
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/Yelp/detect-secrets
+    rev: v1.5.0
+    hooks:
+      - id: detect-secrets

pytgcli-0.7.0/.python-version

@@ -0,0 +1 @@
+3.12

pytgcli-0.7.0/AGENTS.md

@@ -0,0 +1,37 @@
+# AGENTS.md
+
+## Architecture
+
+```
+src/tgcli/
+  cli.py          # Typer app, thin entrypoints
+  auth.py         # Login/logout/status logic
+  client.py       # Telethon wrapper (search, read, context)
+  config.py       # Config loading (TOML + env vars)
+  formatting.py   # Pure output formatting functions (no I/O)
+  session.py      # Keychain-backed StringSession via keyring
+tests/              # pytest + pytest-asyncio, Telethon fully mocked
+```
+
+Layers: CLI (Typer) -> business logic (auth, client) -> Telethon.
+
+## Constraints
+
+- Keep Telethon isolated from CLI and formatting layers
+- Keep CLI entrypoints thin; push logic into library modules
+- Formatting functions are pure (no I/O)
+- All output to stdout, errors to stderr
+- Exit codes: 0 success, 1 error, 2 auth required
+- Mock Telethon entirely in tests, no real API calls
+
+## Telethon Reference
+
+For Telethon questions (API methods, entity resolution, session handling, etc.), check https://docs.telethon.dev/en/stable/ first.
+
+## Verify
+
+```bash
+uv run ruff check
+uv run ruff format --check
+uv run pytest
+```

pytgcli-0.7.0/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

pytgcli-0.7.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Takeshi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pytgcli-0.7.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: pytgcli
+Version: 0.7.0
+Summary: CLI tool to read Telegram messages from the terminal
+Project-URL: Repository, https://github.com/tksohishi/tgcli
+Author: Takeshi
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,messages,telegram
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: keyring>=25
+Requires-Dist: rich>=13
+Requires-Dist: telethon>=1.42
+Requires-Dist: typer>=0.15
+Description-Content-Type: text/markdown
+
+# tgcli — Telegram for your terminal and your AI agents.
+
+Give AI agents (Claude Code, Codex, Cursor, etc.) direct access to your Telegram conversations. Structured JSONL output, minimal command surface, fuzzy name resolution. Works equally well for humans with `--pretty`.
+
+## Features
+
+- **JSONL by default** — one JSON object per line; agents parse it natively, scripts pipe it freely
+- **Minimal surface** — a handful of commands; easy for agents to discover and invoke
+- **Fuzzy resolution** — chat and user names match by display name (no numeric IDs required)
+- **`--pretty` for humans** — Rich tables when you want to read output yourself
+- **Secure session storage** — Telethon session key stored in macOS Keychain via `keyring`
+
+## Installation
+
+Requires Python 3.12+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv tool install pytgcli
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/tksohishi/tgcli.git
+cd tgcli
+uv tool install .
+```
+
+## Quick Start
+
+### 1. Get API Credentials
+
+Create a Telegram API app at [my.telegram.org/apps](https://my.telegram.org/apps). You'll get an `api_id` and `api_hash`.
+
+### 2. Authenticate
+
+```bash
+tg auth
+```
+
+This walks you through setup: saves your API credentials to `~/.config/tgcli/config.toml`, then logs in with phone number + verification code.
+
+### 3. Read Messages
+
+```bash
+tg read "Alice"
+tg read "Finance Team" --limit 20
+tg read "Finance Team" -q "budget"
+tg read "Finance Team" -q "deadline" --from "Alice" --after 2025-01-01
+```
+
+### 4. View Context
+
+```bash
+tg context "Finance Team" 12345
+```
+
+## Use with AI Agents
+
+Once authenticated, any AI coding agent with shell access can use tgcli directly. A few examples:
+
+**Ask Claude Code to summarize a group chat:**
+
+> "Read the last 30 messages from 'Engineering' and summarize the key decisions."
+
+The agent runs `tg read "Engineering" --limit 30`, parses the JSONL, and responds.
+
+**Find a past conversation:**
+
+> "What did I discuss with Alice last week about the deployment?"
+
+The agent runs `tg read "Alice" -q "deployment" --after 2025-02-14` and surfaces the relevant messages.
+
+**Pipe into scripts:**
+
+```bash
+tg read "Alerts" --limit 100 | jq 'select(.text | test("ERROR"))'
+```
+
+No wrapper libraries or API adapters needed. The structured output and simple command surface mean agents can use tgcli out of the box.
+
+## Commands
+
+### `tg auth`
+
+Smart entrypoint: creates config if missing, logs in if needed, shows status if already authenticated.
+
+Explicit subcommands:
+
+- `tg auth login` - interactive login (phone + code/2FA)
+- `tg auth logout` - remove session from Keychain
+- `tg auth status` - show auth state
+
+### `tg chats`
+
+List your Telegram chats. Returns JSONL by default.
+
+| Flag       | Description                  |
+|------------|------------------------------|
+| `--filter` | Fuzzy filter by chat name    |
+| `--limit`  | Max chats to list (default 100) |
+| `--pretty` | Rich table output instead of JSONL |
+
+### `tg read <chat>`
+
+Read recent messages from a chat. Returns JSONL by default, newest first.
+
+| Flag           | Description                            |
+|----------------|----------------------------------------|
+| `--query`/`-q` | Filter messages by text                |
+| `--from`       | Filter by sender                       |
+| `--limit`      | Max messages (default 50)              |
+| `--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     |
+
+### `tg context <chat> <message_id>`
+
+View a message with surrounding context. Returns JSONL by default.
+
+| Flag        | Description                       |
+|-------------|-----------------------------------|
+| `--context` | Messages before/after (default 5) |
+| `--pretty`  | Rich text output instead of JSONL |
+
+## Configuration
+
+Config lives at `~/.config/tgcli/config.toml`:
+
+```toml
+api_id = 123456
+api_hash = "your_api_hash"
+```
+
+Alternatively, set `TELEGRAM_API_ID` and `TELEGRAM_API_HASH` environment variables.
+
+## Contributing
+
+```bash
+uv sync --group dev
+uv run pytest
+uv run ruff check
+```
+
+Tests mock Telethon entirely; no real API calls are made.
+
+## License
+
+[MIT](LICENSE)

pytgcli-0.7.0/README.md

@@ -0,0 +1,150 @@
+# tgcli — Telegram for your terminal and your AI agents.
+
+Give AI agents (Claude Code, Codex, Cursor, etc.) direct access to your Telegram conversations. Structured JSONL output, minimal command surface, fuzzy name resolution. Works equally well for humans with `--pretty`.
+
+## Features
+
+- **JSONL by default** — one JSON object per line; agents parse it natively, scripts pipe it freely
+- **Minimal surface** — a handful of commands; easy for agents to discover and invoke
+- **Fuzzy resolution** — chat and user names match by display name (no numeric IDs required)
+- **`--pretty` for humans** — Rich tables when you want to read output yourself
+- **Secure session storage** — Telethon session key stored in macOS Keychain via `keyring`
+
+## Installation
+
+Requires Python 3.12+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv tool install pytgcli
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/tksohishi/tgcli.git
+cd tgcli
+uv tool install .
+```
+
+## Quick Start
+
+### 1. Get API Credentials
+
+Create a Telegram API app at [my.telegram.org/apps](https://my.telegram.org/apps). You'll get an `api_id` and `api_hash`.
+
+### 2. Authenticate
+
+```bash
+tg auth
+```
+
+This walks you through setup: saves your API credentials to `~/.config/tgcli/config.toml`, then logs in with phone number + verification code.
+
+### 3. Read Messages
+
+```bash
+tg read "Alice"
+tg read "Finance Team" --limit 20
+tg read "Finance Team" -q "budget"
+tg read "Finance Team" -q "deadline" --from "Alice" --after 2025-01-01
+```
+
+### 4. View Context
+
+```bash
+tg context "Finance Team" 12345
+```
+
+## Use with AI Agents
+
+Once authenticated, any AI coding agent with shell access can use tgcli directly. A few examples:
+
+**Ask Claude Code to summarize a group chat:**
+
+> "Read the last 30 messages from 'Engineering' and summarize the key decisions."
+
+The agent runs `tg read "Engineering" --limit 30`, parses the JSONL, and responds.
+
+**Find a past conversation:**
+
+> "What did I discuss with Alice last week about the deployment?"
+
+The agent runs `tg read "Alice" -q "deployment" --after 2025-02-14` and surfaces the relevant messages.
+
+**Pipe into scripts:**
+
+```bash
+tg read "Alerts" --limit 100 | jq 'select(.text | test("ERROR"))'
+```
+
+No wrapper libraries or API adapters needed. The structured output and simple command surface mean agents can use tgcli out of the box.
+
+## Commands
+
+### `tg auth`
+
+Smart entrypoint: creates config if missing, logs in if needed, shows status if already authenticated.
+
+Explicit subcommands:
+
+- `tg auth login` - interactive login (phone + code/2FA)
+- `tg auth logout` - remove session from Keychain
+- `tg auth status` - show auth state
+
+### `tg chats`
+
+List your Telegram chats. Returns JSONL by default.
+
+| Flag       | Description                  |
+|------------|------------------------------|
+| `--filter` | Fuzzy filter by chat name    |
+| `--limit`  | Max chats to list (default 100) |
+| `--pretty` | Rich table output instead of JSONL |
+
+### `tg read <chat>`
+
+Read recent messages from a chat. Returns JSONL by default, newest first.
+
+| Flag           | Description                            |
+|----------------|----------------------------------------|
+| `--query`/`-q` | Filter messages by text                |
+| `--from`       | Filter by sender                       |
+| `--limit`      | Max messages (default 50)              |
+| `--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     |
+
+### `tg context <chat> <message_id>`
+
+View a message with surrounding context. Returns JSONL by default.
+
+| Flag        | Description                       |
+|-------------|-----------------------------------|
+| `--context` | Messages before/after (default 5) |
+| `--pretty`  | Rich text output instead of JSONL |
+
+## Configuration
+
+Config lives at `~/.config/tgcli/config.toml`:
+
+```toml
+api_id = 123456
+api_hash = "your_api_hash"
+```
+
+Alternatively, set `TELEGRAM_API_ID` and `TELEGRAM_API_HASH` environment variables.
+
+## Contributing
+
+```bash
+uv sync --group dev
+uv run pytest
+uv run ruff check
+```
+
+Tests mock Telethon entirely; no real API calls are made.
+
+## License
+
+[MIT](LICENSE)

pytgcli-0.7.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pytgcli"
+version = "0.7.0"
+description = "CLI tool to read Telegram messages from the terminal"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+authors = [{ name = "Takeshi" }]
+keywords = ["telegram", "cli", "messages"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Communications :: Chat",
+    "Typing :: Typed",
+]
+dependencies = [
+    "typer>=0.15",
+    "telethon>=1.42",
+    "keyring>=25",
+    "rich>=13",
+]
+
+[project.urls]
+Repository = "https://github.com/tksohishi/tgcli"
+
+[dependency-groups]
+dev = [
+    "pip-audit>=2",
+    "pytest>=8",
+    "pytest-asyncio>=0.25",
+    "ruff>=0.15",
+]
+
+[project.scripts]
+tg = "tgcli.cli:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tgcli"]
+
+[tool.ruff]
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "S", "UP"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["S101", "S108"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

pytgcli-0.7.0/src/tgcli/auth.py

@@ -0,0 +1,73 @@
+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
+
+
+async def login() -> None:
+    """Interactive login: phone + code/2FA. Saves session to Keychain."""
+    client = create_client()
+    try:
+        await client.start(phone=lambda: input("Phone number: "))
+        session_str = StringSession.save(client.session)
+        save_session(session_str)
+    finally:
+        await client.disconnect()
+
+
+async def logout() -> None:
+    """Log out and remove session from Keychain.
+
+    Always deletes the local session, even if the remote logout fails.
+    """
+    try:
+        client = create_client()
+        try:
+            await client.connect()
+            if await client.is_user_authorized():
+                await client.log_out()
+        finally:
+            await client.disconnect()
+    except Exception:  # noqa: S110
+        pass
+    delete_session()
+
+
+async def get_status() -> dict:
+    """Return auth status info.
+
+    Returns dict with keys: authenticated, phone, session_exists.
+    """
+    session_exists = load_session() is not None
+
+    if not session_exists:
+        return {
+            "authenticated": False,
+            "phone": None,
+            "session_exists": False,
+        }
+
+    client = create_client()
+    try:
+        await client.connect()
+        authorized = await client.is_user_authorized()
+        phone = None
+        if authorized:
+            me = await client.get_me()
+            if me and me.phone:
+                # Mask phone: show first 3 and last 2 digits
+                p = me.phone
+                if len(p) > 5:
+                    phone = p[:3] + "*" * (len(p) - 5) + p[-2:]
+                else:
+                    phone = p
+    finally:
+        await client.disconnect()
+
+    return {
+        "authenticated": authorized,
+        "phone": phone,
+        "session_exists": session_exists,
+    }