telegram-userbot-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{telegram_userbot_cli-0.1.0 → telegram_userbot_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: telegram-userbot-cli
-Version: 0.1.0
+Version: 0.2.0
 Summary: Full-featured Telegram command-line client powered by a Telethon userbot (your own account, not a bot token)
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -25,9 +25,14 @@ no daemon, no external service**. Everything the CLI does lives in the CLI.
 ## Features
 
 - QR-code login (`tg login --qr`) with an independent session
-- Messaging: send / reply / edit / delete / forward / polls
-- Chats: list dialogs, history, pinned messages, in-chat & global search
-- Media: download, send files / albums, voice notes
+- Messaging: send / reply / edit / delete / forward / polls / schedule /
+  drafts / reactions / pinning
+- Chat management: archive, mute, edit title / description / photo,
+  invite links, clear history
+- Media: download, send files / albums / voice notes / stickers / GIFs,
+  contact cards
+- Chats: list dialogs, history, pinned messages, in-chat & global search,
+  online status, common chats
 - Contacts & profile management
 - Chat resolution by name fuzzy match, `@username`, numeric id, or `me`
   (Saved Messages), plus local aliases
@@ -79,6 +84,8 @@ tg logout          # remove the session
 
 ## Commands
 
+### Core
+
 | Command | Description |
 |---|---|
 | `tg me` | Show your account info |
@@ -100,6 +107,34 @@ tg logout          # remove the session
 | `tg profile --name/--bio/--photo` | Update your profile |
 | `tg alias set/list/rm` | Local chat aliases (`~/.config/tg/aliases.json`) |
 
+### Messaging & chat management (v2)
+
+| Command | Description |
+|---|---|
+| `tg schedule <chat> <time> <text...>` | Schedule a message; time is `+30m`/`+2h`/`+1d`, `2026-09-07 14:30`, or a unix ts |
+| `tg scheduled <chat>` | List scheduled messages (`--json` supported) |
+| `tg unschedule <chat> <ids...>` | Delete scheduled messages |
+| `tg draft <chat> [text]` | Save a draft (with text) or show the current draft |
+| `tg draft-clear <chat>` | Clear the draft |
+| `tg react <chat> <msg_id> <emoji>` | React to a message; `--big` for the big animation |
+| `tg unreact <chat> <msg_id>` | Remove your reaction |
+| `tg pin <chat> <msg_id>` / `tg unpin <chat> [msg_id]` | Pin / unpin (no id = unpin all) |
+| `tg read <chat>` | Mark the chat as read (also clears mention badges) |
+| `tg msg-link <chat> <msg_id>` | Export a t.me message link (channels/supergroups only) |
+| `tg contact-card <chat> "<name>" <phone>` | Send a contact card |
+| `tg sticker <chat> <file>` | Send a sticker file (`.webp` / `.tgs` / `.webm`) |
+| `tg gif <chat> <query>` | Search GIFs and send the first match; `-n N` sends the Nth |
+| `tg archive <chat>` / `tg unarchive <chat>` | Archive / unarchive a dialog |
+| `tg mute <chat> [hours]` / `tg unmute <chat>` | Mute notifications (permanent unless hours given) / unmute |
+| `tg chat-title <chat> <title>` | Change group/channel title |
+| `tg chat-about <chat> <text>` | Change chat description |
+| `tg chat-photo <chat> <file>` | Change the chat photo |
+| `tg invite-link <chat>` | Export a chat invite link |
+| `tg join <link>` | Join via `t.me/+hash`, `t.me/joinchat/…`, or `t.me/<username>` |
+| `tg clear-history <chat>` | Delete all messages (both sides; `--self-only` keeps the other copy) |
+| `tg status <user>` | Show a user's online status |
+| `tg common-chats <user>` | List chats you share with a user |
+
 Global flags: `--account` (v1: default only), `--json` (raw JSON output).
 Exit codes: `0` ok, `1` command error, `2` config/connection/session error,
 `130` interrupted.

{telegram_userbot_cli-0.1.0 → telegram_userbot_cli-0.2.0}/README-zh.md

@@ -12,9 +12,10 @@
 ## 特性
 
 - 扫码登录（`tg login --qr`），使用独立会话
-- 消息：发送 / 引用回复 / 编辑 / 删除 / 转发 / 投票
-- 聊天：会话列表、历史记录、置顶消息、会话内搜索与全局搜索
-- 媒体：下载、发文件 / 相册、语音条
+- 消息：发送 / 引用回复 / 编辑 / 删除 / 转发 / 投票 / 定时 / 草稿 / 表情回应 / 置顶
+- 聊天管理：归档、免打扰、修改群名 / 简介 / 群头像、邀请链接、清空历史
+- 媒体：下载、发文件 / 相册 / 语音条 / 贴纸 / GIF、发送名片
+- 聊天：会话列表、历史记录、置顶消息、会话内与全局搜索、在线状态、共同群组
 - 联系人与个人资料管理
 - 会话解析：名称模糊匹配、`@username`、数字 id、`me`（已保存消息），以及本地别名
 
@@ -62,6 +63,8 @@ tg logout          # 退出登录并删除会话
 
 ## 命令
 
+### 基础
+
 | 命令 | 说明 |
 |---|---|
 | `tg me` | 查看自己的账号信息 |
@@ -83,6 +86,34 @@ tg logout          # 退出登录并删除会话
 | `tg profile --name/--bio/--photo` | 修改个人资料 |
 | `tg alias set/list/rm` | 本地会话别名（`~/.config/tg/aliases.json`） |
 
+### 消息增强与聊天管理（v2）
+
+| 命令 | 说明 |
+|---|---|
+| `tg schedule <会话> <时间> <文本...>` | 定时发送；时间支持 `+30m`/`+2h`/`+1d`、`2026-09-07 14:30` 或 unix 时间戳 |
+| `tg scheduled <会话>` | 列出定时消息（支持 `--json`） |
+| `tg unschedule <会话> <id...>` | 撤销定时消息 |
+| `tg draft <会话> [文本]` | 存草稿（带文本）或查看当前草稿 |
+| `tg draft-clear <会话>` | 清空草稿 |
+| `tg react <会话> <消息id> <emoji>` | 对消息发表情回应；`--big` 大动画 |
+| `tg unreact <会话> <消息id>` | 撤销自己的表情回应 |
+| `tg pin <会话> <消息id>` / `tg unpin <会话> [消息id]` | 置顶 / 取消置顶（不带 id = 全部取消） |
+| `tg read <会话>` | 标记已读（同时清除 @ 提醒） |
+| `tg msg-link <会话> <消息id>` | 导出 t.me 消息链接（仅频道/超级群组） |
+| `tg contact-card <会话> "<姓名>" <电话>` | 发送联系人名片 |
+| `tg sticker <会话> <文件>` | 发贴纸文件（`.webp` / `.tgs` / `.webm`） |
+| `tg gif <会话> <关键词>` | 搜索 GIF 并发送第一条；`-n N` 发第 N 条 |
+| `tg archive <会话>` / `tg unarchive <会话>` | 归档 / 取消归档会话 |
+| `tg mute <会话> [小时]` / `tg unmute <会话>` | 免打扰（不带小时数 = 永久）/ 取消免打扰 |
+| `tg chat-title <会话> <标题>` | 修改群/频道标题 |
+| `tg chat-about <会话> <文本>` | 修改群简介 |
+| `tg chat-photo <会话> <文件>` | 修改群头像 |
+| `tg invite-link <会话>` | 导出群邀请链接 |
+| `tg join <链接>` | 通过 `t.me/+hash`、`t.me/joinchat/…` 或 `t.me/<用户名>` 加群 |
+| `tg clear-history <会话>` | 清空聊天记录（双方删除；`--self-only` 仅删自己一侧） |
+| `tg status <用户>` | 查看用户在线状态 |
+| `tg common-chats <用户>` | 列出与该用户的共同群组 |
+
 全局选项：`--account`（v1 仅 default）、`--json`（原始 JSON 输出）。
 退出码：`0` 成功、`1` 命令错误、`2` 配置/连接/会话错误、`130` 中断。
 

{telegram_userbot_cli-0.1.0 → telegram_userbot_cli-0.2.0}/README.md

@@ -12,9 +12,14 @@ no daemon, no external service**. Everything the CLI does lives in the CLI.
 ## Features
 
 - QR-code login (`tg login --qr`) with an independent session
-- Messaging: send / reply / edit / delete / forward / polls
-- Chats: list dialogs, history, pinned messages, in-chat & global search
-- Media: download, send files / albums, voice notes
+- Messaging: send / reply / edit / delete / forward / polls / schedule /
+  drafts / reactions / pinning
+- Chat management: archive, mute, edit title / description / photo,
+  invite links, clear history
+- Media: download, send files / albums / voice notes / stickers / GIFs,
+  contact cards
+- Chats: list dialogs, history, pinned messages, in-chat & global search,
+  online status, common chats
 - Contacts & profile management
 - Chat resolution by name fuzzy match, `@username`, numeric id, or `me`
   (Saved Messages), plus local aliases
@@ -66,6 +71,8 @@ tg logout          # remove the session
 
 ## Commands
 
+### Core
+
 | Command | Description |
 |---|---|
 | `tg me` | Show your account info |
@@ -87,6 +94,34 @@ tg logout          # remove the session
 | `tg profile --name/--bio/--photo` | Update your profile |
 | `tg alias set/list/rm` | Local chat aliases (`~/.config/tg/aliases.json`) |
 
+### Messaging & chat management (v2)
+
+| Command | Description |
+|---|---|
+| `tg schedule <chat> <time> <text...>` | Schedule a message; time is `+30m`/`+2h`/`+1d`, `2026-09-07 14:30`, or a unix ts |
+| `tg scheduled <chat>` | List scheduled messages (`--json` supported) |
+| `tg unschedule <chat> <ids...>` | Delete scheduled messages |
+| `tg draft <chat> [text]` | Save a draft (with text) or show the current draft |
+| `tg draft-clear <chat>` | Clear the draft |
+| `tg react <chat> <msg_id> <emoji>` | React to a message; `--big` for the big animation |
+| `tg unreact <chat> <msg_id>` | Remove your reaction |
+| `tg pin <chat> <msg_id>` / `tg unpin <chat> [msg_id]` | Pin / unpin (no id = unpin all) |
+| `tg read <chat>` | Mark the chat as read (also clears mention badges) |
+| `tg msg-link <chat> <msg_id>` | Export a t.me message link (channels/supergroups only) |
+| `tg contact-card <chat> "<name>" <phone>` | Send a contact card |
+| `tg sticker <chat> <file>` | Send a sticker file (`.webp` / `.tgs` / `.webm`) |
+| `tg gif <chat> <query>` | Search GIFs and send the first match; `-n N` sends the Nth |
+| `tg archive <chat>` / `tg unarchive <chat>` | Archive / unarchive a dialog |
+| `tg mute <chat> [hours]` / `tg unmute <chat>` | Mute notifications (permanent unless hours given) / unmute |
+| `tg chat-title <chat> <title>` | Change group/channel title |
+| `tg chat-about <chat> <text>` | Change chat description |
+| `tg chat-photo <chat> <file>` | Change the chat photo |
+| `tg invite-link <chat>` | Export a chat invite link |
+| `tg join <link>` | Join via `t.me/+hash`, `t.me/joinchat/…`, or `t.me/<username>` |
+| `tg clear-history <chat>` | Delete all messages (both sides; `--self-only` keeps the other copy) |
+| `tg status <user>` | Show a user's online status |
+| `tg common-chats <user>` | List chats you share with a user |
+
 Global flags: `--account` (v1: default only), `--json` (raw JSON output).
 Exit codes: `0` ok, `1` command error, `2` config/connection/session error,
 `130` interrupted.

{telegram_userbot_cli-0.1.0 → telegram_userbot_cli-0.2.0}/ROADMAP.md

@@ -4,34 +4,38 @@ The v1 release covers the core daily workflow. The goal is full coverage of
 the Telegram feature surface reachable from a userbot, roughly matching the
 126-tool scope of [chigwell/telegram-mcp](https://github.com/chigwell/telegram-mcp).
 
-Status legend: ✅ done (v1) · 🚧 planned · ❌ deliberately out of scope.
+Status legend: ✅ done · 🚧 planned · ❌ deliberately out of scope.
 
 ## Milestones
 
-### v2 — Messaging enhancements & chat management
+### v2 — Messaging enhancements & chat management (shipped)
 
 Messaging:
 
-- 🚧 `schedule <chat> <time> <text...>` — send scheduled messages
+- ✅ `schedule <chat> <time> <text...>` — send scheduled messages
   (`send_message(..., schedule=...)`), list/delete scheduled
-- 🚧 `draft <chat> [text]` / `draft-clear <chat>` — save/get/clear drafts
-- 🚧 `react <chat> <msg_id> <emoji>` / `unreact` — send/remove reactions
-- 🚧 `sticker <chat> <file.webp>` — send stickers (telethon handles via `send_file`)
-- 🚧 `gif <chat> <query>` — search GIFs and send
-- 🚧 `contact-card <chat> <name> <phone>` — send a contact card
-- 🚧 `pin <chat> <msg_id>` / `unpin <chat> [msg_id]` — pin/unpin messages
-- 🚧 `read <chat>` — mark a chat as read
-- 🚧 `msg-link <chat> <msg_id>` — export a t.me message link (channels/supergroups)
+  (`scheduled <chat>` / `unschedule <chat> <ids...>`)
+- ✅ `draft <chat> [text]` / `draft-clear <chat>` — save/get/clear drafts
+- ✅ `react <chat> <msg_id> <emoji>` / `unreact` — send/remove reactions
+  (note: reacting to Saved Messages is premium-only on Telegram's side)
+- ✅ `sticker <chat> <file.webp>` — send stickers (telethon handles via `send_file`)
+- ✅ `gif <chat> <query>` — search GIFs (inline query to the built-in @gif bot;
+  `messages.searchGifs` was removed from the TL layer) and send
+- ✅ `contact-card <chat> <name> <phone>` — send a contact card
+- ✅ `pin <chat> <msg_id>` / `unpin <chat> [msg_id]` — pin/unpin messages
+- ✅ `read <chat>` — mark a chat as read
+- ✅ `msg-link <chat> <msg_id>` — export a t.me message link (channels/supergroups)
 
 Chat management:
 
-- 🚧 `archive <chat>` / `unarchive <chat>` — archive/unarchive dialogs
-- 🚧 `mute <chat> [hours]` / `unmute <chat>` — mute/unmute notifications
-- 🚧 `chat-title <chat> <title>` / `chat-about <chat> <text>` /
+- ✅ `archive <chat>` / `unarchive <chat>` — archive/unarchive dialogs
+- ✅ `mute <chat> [hours]` / `unmute <chat>` — mute/unmute notifications
+- ✅ `chat-title <chat> <title>` / `chat-about <chat> <text>` /
   `chat-photo <chat> <file>` — edit chat info
-- 🚧 `invite-link <chat>` / `join <link>` — export/import invite links
-- 🚧 `clear-history <chat>` — delete all messages in a chat
-- 🚧 `status <user>` / `common-chats <user>` — online status, common chats
+- ✅ `invite-link <chat>` / `join <link>` — export/import invite links
+- ✅ `clear-history <chat>` — delete all messages in a chat (`--self-only` to
+  keep the other side's copy)
+- ✅ `status <user>` / `common-chats <user>` — online status, common chats
 
 ### v3 — Group administration
 

{telegram_userbot_cli-0.1.0 → telegram_userbot_cli-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "telegram-userbot-cli"
-version = "0.1.0"
+version = "0.2.0"
 description = "Full-featured Telegram command-line client powered by a Telethon userbot (your own account, not a bot token)"
 readme = "README.md"
 license = "Apache-2.0"

{telegram_userbot_cli-0.1.0 → telegram_userbot_cli-0.2.0}/src/tgcli/__init__.py

@@ -1,3 +1,3 @@
 """tgcli — standalone Telegram command-line client."""
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"

{telegram_userbot_cli-0.1.0 → telegram_userbot_cli-0.2.0}/src/tgcli/chats.py

@@ -1,5 +1,7 @@
 """Chat / search / contacts / profile commands."""
 
+from datetime import datetime
+
 from telethon import functions, types
 
 from .client import run_with_client
@@ -70,7 +72,11 @@ 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)
+    if not mute_until:
+        return False
+    # an unmuted chat sends mute_until=0, which telethon deserializes as
+    # datetime(1970, ...) — truthy but in the past, i.e. not muted
+    return mute_until > datetime.now(mute_until.tzinfo)
 
 
 async def cmd_hist(args) -> None:

{telegram_userbot_cli-0.1.0 → telegram_userbot_cli-0.2.0}/src/tgcli/cli.py

@@ -6,7 +6,7 @@ import sys
 
 from telethon import errors
 
-from . import __version__, auth, chats, media, messages, resolve
+from . import __version__, auth, chats, dialogs, media, messages, resolve
 from .output import TgError
 
 
@@ -41,7 +41,7 @@ def build_parser() -> argparse.ArgumentParser:
     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):
+    for mod in (messages, chats, media, dialogs):
         mod.setup(sub, common)
 
     resolve.setup_alias(sub, common)

telegram_userbot_cli-0.2.0/src/tgcli/dialogs.py

@@ -0,0 +1,269 @@
+"""Chat management: archive, mute, chat info, invite links, history, user status."""
+
+import os
+import re
+import time
+from datetime import datetime
+
+from telethon import functions, types
+
+from .client import run_with_client
+from .output import TgError, fmt_date, json_pp
+from .resolve import resolve_chat
+
+# "forever" mute: the official clients pin mute_until to a far-future timestamp
+_MUTE_FOREVER = 2**31 - 1
+
+
+async def _input_peer(client, chat):
+    return await client.get_input_entity(await resolve_chat(client, chat))
+
+
+async def cmd_archive(args) -> None:
+    await _set_folder(args, 1, "Archived")
+
+
+async def cmd_unarchive(args) -> None:
+    await _set_folder(args, 0, "Unarchived")
+
+
+async def _set_folder(args, folder: int, done: str) -> None:
+    async with run_with_client(args) as client:
+        entity = await resolve_chat(client, args.chat)
+        await client.edit_folder(entity, folder=folder)
+        print(done)
+
+
+async def cmd_mute(args) -> None:
+    if args.hours:
+        until = int(time.time()) + args.hours * 3600
+        human = f"muted for {args.hours}h"
+    else:
+        until = _MUTE_FOREVER
+        human = "muted permanently"
+    await _update_notify(args, until, human)
+
+
+async def cmd_unmute(args) -> None:
+    await _update_notify(args, 0, "unmuted")
+
+
+async def _update_notify(args, mute_until: int, done: str) -> None:
+    async with run_with_client(args) as client:
+        entity = await resolve_chat(client, args.chat)
+        await client(
+            functions.account.UpdateNotifySettingsRequest(
+                peer=entity,
+                settings=types.InputPeerNotifySettings(mute_until=mute_until),
+            )
+        )
+        print(done)
+
+
+async def cmd_chat_title(args) -> None:
+    async with run_with_client(args) as client:
+        peer = await _input_peer(client, args.chat)
+        if isinstance(peer, types.InputPeerChannel):
+            await client(functions.channels.EditTitleRequest(channel=peer, title=args.title))
+        elif isinstance(peer, types.InputPeerChat):
+            await client(
+                functions.messages.EditChatTitleRequest(chat_id=peer.chat_id, title=args.title)
+            )
+        else:
+            raise TgError("chat titles can only be changed for groups and channels")
+        print("Chat title updated")
+
+
+async def cmd_chat_about(args) -> None:
+    async with run_with_client(args) as client:
+        entity = await resolve_chat(client, args.chat)
+        await client(functions.messages.EditChatAboutRequest(peer=entity, about=args.text))
+        print("Chat description updated")
+
+
+async def cmd_chat_photo(args) -> None:
+    path = os.path.expanduser(args.file)
+    if not os.path.exists(path):
+        raise TgError(f"file not found: {path}")
+    async with run_with_client(args) as client:
+        peer = await _input_peer(client, args.chat)
+        uploaded = await client.upload_file(path)
+        photo = types.InputChatUploadedPhoto(file=uploaded)
+        if isinstance(peer, types.InputPeerChannel):
+            await client(functions.channels.EditPhotoRequest(channel=peer, photo=photo))
+        elif isinstance(peer, types.InputPeerChat):
+            await client(functions.messages.EditChatPhotoRequest(chat_id=peer.chat_id, photo=photo))
+        else:
+            raise TgError("chat photos can only be changed for groups and channels")
+        print("Chat photo updated")
+
+
+async def cmd_invite_link(args) -> None:
+    async with run_with_client(args) as client:
+        entity = await resolve_chat(client, args.chat)
+        res = await client(functions.messages.ExportChatInviteRequest(peer=entity))
+        link = getattr(res, "link", None)
+        if not link:
+            raise TgError("no invite link returned (check your admin rights)")
+        print(link)
+
+
+def _invite_hash(link: str) -> str | None:
+    m = re.search(r"t\.me/(?:\+|joinchat/)([A-Za-z0-9_-]+)", link)
+    return m.group(1) if m else None
+
+
+def _invite_username(link: str) -> str | None:
+    m = re.search(r"t\.me/([A-Za-z0-9_]{4,})", link)
+    return m.group(1) if m else link.lstrip("@")
+
+
+async def cmd_join(args) -> None:
+    async with run_with_client(args) as client:
+        h = _invite_hash(args.link)
+        if h:
+            await client(functions.messages.ImportChatInviteRequest(hash=h))
+            print("Joined private group")
+            return
+        name = _invite_username(args.link)
+        await client(functions.channels.JoinChannelRequest(channel=name))
+        print(f"Joined @{name}")
+
+
+async def cmd_clear_history(args) -> None:
+    async with run_with_client(args) as client:
+        peer = await client.get_input_entity(await resolve_chat(client, args.chat))
+        if isinstance(peer, types.InputPeerChannel):
+            # supergroups/channels reject messages.DeleteHistoryRequest
+            await client(
+                functions.channels.DeleteHistoryRequest(
+                    channel=peer, max_id=0, for_everyone=not args.self_only
+                )
+            )
+        else:
+            await client(
+                functions.messages.DeleteHistoryRequest(
+                    peer=peer,
+                    max_id=0,
+                    revoke=not args.self_only,
+                )
+            )
+        scope = "for both sides" if not args.self_only else "locally only"
+        print(f"History cleared ({scope})")
+
+
+def _status_text(status) -> str:
+    if isinstance(status, types.UserStatusOnline):
+        if status.expires > datetime.now(status.expires.tzinfo):
+            return "online"
+        return f"last seen {fmt_date(status.expires)}"
+    if isinstance(status, types.UserStatusOffline):
+        return f"last seen {fmt_date(status.was_online)}"
+    if isinstance(status, types.UserStatusRecently):
+        return "last seen recently"
+    if isinstance(status, types.UserStatusLastWeek):
+        return "last seen within a week"
+    if isinstance(status, types.UserStatusLastMonth):
+        return "last seen within a month"
+    if isinstance(status, types.UserStatusLongAgo):
+        return "last seen a long time ago"
+    return str(status)
+
+
+async def cmd_status(args) -> None:
+    async with run_with_client(args) as client:
+        user = await client.get_entity(await resolve_chat(client, args.user))
+        name = " ".join(x for x in (user.first_name, user.last_name) if x)
+        print(f"{name} ({user.id}): {_status_text(user.status)}")
+
+
+async def cmd_common_chats(args) -> None:
+    async with run_with_client(args) as client:
+        peer = await _input_peer(client, args.user)
+        if isinstance(peer, types.InputPeerSelf):
+            raise TgError("cannot list common chats with yourself")
+        if not isinstance(peer, types.InputPeerUser):
+            raise TgError(f"'{args.user}' is not a user")
+        user = types.InputUser(user_id=peer.user_id, access_hash=peer.access_hash)
+        res = await client(
+            functions.messages.GetCommonChatsRequest(user_id=user, max_id=0, limit=100)
+        )
+        chats = getattr(res, "chats", []) or []
+        if args.json:
+            print(json_pp([c.to_dict() for c in chats]))
+            return
+        if not chats:
+            print("(no common chats)")
+            return
+        for c in chats:
+            title = getattr(c, "title", None) or "?"
+            uname = getattr(c, "username", None) or ""
+            print(f"{c.id:>14}  {title}  {'@' + uname if uname else ''}")
+
+
+def setup(subparsers, common=None) -> None:
+    parents = [common] if common else []
+    sp = subparsers.add_parser("archive", parents=parents, help="Archive a chat")
+    sp.add_argument("chat")
+    sp.set_defaults(func=cmd_archive)
+
+    sp = subparsers.add_parser("unarchive", parents=parents, help="Unarchive a chat")
+    sp.add_argument("chat")
+    sp.set_defaults(func=cmd_unarchive)
+
+    sp = subparsers.add_parser(
+        "mute", parents=parents, help="Mute notifications (permanent unless [hours] given)"
+    )
+    sp.add_argument("chat")
+    sp.add_argument("hours", nargs="?", type=int, default=None)
+    sp.set_defaults(func=cmd_mute)
+
+    sp = subparsers.add_parser("unmute", parents=parents, help="Unmute notifications")
+    sp.add_argument("chat")
+    sp.set_defaults(func=cmd_unmute)
+
+    sp = subparsers.add_parser("chat-title", parents=parents, help="Change group/channel title")
+    sp.add_argument("chat")
+    sp.add_argument("title")
+    sp.set_defaults(func=cmd_chat_title)
+
+    sp = subparsers.add_parser("chat-about", parents=parents, help="Change chat description")
+    sp.add_argument("chat")
+    sp.add_argument("text")
+    sp.set_defaults(func=cmd_chat_about)
+
+    sp = subparsers.add_parser("chat-photo", parents=parents, help="Change the chat photo")
+    sp.add_argument("chat")
+    sp.add_argument("file", help="path to an image")
+    sp.set_defaults(func=cmd_chat_photo)
+
+    sp = subparsers.add_parser("invite-link", parents=parents, help="Export a chat invite link")
+    sp.add_argument("chat")
+    sp.set_defaults(func=cmd_invite_link)
+
+    sp = subparsers.add_parser(
+        "join", parents=parents, help="Join via t.me link, @username, or invite hash"
+    )
+    sp.add_argument("link", help="e.g. t.me/+abc123, t.me/joinchat/abc123, or t.me/somechannel")
+    sp.set_defaults(func=cmd_join)
+
+    sp = subparsers.add_parser(
+        "clear-history",
+        parents=parents,
+        help="Delete all messages in a chat (both sides; --self-only keeps the other copy)",
+    )
+    sp.add_argument("chat")
+    sp.add_argument(
+        "--self-only", action="store_true", help="delete only your own copy (private chats)"
+    )
+    sp.set_defaults(func=cmd_clear_history)
+
+    sp = subparsers.add_parser("status", parents=parents, help="Show a user's online status")
+    sp.add_argument("user")
+    sp.set_defaults(func=cmd_status)
+
+    sp = subparsers.add_parser(
+        "common-chats", parents=parents, help="List chats you share with a user"
+    )
+    sp.add_argument("user")
+    sp.set_defaults(func=cmd_common_chats)

{telegram_userbot_cli-0.1.0 → telegram_userbot_cli-0.2.0}/src/tgcli/media.py

@@ -1,8 +1,10 @@
-"""Media commands: dl (download), sf (send file/album), voice."""
+"""Media commands: dl (download), sf (send file/album), voice, sticker, gif."""
 
 import os
 import re
 
+from telethon import functions
+
 from .client import run_with_client
 from .output import TgError
 from .resolve import resolve_chat
@@ -62,6 +64,34 @@ async def cmd_voice(args) -> None:
         print("Voice note sent")
 
 
+async def cmd_sticker(args) -> None:
+    path = os.path.expanduser(args.file)
+    if not os.path.exists(path):
+        raise TgError(f"file not found: {path}")
+    async with run_with_client(args) as client:
+        entity = await resolve_chat(client, args.chat)
+        await client.send_file(entity, path, force_document=False)
+        print("Sticker sent")
+
+
+async def cmd_gif(args) -> None:
+    async with run_with_client(args) as client:
+        entity = await resolve_chat(client, args.chat)
+        # GIF search = inline query to the built-in @gif bot (searchGifs was
+        # removed from the TL layer; this is what official clients use)
+        res = await client(
+            functions.messages.GetInlineBotResultsRequest(
+                bot="gif", peer=entity, query=args.query, offset=""
+            )
+        )
+        docs = [r.document for r in res.results if getattr(r, "document", None) is not None]
+        if not docs:
+            raise TgError(f"no GIFs found for {args.query!r}")
+        idx = min(max(args.index, 1), len(docs)) - 1
+        await client.send_file(entity, docs[idx])
+        print(f"GIF sent (match {idx + 1} of {len(docs)} for {args.query!r})")
+
+
 def setup(subparsers, common=None) -> None:
     parents = [common] if common else []
     sp = subparsers.add_parser(
@@ -89,3 +119,16 @@ def setup(subparsers, common=None) -> None:
     sp.add_argument("chat")
     sp.add_argument("file")
     sp.set_defaults(func=cmd_voice)
+
+    sp = subparsers.add_parser(
+        "sticker", parents=parents, help="Send a sticker file (.webp / .tgs / .webm)"
+    )
+    sp.add_argument("chat")
+    sp.add_argument("file")
+    sp.set_defaults(func=cmd_sticker)
+
+    sp = subparsers.add_parser("gif", parents=parents, help="Search GIFs and send the first match")
+    sp.add_argument("chat")
+    sp.add_argument("query")
+    sp.add_argument("-n", "--index", type=int, default=1, help="send the Nth match (default 1)")
+    sp.set_defaults(func=cmd_gif)

telegram_userbot_cli-0.2.0/src/tgcli/messages.py

@@ -0,0 +1,365 @@
+"""Messaging commands: send, reply, edit, del, fwd, poll, schedule, draft,
+reactions, pinning, read state, message links, contact cards."""
+
+import random
+import re
+from datetime import datetime, timedelta
+
+from telethon import functions, types
+
+from .client import run_with_client
+from .output import TgError, fmt_date, json_pp
+from .resolve import resolve_chat
+
+_UNIT_SECONDS = {"s": 1, "m": 60, "h": 3600, "d": 86400}
+
+
+def parse_when(spec: str) -> datetime:
+    """Parse a schedule time: relative (+30m/+2h/+1d), unix ts, or ISO date."""
+    s = spec.strip()
+    m = re.fullmatch(r"\+(\d+)([smhd])", s.lower())
+    if m:
+        return datetime.now().astimezone() + timedelta(
+            seconds=int(m.group(1)) * _UNIT_SECONDS[m.group(2)]
+        )
+    if re.fullmatch(r"\d{9,12}", s):
+        return datetime.fromtimestamp(int(s)).astimezone()
+    try:
+        dt = datetime.fromisoformat(s)
+    except ValueError:
+        pass
+    else:
+        return dt.astimezone() if dt.tzinfo is None else dt
+    raise TgError(
+        f"cannot parse time: {spec!r}",
+        'use "+30m" / "+2h", "2026-09-07 14:30", or a unix timestamp',
+    )
+
+
+async def cmd_send(args) -> None:
+    async with run_with_client(args) as client:
+        entity = await resolve_chat(client, args.chat)
+        msg = await client.send_message(entity, " ".join(args.text), parse_mode=args.parse_mode)
+        print(f"Message sent (id: {msg.id})")
+
+
+async def cmd_reply(args) -> None:
+    async with run_with_client(args) as client:
+        entity = await resolve_chat(client, args.chat)
+        msg = await client.send_message(entity, " ".join(args.text), reply_to=args.msg_id)
+        print(f"Reply sent (id: {msg.id})")
+
+
+async def cmd_edit(args) -> None:
+    async with run_with_client(args) as client:
+        entity = await resolve_chat(client, args.chat)
+        await client.edit_message(entity, args.msg_id, args.new_text)
+        print("Message edited")
+
+
+async def cmd_del(args) -> None:
+    async with run_with_client(args) as client:
+        entity = await resolve_chat(client, args.chat)
+        await client.delete_messages(entity, args.ids, revoke=True)
+        print(f"Deleted {len(args.ids)} message(s)")
+
+
+async def cmd_fwd(args) -> None:
+    async with run_with_client(args) as client:
+        from_entity = await resolve_chat(client, args.from_chat)
+        to_entity = await resolve_chat(client, args.to)
+        sent = await client.forward_messages(to_entity, args.msg_ids, from_peer=from_entity)
+        print(f"Forwarded {len(sent)} message(s)")
+
+
+async def cmd_poll(args) -> None:
+    if len(args.options) < 2:
+        raise TgError("a poll needs at least 2 options")
+    async with run_with_client(args) as client:
+        entity = await resolve_chat(client, args.chat)
+        answers = [
+            types.PollAnswer(
+                text=types.TextWithEntities(text=a, entities=[]),
+                option=bytes([i]),
+            )
+            for i, a in enumerate(args.options)
+        ]
+        poll = types.Poll(
+            id=random.randint(1, 2**31),
+            question=types.TextWithEntities(text=args.question, entities=[]),
+            answers=answers,
+            hash=0,
+            closed=False,
+            public_voters=args.public,
+            quiz=args.quiz,
+            multiple_choice=args.multiple,
+        )
+        msg = await client.send_message(entity, file=types.InputMediaPoll(poll=poll))
+        print(f"Poll sent (id: {msg.id})")
+
+
+async def cmd_schedule(args) -> None:
+    when = parse_when(args.time)
+    if when <= datetime.now().astimezone():
+        raise TgError("schedule time must be in the future")
+    async with run_with_client(args) as client:
+        entity = await resolve_chat(client, args.chat)
+        msg = await client.send_message(entity, " ".join(args.text), schedule=when)
+        print(f"Scheduled (id: {msg.id}) for {fmt_date(when)}")
+
+
+async def cmd_scheduled(args) -> None:
+    async with run_with_client(args) as client:
+        entity = await resolve_chat(client, args.chat)
+        res = await client(functions.messages.GetScheduledHistoryRequest(peer=entity, hash=0))
+        msgs = getattr(res, "messages", []) or []
+        if not msgs:
+            print("(no scheduled messages)")
+            return
+        if args.json:
+            print(json_pp([m.to_dict() for m in msgs]))
+            return
+        for m in msgs:
+            body = " ".join((m.message or "").split())[:100] or "[media]"
+            print(f"[{m.id}] {fmt_date(m.date)}  {body}")
+
+
+async def cmd_unschedule(args) -> None:
+    async with run_with_client(args) as client:
+        entity = await resolve_chat(client, args.chat)
+        await client(functions.messages.DeleteScheduledMessagesRequest(peer=entity, id=args.ids))
+        print(f"Unscheduled {len(args.ids)} message(s)")
+
+
+async def cmd_draft(args) -> None:
+    async with run_with_client(args) as client:
+        entity = await resolve_chat(client, args.chat)
+        if args.text:
+            text = " ".join(args.text)
+            await client(functions.messages.SaveDraftRequest(peer=entity, message=text))
+            print("Draft saved")
+            return
+        text = ""
+        async for d in client.iter_drafts(entity):
+            text = d.raw_text or ""
+            break
+        print(text if text else "(no draft)")
+
+
+async def cmd_draft_clear(args) -> None:
+    async with run_with_client(args) as client:
+        entity = await resolve_chat(client, args.chat)
+        # an empty message clears the draft
+        await client(functions.messages.SaveDraftRequest(peer=entity, message=""))
+        print("Draft cleared")
+
+
+async def cmd_react(args) -> None:
+    async with run_with_client(args) as client:
+        entity = await resolve_chat(client, args.chat)
+        await client(
+            functions.messages.SendReactionRequest(
+                peer=entity,
+                msg_id=args.msg_id,
+                big=args.big,
+                reaction=[types.ReactionEmoji(emoticon=args.emoji)],
+            )
+        )
+        print(f"Reacted {args.emoji} to message {args.msg_id}")
+
+
+async def cmd_unreact(args) -> None:
+    async with run_with_client(args) as client:
+        entity = await resolve_chat(client, args.chat)
+        # an empty reaction list removes our reaction
+        await client(
+            functions.messages.SendReactionRequest(peer=entity, msg_id=args.msg_id, reaction=[])
+        )
+        print(f"Reaction removed from message {args.msg_id}")
+
+
+async def cmd_pin(args) -> None:
+    async with run_with_client(args) as client:
+        entity = await resolve_chat(client, args.chat)
+        await client.pin_message(entity, args.msg_id)
+        print(f"Pinned message {args.msg_id}")
+
+
+async def cmd_unpin(args) -> None:
+    async with run_with_client(args) as client:
+        entity = await resolve_chat(client, args.chat)
+        if args.msg_id is None:
+            await client.unpin_message(entity)
+            print("Unpinned all messages")
+        else:
+            await client.unpin_message(entity, args.msg_id)
+            print(f"Unpinned message {args.msg_id}")
+
+
+async def cmd_read(args) -> None:
+    async with run_with_client(args) as client:
+        entity = await resolve_chat(client, args.chat)
+        await client.send_read_acknowledge(entity, clear_mentions=True)
+        print("Marked as read")
+
+
+async def cmd_msg_link(args) -> None:
+    async with run_with_client(args) as client:
+        peer = await client.get_input_entity(await resolve_chat(client, args.chat))
+        if not isinstance(peer, types.InputPeerChannel):
+            raise TgError(
+                "message links only exist for channels and supergroups",
+                "basic groups and private chats have no t.me message links",
+            )
+        res = await client(
+            functions.channels.ExportMessageLinkRequest(
+                channel=types.InputChannel(
+                    channel_id=peer.channel_id, access_hash=peer.access_hash
+                ),
+                id=args.msg_id,
+            )
+        )
+        print(res.link)
+
+
+async def cmd_contact_card(args) -> None:
+    first, _, last = args.name.partition(" ")
+    async with run_with_client(args) as client:
+        entity = await resolve_chat(client, args.chat)
+        msg = await client.send_message(
+            entity,
+            file=types.InputMediaContact(
+                phone_number=args.phone, first_name=first, last_name=last, vcard=""
+            ),
+        )
+        print(f"Contact card sent (id: {msg.id})")
+
+
+def setup(subparsers, common=None) -> None:
+    parents = [common] if common else []
+    sp = subparsers.add_parser(
+        "send", parents=parents, help="Send a message, e.g. tg send me hello"
+    )
+    sp.add_argument("chat")
+    sp.add_argument("text", nargs="+")
+    sp.add_argument("-p", "--parse-mode", default=None, choices=["md", "markdown", "html"])
+    sp.set_defaults(func=cmd_send)
+
+    sp = subparsers.add_parser(
+        "reply", parents=parents, help="Reply to a message, e.g. tg reply me 12 got it"
+    )
+    sp.add_argument("chat")
+    sp.add_argument("msg_id", type=int)
+    sp.add_argument("text", nargs="+")
+    sp.set_defaults(func=cmd_reply)
+
+    sp = subparsers.add_parser("edit", parents=parents, help="Edit your own message")
+    sp.add_argument("chat")
+    sp.add_argument("msg_id", type=int)
+    sp.add_argument("new_text")
+    sp.set_defaults(func=cmd_edit)
+
+    sp = subparsers.add_parser(
+        "del", parents=parents, help="Delete messages (revoke for both sides)"
+    )
+    sp.add_argument("chat")
+    sp.add_argument("ids", nargs="+", type=int)
+    sp.set_defaults(func=cmd_del)
+
+    sp = subparsers.add_parser(
+        "fwd", parents=parents, help="Forward messages, e.g. tg fwd SRC 1 2 3 DST (last is target)"
+    )
+    sp.add_argument("from_chat")
+    sp.add_argument("msg_ids", nargs="+", type=int)
+    sp.add_argument("to")
+    sp.set_defaults(func=cmd_fwd)
+
+    sp = subparsers.add_parser(
+        "poll", parents=parents, help='Create a poll, e.g. tg poll me "Q?" a b c'
+    )
+    sp.add_argument("chat")
+    sp.add_argument("question")
+    sp.add_argument("options", nargs="+")
+    sp.add_argument("--multiple", action="store_true", help="allow multiple answers")
+    sp.add_argument("--quiz", action="store_true", help="quiz mode")
+    sp.add_argument("--public", action="store_true", help="public votes")
+    sp.set_defaults(func=cmd_poll)
+
+    sp = subparsers.add_parser(
+        "schedule",
+        parents=parents,
+        help='Schedule a message, e.g. tg schedule me "+2h" ping',
+    )
+    sp.add_argument("chat")
+    sp.add_argument("time", help='+30m / +2h / +1d, "2026-09-07 14:30", or a unix timestamp')
+    sp.add_argument("text", nargs="+")
+    sp.set_defaults(func=cmd_schedule)
+
+    sp = subparsers.add_parser("scheduled", parents=parents, help="List scheduled messages")
+    sp.add_argument("chat")
+    sp.set_defaults(func=cmd_scheduled)
+
+    sp = subparsers.add_parser(
+        "unschedule", parents=parents, help="Delete scheduled messages (ids from `scheduled`)"
+    )
+    sp.add_argument("chat")
+    sp.add_argument("ids", nargs="+", type=int)
+    sp.set_defaults(func=cmd_unschedule)
+
+    sp = subparsers.add_parser(
+        "draft",
+        parents=parents,
+        help="Save a draft (with text) or show the current draft (without)",
+    )
+    sp.add_argument("chat")
+    sp.add_argument("text", nargs="*", default=[])
+    sp.set_defaults(func=cmd_draft)
+
+    sp = subparsers.add_parser("draft-clear", parents=parents, help="Clear the draft")
+    sp.add_argument("chat")
+    sp.set_defaults(func=cmd_draft_clear)
+
+    sp = subparsers.add_parser("react", parents=parents, help="React to a message")
+    sp.add_argument("chat")
+    sp.add_argument("msg_id", type=int)
+    sp.add_argument("emoji", help='e.g. "👍", "❤️", "🎉"')
+    sp.add_argument("--big", action="store_true", help="big animation")
+    sp.set_defaults(func=cmd_react)
+
+    sp = subparsers.add_parser("unreact", parents=parents, help="Remove your reaction")
+    sp.add_argument("chat")
+    sp.add_argument("msg_id", type=int)
+    sp.set_defaults(func=cmd_unreact)
+
+    sp = subparsers.add_parser("pin", parents=parents, help="Pin a message")
+    sp.add_argument("chat")
+    sp.add_argument("msg_id", type=int)
+    sp.set_defaults(func=cmd_pin)
+
+    sp = subparsers.add_parser(
+        "unpin", parents=parents, help="Unpin a message (or all if no id given)"
+    )
+    sp.add_argument("chat")
+    sp.add_argument("msg_id", nargs="?", type=int, default=None)
+    sp.set_defaults(func=cmd_unpin)
+
+    sp = subparsers.add_parser("read", parents=parents, help="Mark the chat as read")
+    sp.add_argument("chat")
+    sp.set_defaults(func=cmd_read)
+
+    sp = subparsers.add_parser(
+        "msg-link", parents=parents, help="Export a t.me link (channels/supergroups)"
+    )
+    sp.add_argument("chat")
+    sp.add_argument("msg_id", type=int)
+    sp.set_defaults(func=cmd_msg_link)
+
+    sp = subparsers.add_parser(
+        "contact-card",
+        parents=parents,
+        help='Send a contact card, e.g. tg contact-card me "Jo Do" +8613800000000',
+    )
+    sp.add_argument("chat")
+    sp.add_argument("name", help='contact name, e.g. "John Doe"')
+    sp.add_argument("phone")
+    sp.set_defaults(func=cmd_contact_card)

telegram_userbot_cli-0.1.0/src/tgcli/messages.py

@@ -1,122 +0,0 @@
-"""Messaging commands: send, reply, edit, del, fwd, poll."""
-
-import random
-
-from telethon import types
-
-from .client import run_with_client
-from .output import TgError
-from .resolve import resolve_chat
-
-
-async def cmd_send(args) -> None:
-    async with run_with_client(args) as client:
-        entity = await resolve_chat(client, args.chat)
-        msg = await client.send_message(entity, " ".join(args.text), parse_mode=args.parse_mode)
-        print(f"Message sent (id: {msg.id})")
-
-
-async def cmd_reply(args) -> None:
-    async with run_with_client(args) as client:
-        entity = await resolve_chat(client, args.chat)
-        msg = await client.send_message(entity, " ".join(args.text), reply_to=args.msg_id)
-        print(f"Reply sent (id: {msg.id})")
-
-
-async def cmd_edit(args) -> None:
-    async with run_with_client(args) as client:
-        entity = await resolve_chat(client, args.chat)
-        await client.edit_message(entity, args.msg_id, args.new_text)
-        print("Message edited")
-
-
-async def cmd_del(args) -> None:
-    async with run_with_client(args) as client:
-        entity = await resolve_chat(client, args.chat)
-        await client.delete_messages(entity, args.ids, revoke=True)
-        print(f"Deleted {len(args.ids)} message(s)")
-
-
-async def cmd_fwd(args) -> None:
-    async with run_with_client(args) as client:
-        from_entity = await resolve_chat(client, args.from_chat)
-        to_entity = await resolve_chat(client, args.to)
-        sent = await client.forward_messages(to_entity, args.msg_ids, from_peer=from_entity)
-        print(f"Forwarded {len(sent)} message(s)")
-
-
-async def cmd_poll(args) -> None:
-    if len(args.options) < 2:
-        raise TgError("a poll needs at least 2 options")
-    async with run_with_client(args) as client:
-        entity = await resolve_chat(client, args.chat)
-        answers = [
-            types.PollAnswer(
-                text=types.TextWithEntities(text=a, entities=[]),
-                option=bytes([i]),
-            )
-            for i, a in enumerate(args.options)
-        ]
-        poll = types.Poll(
-            id=random.randint(1, 2**31),
-            question=types.TextWithEntities(text=args.question, entities=[]),
-            answers=answers,
-            hash=0,
-            closed=False,
-            public_voters=args.public,
-            quiz=args.quiz,
-            multiple_choice=args.multiple,
-        )
-        msg = await client.send_message(entity, file=types.InputMediaPoll(poll=poll))
-        print(f"Poll sent (id: {msg.id})")
-
-
-def setup(subparsers, common=None) -> None:
-    parents = [common] if common else []
-    sp = subparsers.add_parser(
-        "send", parents=parents, help="Send a message, e.g. tg send me hello"
-    )
-    sp.add_argument("chat")
-    sp.add_argument("text", nargs="+")
-    sp.add_argument("-p", "--parse-mode", default=None, choices=["md", "markdown", "html"])
-    sp.set_defaults(func=cmd_send)
-
-    sp = subparsers.add_parser(
-        "reply", parents=parents, help="Reply to a message, e.g. tg reply me 12 got it"
-    )
-    sp.add_argument("chat")
-    sp.add_argument("msg_id", type=int)
-    sp.add_argument("text", nargs="+")
-    sp.set_defaults(func=cmd_reply)
-
-    sp = subparsers.add_parser("edit", parents=parents, help="Edit your own message")
-    sp.add_argument("chat")
-    sp.add_argument("msg_id", type=int)
-    sp.add_argument("new_text")
-    sp.set_defaults(func=cmd_edit)
-
-    sp = subparsers.add_parser(
-        "del", parents=parents, help="Delete messages (revoke for both sides)"
-    )
-    sp.add_argument("chat")
-    sp.add_argument("ids", nargs="+", type=int)
-    sp.set_defaults(func=cmd_del)
-
-    sp = subparsers.add_parser(
-        "fwd", parents=parents, help="Forward messages, e.g. tg fwd SRC 1 2 3 DST (last is target)"
-    )
-    sp.add_argument("from_chat")
-    sp.add_argument("msg_ids", nargs="+", type=int)
-    sp.add_argument("to")
-    sp.set_defaults(func=cmd_fwd)
-
-    sp = subparsers.add_parser(
-        "poll", parents=parents, help='Create a poll, e.g. tg poll me "Q?" a b c'
-    )
-    sp.add_argument("chat")
-    sp.add_argument("question")
-    sp.add_argument("options", nargs="+")
-    sp.add_argument("--multiple", action="store_true", help="allow multiple answers")
-    sp.add_argument("--quiz", action="store_true", help="quiz mode")
-    sp.add_argument("--public", action="store_true", help="public votes")
-    sp.set_defaults(func=cmd_poll)