先看清数据边界，
再敲下命令。

01 · Start

快速开始

先完成一次交互式认证，再选择聊天同步到本地。之后，本地搜索不需要连接 Telegram。

npm install -g @will-17173/telegram-cli
tg --version

tg account add
tg status
tg whoami

tg chats --account work --json
tg chats --type channel --account work --json

tg sync @team --account work --json
tg search "release" --chat @team --account work --json

02 · Model

执行模型：命令到底运行在哪里

“读取”不等于“保存”，“写到本地”也不等于“修改 Telegram”。先按下面五种范围选命令。

两个容易混淆的本地落点

SQLite 持久化

history 会从本地最旧消息继续向更旧回填，默认最多 1000 条；sync 会从本地最新消息增量更新。一个聊天尚未出现在本地数据库时，sync、sync-all 和 refresh 的首次抓取最多 500 条，即使传入更大的 --limit。

Markdown 文件归档

archive 在线读取历史并写入文件系统，但不会填充 SQLite。首次未指定范围时归档此前七天；后续根据 manifest 与 Markdown 内的消息标记增量追加。

03 · Workflows

常用工作流

下面的组合刻意把在线、持久化、本地和远端写入分开，适合直接改成自己的账号名和聊天 ID。

tg inbox --limit 50 --account work --json
tg read @ops --since 2h --account work --json
tg search-online "incident" --chat @ops --until "2026-07-14T10:00:00+08:00" --account work --yaml

tg refresh --max-chats 20 --delay 1 --account work --json
tg search "error|failed" --regex --hours 168 --account work --json
tg top --chat @ops --hours 168 --limit 20 --account work --json
tg timeline --chat @ops --hours 168 --by hour --account work --json

tg config write-access status --json
tg send @team "Release is ready" --file ./report.pdf --account work --json
tg sync @team --account work --json

tg listen @team --persist --retry-seconds 5 --account work
tg listen @team --no-interactive --no-media --auto-download --account work
tg listen @team @ops --send-to @team --account work

tg archive @ops --download-media --account work --json
tg archive @ops --since "2026-07-12T10:00:00+08:00" --until "2026-07-14T10:00:00+08:00" --account work --json
tg archive --all --full --output ./telegram-archive --account work --markdown

04 · Accounts

账号与配置

每个账号的 Telegram 会话和消息数据库彼此隔离；API 凭据与持久化代理配置则由所有账号共享。

账号生命周期

tg account add
tg account list --json
tg account current --json
tg account switch work --json
tg account logout work --yes --json
tg account login work --json
tg account remove work --force --json

• 第一个添加的账号会成为当前账号；之后新增账号不会自动切换。
• logout 会使 Telegram 会话失效，但保留账号注册信息和消息数据库；已登出的账号仍能运行本地 SQLite 查询。
• login 会安全替换会话并保留数据库。非 TTY 返回 interaction_required 时，请在人类终端重试，不要通过管道传入凭据。
• 自动化优先在每次调用中显式传入 --account work，避免依赖或改变当前账号。

API 凭据和代理

tg config set --api-id <id> --api-hash "<hash>"
tg config set --proxy socks5://127.0.0.1:1080
tg config list --json
TG_PROXY=http://127.0.0.1:8080 tg status

凭据优先级

TG_API_ID 与 TG_API_HASH 必须一起设置，并覆盖已保存值。两者都不存在时可以使用受限的内置默认凭据，但更容易遇到 flood wait。

代理优先级

TG_PROXY 覆盖已保存代理。支持 SOCKS4、SOCKS5、HTTP、HTTPS 和 MTProxy，且代理会用于登录和所有需要 Telegram 连接的命令。

脱敏规则

config list 默认隐藏 API hash。--show-secrets 只显示完整 API hash；代理用户名、密码和凭据查询参数始终显示为 ***。

恢复文件

账号登录失败若返回 error.details.recovery_path 或 recovery_paths，请安全保留并报告这些路径，恢复前不要删除或覆盖。

本地路径

DATA_DIR 可替换操作系统默认数据根目录；DB_PATH 主要用于测试时覆盖数据库。典型布局如下：

config.json
accounts.json
accounts/<name>/session
accounts/<name>/messages.db
accounts/<name>/archive/

05 · Reference

34 个顶层命令

这是 tg v0.6.1 的完整顶层 Commander 命令清单。范围徽标描述主要行为；带子命令的命令组可能同时包含读取和写入操作。

所有有限结果命令都可使用全局 --account（适用时）与 --markdown；各命令的 JSON/YAML 支持和专用参数请用 tg <command> --help 核对。

06 · Groups

群组检查与 48 个管理操作

先用只读路由确认聊天、成员和权限，再执行具体操作。下面每条完整 CLI 语法都把 <chat> 放在操作之后、操作参数之前。

先检查，不修改

tg group info <chat> --account work --json
tg group members <chat> --type admins --query alice --limit 50 --account work --json
tg group member info <chat> <@username-or-user-id> --account work --json
tg group audit <chat> --user <user> --type member_invited --limit 100 --account work --json
tg group list --admin --limit 100 --account work --json

在监听模式使用斜杠命令

在交互式 listen 中输入 /，即可打开统一命令菜单。回复消息或执行群组操作时，无需重复当前聊天：

/reply <message-id> <content>
/member mute @alice 2h

命令依次匹配完整路径、前缀和有序模糊结果。/rep 和 /rpy 会找到 /reply，/ban 会找到 /member ban。

监听多个聊天时，执行群组操作前必须设置 --send-to <chat>。权限与可用性检查仍然生效，有风险的操作会打开确认弹窗。

07 · Automation

结构化输出与自动化

有限结果命令提供稳定信封和错误码；不要解析人类表格，也不要把流式 listen 当作有限结果命令。

tg stats --account work --json
tg stats --account work --yaml
tg inbox --account work --markdown
OUTPUT=markdown tg recent --account work

成功信封

{
  "ok": true,
  "schema_version": "2",
  "data": {}
}

失败信封

{
  "ok": false,
  "schema_version": "2",
  "error": {
    "code": "archive_partial_failure",
    "message": "Some chats or media could not be archived",
    "details": {
      "completed": [],
      "failed": [],
      "warnings": []
    }
  }
}

08 · Safety

远端写入与本地隐私

写入总开关是一道本地技术闸门，不是授权。打开闸门后，仍要在执行每个具体远端修改前取得明确许可。

tg config write-access status --json
tg config write-access off --json
tg config write-access on --json

确认规则

• 标记为高风险的群命令缺少 --yes 时会拒绝执行，不会为了该修改而连接 Telegram。
• 永久删除群组还必须传入 --confirm-title "<exact title>"，内容与当前群名完全一致。
• 没有内置确认提示的操作仍是远端写入；不要把“无需 --yes”理解为“无需授权”。
• Telegram 自身的管理员权限、群主身份、超级群组或论坛能力和速率限制始终适用。

09 · Recovery

故障排查

v0.6.1 的自动化应匹配 error.code，不要匹配可能变化的消息文本。先判断账号与数据范围，再决定是否重试。