telegram-userbot-cli 0.1.0__py3-none-any.whl

tgcli/chats.py

@@ -0,0 +1,229 @@
+"""Chat / search / contacts / profile commands."""
+
+from telethon import functions, types
+
+from .client import run_with_client
+from .output import TgError, fmt_message_row, json_pp
+from .resolve import resolve_chat
+
+
+async def cmd_me(args) -> None:
+    async with run_with_client(args) as client:
+        me = await client.get_me()
+        print(json_pp(me.to_dict() if me else {}))
+
+
+async def cmd_chats(args) -> None:
+    async with run_with_client(args) as client:
+        dialogs = await client.get_dialogs(limit=args.limit)
+        q = args.query.lower() if args.query else None
+        rows = []
+        for d in dialogs:
+            kind = kind_of(d)
+            if args.type and kind != args.type:
+                continue
+            if args.unread and not d.unread_count:
+                continue
+            if args.archived is not None and bool(d.archived) != args.archived:
+                continue
+            name = d.name or ""
+            uname = getattr(d.entity, "username", None) or ""
+            if q and q not in f"{name} {uname}".lower():
+                continue
+            rows.append((d, kind, name, uname))
+        if args.json:
+            print(
+                json_pp(
+                    [
+                        {
+                            "id": d.id,
+                            "name": name,
+                            "username": uname,
+                            "type": kind,
+                            "unread": d.unread_count,
+                            "muted": muted_of(d),
+                            "archived": d.archived,
+                        }
+                        for d, kind, name, uname in rows
+                    ]
+                )
+            )
+            return
+        if not rows:
+            print("(no chats matched)")
+            return
+        for d, kind, name, uname in rows:
+            mark = "M" if muted_of(d) else " "
+            unread_s = f"({d.unread_count})" if d.unread_count else ""
+            print(f"{kind:<8} {d.id:>14} {mark}{unread_s:<5} {name} {'@' + uname if uname else ''}")
+
+
+def kind_of(d) -> str:
+    if d.is_group:
+        return "group"
+    if d.is_channel:
+        return "channel"
+    return "user"
+
+
+def muted_of(d) -> bool:
+    # The custom Dialog wrapper drops the mute state; read it from the raw dialog.
+    notify = getattr(getattr(d, "dialog", None), "notify_settings", None)
+    mute_until = getattr(notify, "mute_until", None)
+    return bool(mute_until)
+
+
+async def cmd_hist(args) -> None:
+    async with run_with_client(args) as client:
+        entity = await resolve_chat(client, args.chat)
+        msgs = await client.get_messages(entity, limit=args.n)
+        if not msgs:
+            print("(no messages)")
+            return
+        if args.json:
+            print(json_pp([m.to_dict() for m in msgs]))
+            return
+        for m in msgs:
+            print(fmt_message_row(m))
+
+
+async def cmd_pinned(args) -> None:
+    async with run_with_client(args) as client:
+        entity = await resolve_chat(client, args.chat)
+        # telethon 1.44 removed get_pinned_messages; use the raw search
+        res = await client(
+            functions.messages.SearchRequest(
+                peer=entity,
+                q="",
+                filter=types.InputMessagesFilterPinned(),
+                min_date=None,
+                max_date=None,
+                offset_id=0,
+                add_offset=0,
+                limit=10,
+                max_id=0,
+                min_id=0,
+                hash=0,
+            )
+        )
+        msgs = getattr(res, "messages", [])
+        if not msgs:
+            print("No pinned messages found in this chat.")
+            return
+        print(json_pp([m.to_dict() for m in msgs]))
+
+
+async def cmd_search(args) -> None:
+    async with run_with_client(args) as client:
+        entity = await resolve_chat(client, args.chat)
+        msgs = await client.get_messages(entity, search=args.query, limit=args.n)
+        if not msgs:
+            print("(no matches)")
+            return
+        print(json_pp([m.to_dict() for m in msgs]))
+
+
+async def cmd_gsearch(args) -> None:
+    async with run_with_client(args) as client:
+        req = functions.messages.SearchGlobalRequest(
+            q=args.query,
+            filter=types.InputMessagesFilterEmpty(),
+            min_date=None,
+            max_date=None,
+            offset_rate=0,
+            offset_peer=types.InputPeerEmpty(),
+            offset_id=0,
+            limit=20,
+        )
+        results: list = []
+        page = args.page
+        while page > 0:
+            res = await client(req)
+            results.extend(getattr(res, "messages", []))
+            if not isinstance(res, (types.messages.MessagesSlice, types.messages.ChannelMessages)):
+                break
+            if not res.next_rate:
+                break
+            req.offset_rate, req.offset_peer, req.offset_id = (
+                res.next_rate,
+                res.next_peer,
+                res.next_id,
+            )
+            page -= 1
+        if not results:
+            print("(no results)")
+            return
+        print(json_pp([m.to_dict() for m in results]))
+
+
+async def cmd_contacts(args) -> None:
+    async with run_with_client(args) as client:
+        res = await client(functions.contacts.GetContactsRequest(hash=0))
+        print(json_pp([u.to_dict() for u in res.users]))
+
+
+async def cmd_profile(args) -> None:
+    if not (args.name or args.bio or args.photo):
+        raise TgError("nothing to update; pass at least one of --name / --bio / --photo")
+    async with run_with_client(args) as client:
+        if args.name:
+            first, _, last = args.name.partition(" ")
+            await client(
+                functions.account.UpdateProfileRequest(first_name=first, last_name=last or "")
+            )
+        if args.bio:
+            await client(functions.account.UpdateProfileRequest(about=args.bio))
+        if args.photo:
+            uploaded = await client.upload_file(args.photo)
+            await client(functions.photos.UploadProfilePhotoRequest(file=uploaded))
+        me = await client.get_me()
+        print(json_pp(me.to_dict() if me else {}))
+
+
+def setup(subparsers, common=None) -> None:
+    parents = [common] if common else []
+    sp = subparsers.add_parser("me", parents=parents, help="Show your account info")
+    sp.set_defaults(func=cmd_me)
+
+    sp = subparsers.add_parser(
+        "chats", parents=parents, help="List dialogs (optional keyword filter)"
+    )
+    sp.add_argument("query", nargs="?", default=None, help="filter by name/username")
+    sp.add_argument("-n", "--limit", type=int, default=20)
+    sp.add_argument("-t", "--type", choices=["user", "group", "channel"])
+    sp.add_argument("-u", "--unread", action="store_true", help="unread only")
+    sp.add_argument("--archived", action="store_true", default=None, help="archived only")
+    sp.set_defaults(func=cmd_chats)
+
+    sp = subparsers.add_parser(
+        "hist", parents=parents, help='Show recent messages, e.g. tg hist "Music Bot" 10'
+    )
+    sp.add_argument("chat")
+    sp.add_argument("n", nargs="?", type=int, default=10, help="count (default 10)")
+    sp.set_defaults(func=cmd_hist)
+
+    sp = subparsers.add_parser("pinned", parents=parents, help="Show pinned messages of a chat")
+    sp.add_argument("chat")
+    sp.set_defaults(func=cmd_pinned)
+
+    sp = subparsers.add_parser("search", parents=parents, help="Search messages inside a chat")
+    sp.add_argument("chat")
+    sp.add_argument("query")
+    sp.add_argument("-n", "--limit", type=int, default=20, dest="n")
+    sp.set_defaults(func=cmd_search)
+
+    sp = subparsers.add_parser("gsearch", parents=parents, help="Global search across public chats")
+    sp.add_argument("query")
+    sp.add_argument("-p", "--page", type=int, default=1)
+    sp.set_defaults(func=cmd_gsearch)
+
+    sp = subparsers.add_parser("contacts", parents=parents, help="List contacts")
+    sp.set_defaults(func=cmd_contacts)
+
+    sp = subparsers.add_parser(
+        "profile", parents=parents, help="Update your profile (name / bio / photo)"
+    )
+    sp.add_argument("--name", default=None, help='first and last name, e.g. "John Doe"')
+    sp.add_argument("--bio", default=None)
+    sp.add_argument("--photo", default=None, help="path to an image")
+    sp.set_defaults(func=cmd_profile)

tgcli/cli.py

@@ -0,0 +1,101 @@
+"""tg — standalone Telegram command-line client (direct Telethon, no MCP)."""
+
+import argparse
+import asyncio
+import sys
+
+from telethon import errors
+
+from . import __version__, auth, chats, media, messages, resolve
+from .output import TgError
+
+
+def build_parser() -> argparse.ArgumentParser:
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--account", default=None, help="account label (v1: default only)")
+    common.add_argument(
+        "--json", action="store_true", help="print raw tool output without line formatting"
+    )
+
+    p = argparse.ArgumentParser(
+        prog="tg",
+        description="Standalone Telegram command-line client (direct Telethon connection, no MCP).",
+        epilog='Tip: messages starting with "-" need "--", e.g. tg send me -- -hello',
+    )
+    p.add_argument("--version", action="version", version=f"tg {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    # auth (no --account/--json needed, but harmless to keep consistent)
+    sp = sub.add_parser("login", parents=[common], help="Log in (default: QR code)")
+    sp.add_argument(
+        "--qr", action="store_true", default=False, help="QR login (this is the default)"
+    )
+    sp.add_argument(
+        "--phone",
+        nargs="?",
+        const="",
+        default=None,
+        help="phone login instead of QR; optionally pass the number",
+    )
+    sp.set_defaults(func=auth.cmd_login)
+    sp2 = sub.add_parser("logout", parents=[common], help="Log out and remove the session")
+    sp2.set_defaults(func=auth.cmd_logout)
+
+    for mod in (messages, chats, media):
+        mod.setup(sub, common)
+
+    resolve.setup_alias(sub, common)
+    return p
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        asyncio.run(args.func(args))
+        return 0
+    except TgError as e:
+        print(f"tg: {e}", file=sys.stderr)
+        if e.hint:
+            print(f"hint: {e.hint}", file=sys.stderr)
+        return e.code
+    except errors.AuthKeyDuplicatedError:
+        print(
+            "tg: session is in use by another connection (AuthKeyDuplicatedError)", file=sys.stderr
+        )
+        print(
+            "hint: this CLI and the MCP daemon must use separate sessions; "
+            "run `tg logout` then `tg login --qr` to get a fresh one",
+            file=sys.stderr,
+        )
+        return 2
+    except (errors.UnauthorizedError, errors.AuthKeyInvalidError):
+        print("tg: session is no longer valid", file=sys.stderr)
+        print("hint: log in again with: tg login --qr", file=sys.stderr)
+        return 2
+    except errors.SessionPasswordNeededError:
+        print("tg: two-step verification password required", file=sys.stderr)
+        return 2
+    except errors.FloodWaitError as e:
+        print(f"tg: rate-limited; Telegram asks to wait {e.seconds}s", file=sys.stderr)
+        return 1
+    except ValueError as e:
+        # e.g. entity resolution failures ("Cannot find any entity ...")
+        print(f"tg: {e}", file=sys.stderr)
+        return 1
+    except errors.RPCError as e:
+        print(f"tg: Telegram API error: {e}", file=sys.stderr)
+        return 1
+    except (OSError, ConnectionError) as e:
+        print(f"tg: cannot reach Telegram: {e}", file=sys.stderr)
+        print(
+            "hint: check that the proxy is up (e.g. Clash 127.0.0.1:7890) "
+            "and TELEGRAM_PROXY_* in .env",
+            file=sys.stderr,
+        )
+        return 2
+    except (KeyboardInterrupt, BrokenPipeError):
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tgcli/client.py

@@ -0,0 +1,46 @@
+"""Telethon client factory and per-invocation lifecycle."""
+
+import contextlib
+import os
+from collections.abc import AsyncIterator
+
+from telethon import TelegramClient
+from telethon.sessions import StringSession
+
+from . import config
+from .output import TgError
+
+
+def build_client(session: str | StringSession, api_id: int, api_hash: str) -> TelegramClient:
+    """Build a client with proxy and device identity injected."""
+    kwargs: dict = {}
+    proxy = config.build_proxy()
+    if proxy is None:
+        raise TgError(
+            "No proxy configured (TELEGRAM_PROXY_TYPE/HOST/PORT are empty)",
+            "Telegram is unreachable directly from this network; set the proxy in .env "
+            "(e.g. socks5 127.0.0.1:7890 for Clash)",
+            code=2,
+        )
+    kwargs["proxy"] = proxy
+    for kw, env in (
+        ("device_model", "TELEGRAM_DEVICE_MODEL"),
+        ("system_version", "TELEGRAM_SYSTEM_VERSION"),
+        ("app_version", "TELEGRAM_APP_VERSION"),
+    ):
+        if os.environ.get(env):
+            kwargs[kw] = os.environ[env]
+    return TelegramClient(session, api_id, api_hash, **kwargs)
+
+
+@contextlib.asynccontextmanager
+async def run_with_client(args) -> AsyncIterator[TelegramClient]:
+    """One short-lived client per invocation: connect → yield → disconnect."""
+    api_id, api_hash = config.require_credentials()
+    session_str = config.load_session(getattr(args, "account", None))
+    client = build_client(StringSession(session_str), api_id, api_hash)
+    try:
+        await client.connect()
+        yield client
+    finally:
+        await client.disconnect()

tgcli/config.py

@@ -0,0 +1,129 @@
+"""Configuration: .env precedence, proxy tuple, session persistence."""
+
+import os
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+from .output import TgError
+
+# src/tgcli/config.py -> project root (parents[2]); works for both source
+# checkouts and editable installs (which point at the same file).
+PROJECT_ROOT = Path(__file__).resolve().parents[2]
+
+# Precedence (highest wins): real env vars > .env in CWD > .env in project root.
+# load_dotenv never overrides already-set variables, so load project root first.
+load_dotenv(PROJECT_ROOT / ".env")
+load_dotenv(Path.cwd() / ".env")
+
+
+def require_credentials() -> tuple[int, str]:
+    """Return (api_id, api_hash) or raise with a config hint."""
+    raw_id = os.environ.get("TELEGRAM_API_ID", "").strip()
+    api_hash = os.environ.get("TELEGRAM_API_HASH", "").strip()
+    if not raw_id or not api_hash:
+        raise TgError(
+            "TELEGRAM_API_ID / TELEGRAM_API_HASH are not configured",
+            "Get them from https://my.telegram.org/apps and put them in .env",
+            code=2,
+        )
+    try:
+        api_id = int(raw_id)
+    except ValueError:
+        raise TgError("TELEGRAM_API_ID must be an integer", code=2) from None
+    return api_id, api_hash
+
+
+def build_proxy() -> tuple | None:
+    """Build the telethon proxy tuple from TELEGRAM_PROXY_* vars.
+
+    Telethon tuple form: (type, addr, port[, rdns, username, password]).
+    NOTE: the 4th element is rdns, NOT username.
+    """
+    ptype = os.environ.get("TELEGRAM_PROXY_TYPE", "").strip().lower()
+    host = os.environ.get("TELEGRAM_PROXY_HOST", "").strip()
+    port = os.environ.get("TELEGRAM_PROXY_PORT", "").strip()
+    if not (ptype and host and port):
+        return None
+    user = os.environ.get("TELEGRAM_PROXY_USERNAME", "").strip()
+    pw = os.environ.get("TELEGRAM_PROXY_PASSWORD", "").strip()
+    rdns_raw = os.environ.get("TELEGRAM_PROXY_RDNS", "true").strip().lower()
+    rdns = rdns_raw not in ("0", "false", "no")
+    try:
+        port_int = int(port)
+    except ValueError:
+        raise TgError(f"TELEGRAM_PROXY_PORT must be an integer, got: {port}", code=2) from None
+    if user:
+        return (ptype, host, port_int, rdns, user, pw)
+    return (ptype, host, port_int)
+
+
+def session_env_var(account: str | None) -> str:
+    """Env var name holding the session string for an account (v1: default only)."""
+    if account is None:
+        return "TELEGRAM_SESSION_STRING"
+    return f"TELEGRAM_SESSION_STRING_{account.strip().upper()}"
+
+
+def load_session(account: str | None) -> str:
+    """Return the session string, or raise a config hint if not logged in."""
+    var = session_env_var(account)
+    value = os.environ.get(var, "").strip()
+    if not value:
+        if account is not None:
+            raise TgError(
+                f"No session configured for account '{account}'",
+                f"Set {var} in .env (v1 supports the default account only)",
+                code=2,
+            )
+        raise TgError(
+            "Not logged in: TELEGRAM_SESSION_STRING not found",
+            "Run: tg login --qr",
+            code=2,
+        )
+    return value
+
+
+def write_env(key: str, value: str, comment: str | None = None) -> Path:
+    """Rewrite .env in the project root, preserving comments; replace the
+    existing key line in place or append. Returns the .env path."""
+    env_path = PROJECT_ROOT / ".env"
+    lines = env_path.read_text(encoding="utf-8").splitlines() if env_path.exists() else []
+    out: list[str] = []
+    done = False
+    for line in lines:
+        if line.startswith(f"{key}="):
+            if comment:
+                out.append(f"# {comment}")
+            out.append(f"{key}={value}")
+            done = True
+        else:
+            out.append(line)
+    if not done:
+        if out and out[-1].strip():
+            out.append("")
+        if comment:
+            out.append(f"# {comment}")
+        out.append(f"{key}={value}")
+    env_path.write_text("\n".join(out) + "\n", encoding="utf-8")
+    return env_path
+
+
+def clear_env(key: str) -> None:
+    """Remove a key line (and the comment line directly above it) from .env."""
+    env_path = PROJECT_ROOT / ".env"
+    if not env_path.exists():
+        return
+    lines = env_path.read_text(encoding="utf-8").splitlines()
+    out: list[str] = []
+    i = 0
+    while i < len(lines):
+        if lines[i].startswith(f"{key}="):
+            # drop the comment line immediately above, if any
+            if out and out[-1].startswith("#"):
+                out.pop()
+            i += 1
+            continue
+        out.append(lines[i])
+        i += 1
+    env_path.write_text("\n".join(out) + "\n", encoding="utf-8")

tgcli/media.py

@@ -0,0 +1,91 @@
+"""Media commands: dl (download), sf (send file/album), voice."""
+
+import os
+import re
+
+from .client import run_with_client
+from .output import TgError
+from .resolve import resolve_chat
+
+
+async def cmd_dl(args) -> None:
+    async with run_with_client(args) as client:
+        entity = await resolve_chat(client, args.chat)
+        msgs = await client.get_messages(entity, ids=args.msg_id)
+        if not isinstance(msgs, list):  # single id returns a bare Message
+            msgs = [msgs]
+        msg = msgs[0] if msgs else None
+        if msg is None or not msg.media:
+            raise TgError(
+                f"message {args.msg_id} has no media",
+                hint=f"check with: tg hist {args.chat} 5",
+            )
+        if args.out:
+            out = os.path.expanduser(args.out)
+        else:
+            safe = re.sub(r"[^A-Za-z0-9_.-]+", "_", str(args.chat))
+            out = os.path.expanduser(f"~/Downloads/telegram_{safe}_{args.msg_id}")
+        # append the real extension when the caller did not give one
+        ext = getattr(getattr(msg, "file", None), "ext", None)
+        if ext and not os.path.splitext(out)[1]:
+            out += ext
+        try:
+            path = await client.download_media(msg, file=out)
+        except OSError as e:
+            raise TgError(
+                f"cannot write to {out}: {e}",
+                "macOS: grant the terminal app access to this folder "
+                "(System Settings → Privacy & Security → Files and Folders), "
+                "or pass -o with a different path",
+                code=2,
+            ) from None
+        if not path:
+            raise TgError("download failed (no data returned)")
+        print(f"Media downloaded to {path}")
+
+
+async def cmd_sf(args) -> None:
+    async with run_with_client(args) as client:
+        entity = await resolve_chat(client, args.chat)
+        files = [os.path.expanduser(f) for f in args.files]
+        # single file must be a string; a list of 2-10 becomes an album
+        payload = files[0] if len(files) == 1 else files
+        sent = await client.send_file(entity, payload, caption=args.caption)
+        count = len(sent) if isinstance(sent, list) else 1
+        print(f"Sent {count} file(s)")
+
+
+async def cmd_voice(args) -> None:
+    async with run_with_client(args) as client:
+        entity = await resolve_chat(client, args.chat)
+        await client.send_file(entity, os.path.expanduser(args.file), voice_note=True)
+        print("Voice note sent")
+
+
+def setup(subparsers, common=None) -> None:
+    parents = [common] if common else []
+    sp = subparsers.add_parser(
+        "dl", parents=parents, help="Download media, e.g. tg dl 7381828427 785"
+    )
+    sp.add_argument("chat")
+    sp.add_argument("msg_id", type=int)
+    sp.add_argument(
+        "-o",
+        "--out",
+        default=None,
+        help="output path (default ~/Downloads/telegram_<chat>_<msgid>)",
+    )
+    sp.set_defaults(func=cmd_dl)
+
+    sp = subparsers.add_parser(
+        "sf", parents=parents, help="Send files (2-10 files become an album)"
+    )
+    sp.add_argument("chat")
+    sp.add_argument("files", nargs="+")
+    sp.add_argument("-c", "--caption", default=None)
+    sp.set_defaults(func=cmd_sf)
+
+    sp = subparsers.add_parser("voice", parents=parents, help="Send a voice note")
+    sp.add_argument("chat")
+    sp.add_argument("file")
+    sp.set_defaults(func=cmd_voice)