pytgcli 0.7.0__py3-none-any.whl

pytgcli-0.7.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+tgcli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tgcli/auth.py,sha256=v7NGmalp2JiKJWbIocDZ__BD8BeDISi62IsbGqYmyDM,1988
+tgcli/cli.py,sha256=Wr9vJ1OqrQIfGEmTk3ECrM4v5Wde-IX7GN031LRpgFs,10430
+tgcli/client.py,sha256=pI-hOHU4oCcxF2FWoRQfEkNMkXtVo3Mfjdv6ZvWCft0,6750
+tgcli/config.py,sha256=58GIHkPEffSIAT1q8baBy097IItSjfh1ya1DMpmalG8,1770
+tgcli/formatting.py,sha256=5568iJVA4FgfuQz2JKUDVj1gG2cVxOsDuyRz-3ZooMs,4027
+tgcli/session.py,sha256=svd1axrP6EZXEAMXQSm7OpWOas1GdeTT1iWgUWtHjpo,757
+pytgcli-0.7.0.dist-info/METADATA,sha256=iJCMun85yhQ1z3VTvcXwycNwO7u1ewH7Bj4IW1BUEDw,5051
+pytgcli-0.7.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+pytgcli-0.7.0.dist-info/entry_points.txt,sha256=RZzTkIaOpH6ShabkhHLCmNp5mVmlBFXIGZ_N2IAt8CY,37
+pytgcli-0.7.0.dist-info/licenses/LICENSE,sha256=8_Od5tjv6EKv--zs-_a_Nk4DzMYj_XGrLVZwiMeUCj0,1064
+pytgcli-0.7.0.dist-info/RECORD,,

pytgcli-0.7.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pytgcli-0.7.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tg = tgcli.cli:app

pytgcli-0.7.0.dist-info/licenses/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.

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,
+    }

tgcli/cli.py

@@ -0,0 +1,336 @@
+from __future__ import annotations
+
+import asyncio
+from datetime import UTC, datetime
+from importlib.metadata import version
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from telethon.errors import UnauthorizedError
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        print(version("pytgcli"))
+        raise typer.Exit()
+
+
+app = typer.Typer(help="Read Telegram messages from the terminal.")
+auth_app = typer.Typer(
+    help="Manage Telegram authentication.", invoke_without_command=True
+)
+app.add_typer(auth_app, name="auth")
+
+stdout = Console()
+
+
+@app.callback()
+def main(
+    _version: Annotated[
+        bool | None,
+        typer.Option(
+            "--version",
+            callback=_version_callback,
+            is_eager=True,
+            help="Show version and exit.",
+        ),
+    ] = None,
+) -> None:
+    """Read Telegram messages from the terminal."""
+
+
+stderr = Console(stderr=True)
+
+
+@auth_app.callback(invoke_without_command=True)
+def auth_default(ctx: typer.Context) -> None:
+    """Smart auth: configure, login, or show status as needed."""
+    if ctx.invoked_subcommand is not None:
+        return
+
+    from tgcli.config import CONFIG_PATH, load_config, write_config
+    from tgcli.formatting import format_auth_status
+
+    # Step 1: ensure config exists
+    try:
+        load_config()
+    except SystemExit:
+        import webbrowser
+
+        stderr.print(f"No config found at {CONFIG_PATH}\n")
+        stderr.print("You need a Telegram API app to use this tool.")
+        typer.prompt(
+            "Press Enter to open my.telegram.org/apps", default="", show_default=False
+        )
+        webbrowser.open("https://my.telegram.org/apps")
+        api_id = typer.prompt("\nAPI ID", type=int)
+        api_hash = typer.prompt("API Hash", type=str)
+        path = write_config(api_id, api_hash)
+        stderr.print(f"Config written to {path}\n")
+    except Exception as e:
+        stderr.print(f"[red]Config error:[/red] {e}")
+        stderr.print(f"Check your config at {CONFIG_PATH}")
+        raise typer.Exit(1)
+
+    # Step 2: check auth state
+    from tgcli.auth import get_status
+
+    try:
+        info = asyncio.run(get_status())
+    except Exception as e:
+        stderr.print(f"[red]Error checking status:[/red] {e}")
+        raise typer.Exit(1)
+
+    if info["authenticated"]:
+        stdout.print(format_auth_status(**info))
+        stdout.print("Run `tg auth logout` to log out.")
+        return
+
+    # Step 3: not authenticated, run login
+    _run_login()
+
+
+def _run_login() -> None:
+    """Shared login flow for both `tg auth` and `tg auth login`."""
+    from tgcli.auth import login as _login
+
+    stderr.print(
+        "\nLogging in to Telegram. You'll be asked for your phone number\n"
+        "including country code (e.g. +81 90 1234 5678). The + and any\n"
+        "spaces/dashes are optional, but the country code is required.\n"
+        "Telegram will send a verification code to your account, like\n"
+        "logging in on a new device. Your phone number is sent to\n"
+        "Telegram's API only; tgcli does not store or transmit it.\n"
+    )
+    try:
+        asyncio.run(_login())
+    except Exception as e:
+        stderr.print(f"[red]Login failed:[/red] {e}")
+        raise typer.Exit(1)
+    stderr.print(
+        "\nRegarding the ToS warning above: unofficial API clients are\n"
+        "under 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"
+    )
+    stdout.print("[green]Login successful.[/green]")
+
+
+@auth_app.command()
+def login() -> None:
+    """Interactive login: phone + verification code (or 2FA password)."""
+    _run_login()
+
+
+@auth_app.command()
+def logout() -> None:
+    """Remove session from Keychain."""
+    from tgcli.auth import logout as _logout
+
+    try:
+        asyncio.run(_logout())
+        stdout.print("Logged out.")
+    except Exception as e:
+        stderr.print(f"[red]Logout failed:[/red] {e}")
+        raise typer.Exit(1)
+
+
+@auth_app.command()
+def status() -> None:
+    """Show current auth state."""
+    from tgcli.auth import get_status
+    from tgcli.formatting import format_auth_status
+
+    try:
+        info = asyncio.run(get_status())
+    except SystemExit as e:
+        stderr.print(f"[red]Configuration error:[/red] {e}")
+        stderr.print("Run `tg auth` to set up.")
+        raise typer.Exit(1)
+    except Exception as e:
+        stderr.print(f"[red]Error checking status:[/red] {e}")
+        raise typer.Exit(1)
+
+    stdout.print(format_auth_status(**info))
+
+
+def _parse_date(value: str) -> datetime:
+    return datetime.strptime(value, "%Y-%m-%d").replace(tzinfo=UTC)
+
+
+@app.command()
+def chats(
+    filter_: Annotated[
+        str | None, typer.Option("--filter", help="Fuzzy filter by chat name.")
+    ] = None,
+    limit: Annotated[int, typer.Option(help="Max chats to list.")] = 100,
+    pretty: Annotated[
+        bool, typer.Option("--pretty", help="Rich table output.")
+    ] = False,
+) -> None:
+    """List your Telegram chats."""
+    from tgcli.client import create_client, list_chats
+
+    async def _run():
+        client = create_client()
+        async with client:
+            return await list_chats(client, filter_name=filter_, limit=limit)
+
+    try:
+        results = asyncio.run(_run())
+    except SystemExit as e:
+        stderr.print(f"[red]Configuration error:[/red] {e}")
+        stderr.print("Run `tg auth` to set up.")
+        raise typer.Exit(1)
+    except UnauthorizedError:
+        stderr.print("[red]Not authenticated.[/red] Run `tg auth login` first.")
+        raise typer.Exit(2)
+    except Exception as e:
+        stderr.print(f"[red]Failed to list chats:[/red] {e}")
+        raise typer.Exit(1)
+
+    if not results:
+        stdout.print("No chats found.")
+        return
+
+    if pretty:
+        from tgcli.formatting import format_chats_table
+
+        stdout.print(format_chats_table(results))
+    else:
+        from tgcli.formatting import format_chat_jsonl
+
+        for chat in results:
+            print(format_chat_jsonl(chat))
+
+
+@app.command()
+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.")
+    ] = None,
+    limit: Annotated[int, typer.Option(help="Max messages to return.")] = 50,
+    head: Annotated[
+        bool, typer.Option("--head", help="Oldest messages first.")
+    ] = False,
+    after: Annotated[
+        str | None, typer.Option(help="Only messages after this date (YYYY-MM-DD).")
+    ] = None,
+    before: Annotated[
+        str | None, typer.Option(help="Only messages before this date (YYYY-MM-DD).")
+    ] = None,
+    pretty: Annotated[
+        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)."""
+    from tgcli.client import create_client, read_messages
+
+    try:
+        after_dt = _parse_date(after) if after else None
+        before_dt = _parse_date(before) if before else None
+    except ValueError as e:
+        stderr.print(f"[red]Invalid date format:[/red] {e}")
+        stderr.print("Expected format: YYYY-MM-DD")
+        raise typer.Exit(1)
+
+    async def _run():
+        client = create_client()
+        async with client:
+            return await read_messages(
+                client,
+                chat,
+                query=query or "",
+                from_=from_,
+                limit=limit,
+                after=after_dt,
+                before=before_dt,
+                reverse=head,
+            )
+
+    try:
+        results = asyncio.run(_run())
+    except SystemExit as e:
+        stderr.print(f"[red]Configuration error:[/red] {e}")
+        stderr.print("Run `tg auth` to set up.")
+        raise typer.Exit(1)
+    except UnauthorizedError:
+        stderr.print("[red]Not authenticated.[/red] Run `tg auth login` first.")
+        raise typer.Exit(2)
+    except Exception as e:
+        stderr.print(f"[red]Read failed:[/red] {e}")
+        raise typer.Exit(1)
+
+    if not results:
+        stdout.print("No messages found.")
+        return
+
+    if pretty:
+        from tgcli.formatting import format_search_results
+
+        stdout.print(format_search_results(results))
+    else:
+        from tgcli.formatting import format_message_jsonl
+
+        for msg in results:
+            print(format_message_jsonl(msg))
+
+
+@app.command()
+def context(
+    chat: str,
+    message_id: int,
+    context_size: Annotated[
+        int, typer.Option("--context", help="Messages before/after the target.")
+    ] = 5,
+    pretty: Annotated[
+        bool, typer.Option("--pretty", help="Rich text output instead of JSONL.")
+    ] = False,
+) -> None:
+    """View a message with surrounding context."""
+    from tgcli.client import create_client, get_context
+
+    async def _run():
+        client = create_client()
+        async with client:
+            return await get_context(client, chat, message_id, context=context_size)
+
+    try:
+        messages, target_id, replied_to = asyncio.run(_run())
+    except SystemExit as e:
+        stderr.print(f"[red]Configuration error:[/red] {e}")
+        stderr.print("Run `tg auth` to set up.")
+        raise typer.Exit(1)
+    except UnauthorizedError:
+        stderr.print("[red]Not authenticated.[/red] Run `tg auth login` first.")
+        raise typer.Exit(2)
+    except Exception as e:
+        stderr.print(f"[red]Context fetch failed:[/red] {e}")
+        raise typer.Exit(1)
+
+    if not messages:
+        stdout.print("No messages found.")
+        return
+
+    if pretty:
+        from tgcli.formatting import format_context
+
+        stdout.print(format_context(messages, target_id, replied_to=replied_to))
+    else:
+        from tgcli.formatting import format_message_jsonl
+
+        replied_to_id = replied_to.id if replied_to else None
+        for msg in messages:
+            print(
+                format_message_jsonl(
+                    msg,
+                    target=(msg.id == target_id),
+                    replied_to=(msg.id == replied_to_id),
+                )
+            )

tgcli/client.py

@@ -0,0 +1,224 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+from telethon import TelegramClient
+from telethon.sessions import StringSession
+
+from tgcli.config import TelegramConfig, load_config
+from tgcli.formatting import ChatData, MessageData
+from tgcli.session import load_session
+
+
+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 ""
+    return TelegramClient(
+        StringSession(session_str),
+        config.api_id,
+        config.api_hash,
+    )
+
+
+def _get_name(entity) -> str:
+    """Extract a display name from a Telethon entity."""
+    if entity is None:
+        return "Unknown"
+    if hasattr(entity, "title"):
+        return entity.title
+    parts = [getattr(entity, "first_name", None), getattr(entity, "last_name", None)]
+    return " ".join(p for p in parts if p) or "Unknown"
+
+
+async def _resolve_entity(client: TelegramClient, name: str):
+    """Resolve a name to a Telethon entity.
+
+    Handles @usernames, phone numbers, and numeric IDs via get_entity().
+    Plain names are matched case-insensitively against dialog names.
+    """
+    if name.lower() == "me":
+        return await client.get_me()
+
+    if name.startswith("@") or name.startswith("+") or name.lstrip("-").isdigit():
+        try:
+            return await client.get_entity(name)
+        except Exception:  # noqa: S110
+            pass
+
+    name_lower = name.lower()
+    async for dialog in client.iter_dialogs():
+        if dialog.name.lower() == name_lower:
+            return dialog.entity
+
+    raise ValueError(
+        f'Cannot find chat "{name}". Use `tg chats --filter` to find exact names.'
+    )
+
+
+def _msg_to_data(msg, chat_name: str, sender_name: str) -> MessageData:
+    return MessageData(
+        id=msg.id,
+        text=msg.text or "",
+        chat_name=chat_name,
+        sender_name=sender_name,
+        date=msg.date,
+        reply_to_msg_id=msg.reply_to.reply_to_msg_id if msg.reply_to else None,
+    )
+
+
+def _chat_type(entity) -> str:
+    """Determine the chat type from a Telethon entity."""
+    cls = type(entity).__name__
+    if cls == "User":
+        return "user"
+    if cls == "Channel":
+        if getattr(entity, "megagroup", False):
+            return "group"
+        return "channel"
+    return "group"
+
+
+async def list_chats(
+    client: TelegramClient,
+    *,
+    filter_name: str | None = None,
+    limit: int = 100,
+) -> list[ChatData]:
+    """List dialogs, optionally filtered by name substring.
+
+    limit controls how many dialogs to scan. With filter_name, matches
+    are returned from that scanned set.
+    """
+    filter_lower = filter_name.lower() if filter_name else None
+    results: list[ChatData] = []
+    count = 0
+    async for dialog in client.iter_dialogs():
+        count += 1
+        if not filter_lower or filter_lower in dialog.name.lower():
+            results.append(
+                ChatData(
+                    name=dialog.name,
+                    chat_type=_chat_type(dialog.entity),
+                    unread_count=dialog.unread_count,
+                    pinned=dialog.pinned,
+                    date=dialog.date,
+                )
+            )
+        if count >= limit:
+            break
+    return results
+
+
+async def read_messages(
+    client: TelegramClient,
+    chat: str,
+    *,
+    query: str = "",
+    from_: str | None = None,
+    limit: int = 50,
+    after: datetime | None = None,
+    before: datetime | None = None,
+    reverse: bool = False,
+) -> list[MessageData]:
+    """Read messages from a chat.
+
+    Default order is newest first (tail). Set reverse=True for oldest first (head).
+    Optional query does client-side text filtering. Optional from_ filters by sender
+    (resolved server-side via from_user).
+    """
+    entity = await _resolve_entity(client, chat)
+    chat_name = _get_name(entity)
+
+    from_user = None
+    if from_:
+        from_user = await _resolve_entity(client, from_)
+
+    filtering = bool(query or from_user)
+    filter_query = query.lower() if query else None
+    offset_date = before if before and not reverse else None
+
+    results: list[MessageData] = []
+    async for msg in client.iter_messages(
+        entity,
+        limit=None if filtering else limit,
+        offset_date=offset_date,
+        reverse=reverse,
+        from_user=from_user,
+    ):
+        if before and msg.date and msg.date >= before:
+            if reverse:
+                break
+            continue
+
+        if after and msg.date and msg.date < after:
+            if reverse:
+                continue
+            break
+
+        if filter_query and filter_query not in (msg.text or "").lower():
+            continue
+
+        sender = await msg.get_sender()
+        results.append(_msg_to_data(msg, chat_name, _get_name(sender)))
+        if len(results) >= limit:
+            break
+
+    return results
+
+
+async def get_context(
+    client: TelegramClient,
+    chat: str,
+    message_id: int,
+    context: int = 5,
+) -> tuple[list[MessageData], int, MessageData | None]:
+    """Get a message and surrounding context.
+
+    Returns (messages, target_id, replied_to_message).
+    """
+    entity = await _resolve_entity(client, chat)
+    chat_name = _get_name(entity)
+
+    # Fetch messages around the target: context after + target + context before
+    # iter_messages returns newest first, so offset from message_id
+    messages_raw = []
+
+    # Messages after (newer than) the target
+    after_msgs = []
+    async for msg in client.iter_messages(
+        entity,
+        min_id=message_id,
+        limit=context,
+        reverse=True,
+    ):
+        after_msgs.append(msg)
+
+    # The target message itself + messages before (older than) it
+    before_msgs = []
+    async for msg in client.iter_messages(
+        entity,
+        max_id=message_id + 1,
+        limit=context + 1,
+    ):
+        before_msgs.append(msg)
+
+    messages_raw = sorted(after_msgs + before_msgs, key=lambda m: m.id)
+
+    # Build MessageData list
+    messages: list[MessageData] = []
+    for msg in messages_raw:
+        sender = await msg.get_sender()
+        messages.append(_msg_to_data(msg, chat_name, _get_name(sender)))
+
+    # Find the replied-to message if applicable
+    replied_to = None
+    target_msg = next((m for m in messages_raw if m.id == message_id), None)
+    if target_msg and target_msg.reply_to:
+        reply_id = target_msg.reply_to.reply_to_msg_id
+        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))
+
+    return messages, message_id, replied_to

tgcli/config.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+CONFIG_PATH = Path.home() / ".config" / "tgcli" / "config.toml"
+
+
+@dataclass(frozen=True)
+class TelegramConfig:
+    api_id: int
+    api_hash: str
+
+
+def load_config(config_path: Path | None = None) -> TelegramConfig:
+    """Load Telegram API credentials.
+
+    Resolution order:
+    1. Config TOML
+    2. Env vars TELEGRAM_API_ID, TELEGRAM_API_HASH
+    3. Error with clear message
+    """
+    path = config_path or CONFIG_PATH
+    api_id: str | None = None
+    api_hash: str | None = None
+
+    if path.exists():
+        with open(path, "rb") as f:
+            data = tomllib.load(f)
+        raw_id = data.get("api_id")
+        raw_hash = data.get("api_hash")
+        if raw_id is not None:
+            api_id = str(raw_id)
+        if raw_hash is not None:
+            api_hash = str(raw_hash)
+
+    if api_id is None:
+        api_id = os.environ.get("TELEGRAM_API_ID")
+    if api_hash is None:
+        api_hash = os.environ.get("TELEGRAM_API_HASH")
+
+    if not api_id or not api_hash:
+        raise SystemExit(
+            "Telegram API credentials not found.\n"
+            f"Set them in {CONFIG_PATH} or via "
+            "TELEGRAM_API_ID / TELEGRAM_API_HASH env vars."
+        )
+
+    return TelegramConfig(api_id=int(api_id), api_hash=api_hash)
+
+
+def write_config(api_id: int, api_hash: str, config_path: Path | None = None) -> Path:
+    """Write Telegram API credentials to a TOML config file.
+
+    Creates parent directories if needed. Returns the path written to.
+    """
+    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')
+    return path

tgcli/formatting.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+from datetime import datetime
+
+from rich.table import Table
+from rich.text import Text
+
+
+@dataclass(frozen=True)
+class ChatData:
+    name: str
+    chat_type: str
+    unread_count: int
+    pinned: bool
+    date: datetime | None
+
+
+@dataclass(frozen=True)
+class MessageData:
+    id: int
+    text: str
+    chat_name: str
+    sender_name: str
+    date: datetime
+    reply_to_msg_id: int | None = None
+
+
+def _truncate(text: str, max_lines: int = 3) -> str:
+    lines = text.splitlines()
+    if len(lines) <= max_lines:
+        return text
+    return "\n".join(lines[:max_lines]) + " ..."
+
+
+def format_message_jsonl(msg: MessageData, **flags: bool) -> str:
+    """Serialize a MessageData to a single JSON line.
+
+    Extra boolean flags (e.g. target=True, replied_to=True) are merged
+    into the dict before serialization.
+    """
+    d = asdict(msg)
+    d["date"] = msg.date.isoformat()
+    for key, value in flags.items():
+        if value:
+            d[key] = True
+    return json.dumps(d, ensure_ascii=False)
+
+
+def format_search_results(messages: list[MessageData]) -> Table:
+    """Build a Rich Table for search results."""
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("Date", style="dim", no_wrap=True)
+    table.add_column("Chat")
+    table.add_column("Sender")
+    table.add_column("Message")
+
+    for msg in messages:
+        table.add_row(
+            msg.date.strftime("%Y-%m-%d %H:%M"),
+            msg.chat_name,
+            msg.sender_name,
+            _truncate(msg.text),
+        )
+
+    return table
+
+
+def format_context(
+    messages: list[MessageData],
+    target_id: int,
+    replied_to: MessageData | None = None,
+) -> Text:
+    """Build a Rich Text for context view.
+
+    The target message is highlighted. If replied_to is provided, it's
+    shown above the target with a separator.
+    """
+    output = Text()
+
+    if replied_to:
+        output.append(
+            f"  >> {replied_to.sender_name}: {replied_to.text}\n",
+            style="dim italic",
+        )
+        output.append("  " + "-" * 40 + "\n", style="dim")
+
+    for msg in messages:
+        ts = msg.date.strftime("%H:%M")
+        line = f"[{ts}] {msg.sender_name}: {msg.text}\n"
+        if msg.id == target_id:
+            output.append(line, style="bold yellow")
+        else:
+            output.append(line)
+
+    return output
+
+
+def format_chat_jsonl(chat: ChatData) -> str:
+    """Serialize a ChatData to a single JSON line."""
+    d = asdict(chat)
+    if chat.date:
+        d["date"] = chat.date.isoformat()
+    else:
+        d["date"] = None
+    return json.dumps(d, ensure_ascii=False)
+
+
+def format_chats_table(chats: list[ChatData]) -> Table:
+    """Build a Rich Table for chat listing."""
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("Name")
+    table.add_column("Type", style="dim")
+    table.add_column("Unread", justify="right")
+    table.add_column("Last message", style="dim", no_wrap=True)
+
+    for chat in chats:
+        unread = str(chat.unread_count) if chat.unread_count else ""
+        date = chat.date.strftime("%Y-%m-%d") if chat.date else ""
+        table.add_row(chat.name, chat.chat_type, unread, date)
+
+    return table
+
+
+def format_auth_status(
+    authenticated: bool,
+    phone: str | None = None,
+    session_exists: bool = False,
+) -> Text:
+    """Build a Rich Text for auth status display."""
+    output = Text()
+
+    if authenticated:
+        output.append("Status: ", style="bold")
+        output.append("authenticated\n", style="green")
+    else:
+        output.append("Status: ", style="bold")
+        output.append("not authenticated\n", style="red")
+
+    if phone:
+        output.append("Phone: ", style="bold")
+        output.append(f"{phone}\n")
+
+    output.append("Session: ", style="bold")
+    if session_exists:
+        output.append("stored in Keychain\n", style="green")
+    else:
+        output.append("none\n", style="red")
+
+    return output

tgcli/session.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import keyring
+from keyring.errors import PasswordDeleteError
+
+SERVICE_NAME = "tgcli"
+SESSION_KEY = "telegram_session"
+
+
+def save_session(session_string: str) -> None:
+    """Store the Telethon StringSession in the system keychain."""
+    keyring.set_password(SERVICE_NAME, SESSION_KEY, session_string)
+
+
+def load_session() -> str | None:
+    """Load the Telethon StringSession from the system keychain.
+
+    Returns None if no session is stored.
+    """
+    return keyring.get_password(SERVICE_NAME, SESSION_KEY)
+
+
+def delete_session() -> None:
+    """Remove the stored session from the system keychain."""
+    try:
+        keyring.delete_password(SERVICE_NAME, SESSION_KEY)
+    except PasswordDeleteError:
+        pass