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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: telegram-userbot-cli
-Version: 0.1.0
+Version: 0.3.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,16 @@ 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
+- Group administration: create groups/channels, invite / kick / ban,
+  admin promotion with granular rights, slow mode, forum topics, admin log
+- 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 +86,8 @@ tg logout          # remove the session
 
 ## Commands
 
+### Core
+
 | Command | Description |
 |---|---|
 | `tg me` | Show your account info |
@@ -100,6 +109,55 @@ 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 |
+
+### Group administration (v3)
+
+| Command | Description |
+|---|---|
+| `tg new-group <title> <user...>` | Create a basic group with initial members |
+| `tg new-channel <title> [--about text]` | Create a channel; `--group` creates a supergroup |
+| `tg invite <chat> <user...>` | Invite users (supergroups & basic groups) |
+| `tg kick <chat> <user...>` | Remove users (supergroup kick = view-messages ban; `unban` to reverse) |
+| `tg leave <chat>` | Leave a group/channel |
+| `tg ban <chat> <user> [days]` | Ban a user (permanent unless days given); supergroups only |
+| `tg unban <chat> <user>` | Unban a user |
+| `tg banned <chat>` | List banned users (`--json` supported) |
+| `tg admins <chat>` | List admins with ranks |
+| `tg promote <chat> <user> [--title rank]` | Promote with the standard right set |
+| `tg demote <chat> <user>` | Remove admin rights |
+| `tg admin-rights <chat> <user> <flags...>` | Set exact rights: `--change-info --post-messages --edit-messages --delete-messages --ban-users --invite-users --pin-messages --add-admins --anonymous --manage-call --other --manage-topics …`; `--rank` |
+| `tg slow-mode <chat> [seconds]` | Set slow mode (0 = disable); supergroups only |
+| `tg topics <chat>` | List forum topics |
+| `tg topic-create <chat> <title> [text]` | Create a forum topic, optionally with a first message |
+| `tg admin-log <chat> [-n]` | Recent admin actions |
+
 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.3.0}/README-zh.md

@@ -12,9 +12,11 @@
 ## 特性
 
 - 扫码登录（`tg login --qr`），使用独立会话
-- 消息：发送 / 引用回复 / 编辑 / 删除 / 转发 / 投票
-- 聊天：会话列表、历史记录、置顶消息、会话内搜索与全局搜索
-- 媒体：下载、发文件 / 相册、语音条
+- 消息：发送 / 引用回复 / 编辑 / 删除 / 转发 / 投票 / 定时 / 草稿 / 表情回应 / 置顶
+- 群组管理：建群 / 建频道、邀请 / 踢人 / 封禁、管理员升降级（细粒度权限）、慢速模式、论坛话题、管理日志
+- 聊天管理：归档、免打扰、修改群名 / 简介 / 群头像、邀请链接、清空历史
+- 媒体：下载、发文件 / 相册 / 语音条 / 贴纸 / GIF、发送名片
+- 聊天：会话列表、历史记录、置顶消息、会话内与全局搜索、在线状态、共同群组
 - 联系人与个人资料管理
 - 会话解析：名称模糊匹配、`@username`、数字 id、`me`（已保存消息），以及本地别名
 
@@ -62,6 +64,8 @@ tg logout          # 退出登录并删除会话
 
 ## 命令
 
+### 基础
+
 | 命令 | 说明 |
 |---|---|
 | `tg me` | 查看自己的账号信息 |
@@ -83,6 +87,55 @@ 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 <用户>` | 列出与该用户的共同群组 |
+
+### 群组管理（v3）
+
+| 命令 | 说明 |
+|---|---|
+| `tg new-group <标题> <用户...>` | 建基本群并拉入初始成员 |
+| `tg new-channel <标题> [--about 简介]` | 建频道；`--group` 建超级群组 |
+| `tg invite <会话> <用户...>` | 邀请用户（超级群组与基本群都支持） |
+| `tg kick <会话> <用户...>` | 移出用户（超级群组的踢人 = 禁言封禁，`unban` 可恢复） |
+| `tg leave <会话>` | 退出群组/频道 |
+| `tg ban <会话> <用户> [天数]` | 封禁（不带天数 = 永久）；仅超级群组 |
+| `tg unban <会话> <用户>` | 解除封禁 |
+| `tg banned <会话>` | 封禁名单（支持 `--json`） |
+| `tg admins <会话>` | 管理员列表（含头衔） |
+| `tg promote <会话> <用户> [--title 头衔]` | 升级为管理员（标准权限集） |
+| `tg demote <会话> <用户>` | 撤销管理员 |
+| `tg admin-rights <会话> <用户> <权限...>` | 设置精确权限：`--change-info --post-messages --edit-messages --delete-messages --ban-users --invite-users --pin-messages --add-admins --anonymous --manage-call --other --manage-topics …`；`--rank` 定头衔 |
+| `tg slow-mode <会话> [秒]` | 设置慢速模式（0 = 关闭）；仅超级群组 |
+| `tg topics <会话>` | 列出论坛话题 |
+| `tg topic-create <会话> <标题> [首条消息]` | 创建论坛话题 |
+| `tg admin-log <会话> [-n]` | 近期管理操作日志 |
+
 全局选项：`--account`（v1 仅 default）、`--json`（原始 JSON 输出）。
 退出码：`0` 成功、`1` 命令错误、`2` 配置/连接/会话错误、`130` 中断。
 

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

@@ -12,9 +12,16 @@ 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
+- Group administration: create groups/channels, invite / kick / ban,
+  admin promotion with granular rights, slow mode, forum topics, admin log
+- 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 +73,8 @@ tg logout          # remove the session
 
 ## Commands
 
+### Core
+
 | Command | Description |
 |---|---|
 | `tg me` | Show your account info |
@@ -87,6 +96,55 @@ 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 |
+
+### Group administration (v3)
+
+| Command | Description |
+|---|---|
+| `tg new-group <title> <user...>` | Create a basic group with initial members |
+| `tg new-channel <title> [--about text]` | Create a channel; `--group` creates a supergroup |
+| `tg invite <chat> <user...>` | Invite users (supergroups & basic groups) |
+| `tg kick <chat> <user...>` | Remove users (supergroup kick = view-messages ban; `unban` to reverse) |
+| `tg leave <chat>` | Leave a group/channel |
+| `tg ban <chat> <user> [days]` | Ban a user (permanent unless days given); supergroups only |
+| `tg unban <chat> <user>` | Unban a user |
+| `tg banned <chat>` | List banned users (`--json` supported) |
+| `tg admins <chat>` | List admins with ranks |
+| `tg promote <chat> <user> [--title rank]` | Promote with the standard right set |
+| `tg demote <chat> <user>` | Remove admin rights |
+| `tg admin-rights <chat> <user> <flags...>` | Set exact rights: `--change-info --post-messages --edit-messages --delete-messages --ban-users --invite-users --pin-messages --add-admins --anonymous --manage-call --other --manage-topics …`; `--rank` |
+| `tg slow-mode <chat> [seconds]` | Set slow mode (0 = disable); supergroups only |
+| `tg topics <chat>` | List forum topics |
+| `tg topic-create <chat> <title> [text]` | Create a forum topic, optionally with a first message |
+| `tg admin-log <chat> [-n]` | Recent admin actions |
+
 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.3.0/ROADMAP.md

@@ -0,0 +1,75 @@
+# Roadmap
+
+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 · 🚧 planned · ❌ deliberately out of scope.
+
+## Milestones
+
+### v2 — Messaging enhancements & chat management (shipped)
+
+Messaging:
+
+- ✅ `schedule <chat> <time> <text...>` — send scheduled messages
+  (`send_message(..., schedule=...)`), list/delete scheduled
+  (`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>` /
+  `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 (`--self-only` to
+  keep the other side's copy)
+- ✅ `status <user>` / `common-chats <user>` — online status, common chats
+
+### v3 — Group administration (shipped)
+
+- ✅ `new-group <title> <user...>` / `new-channel <title>` — create groups
+  (`--group` flag makes a supergroup) /channels
+- ✅ `invite <chat> <user...>` / `kick <chat> <user...>` / `leave <chat>`
+  (basic-group kick/leave use `messages.DeleteChatUser`, supergroup kick is a
+  view-messages ban like official clients)
+- ✅ `ban <chat> <user> [days]` / `unban <chat> <user>` / `banned <chat>`
+  (the working participant filter on the current TL layer is
+  `ChannelParticipantsKicked`, not `ChannelParticipantsBanned`)
+- ✅ `admins <chat>` / `promote <chat> <user> [--title]` / `demote <chat> <user>` /
+  `admin-rights <chat> <user> ...` — admin management with granular rights
+  (basic groups use `messages.EditChatAdmin`, no titles)
+- ✅ `slow-mode <chat> [seconds]` — set/disable slow mode
+- ✅ `topics <chat>` / `topic-create <chat> <title> [text]` — forum topics
+  (list/create)
+- ✅ `admin-log <chat>` — recent admin actions
+
+### v4 — Contacts, profile & misc
+
+- 🚧 `contact add/del` — add/delete contacts
+- 🚧 `contact import <file>` / `contact export` — bulk import/export
+- 🚧 `photo-del` — delete profile photo
+- 🚧 `privacy get/set` — privacy settings (last seen, phone, …)
+- 🚧 `block <user>` / `unblock <user>` / `blocked` — block management
+- 🚧 `folder ...` — dialog folders (create/assign/reorder)
+- 🚧 `accounts` — multi-account support (the `--account` hook already exists;
+  v1 resolves the default account only)
+- 🚧 `vtr <chat> <msg_id>` — voice transcription. telethon 1.44 has no
+  transcribe support; options: Groq HTTP API, or raw
+  `messages.transcribeAudio` TL (Telegram Premium)
+
+### Out of scope
+
+- ❌ Agent-oriented event tools (`wait_for_settled_message`, incoming feed
+  watchers) — meaningless for an interactive CLI.

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "telegram-userbot-cli"
-version = "0.1.0"
+version = "0.3.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.3.0}/src/tgcli/__init__.py

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

{telegram_userbot_cli-0.1.0 → telegram_userbot_cli-0.3.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.3.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, groups, 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, groups):
         mod.setup(sub, common)
 
     resolve.setup_alias(sub, common)

telegram_userbot_cli-0.3.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)