tg search "release" --account work --json
{
"ok": true,
"schema_version": "2",
"data": [{
"chat_name": "Build room",
"sender_name": "Maya",
"content": "Release is ready…"
}]
}开源 TypeScript CLI
你的 Telegram。
一个命令直达。
读取在线聊天，建立可搜索的本地消息库，在终端里管理对话。对人足够清楚，对智能体足够结构化。
- 运行环境
- Node.js 22.12.0+
- 命令
tg- 许可证
- GPL-3.0-only
在线聊天
结构化结果
找到 1 条本地 SQLite · 无需联网
一套命令界面
从在线聊天，到本地记忆。
明确选择何时连接 Telegram、何时只查询 SQLite，以及何时允许远端写入。每一种工作流的边界都清晰可见。
-
在线读取
查看未读聊天、读取近期消息或监听消息流，查询结果无需写入本地数据库。
tg inbox --markdown -
建立记忆
把需要的聊天同步到 SQLite，之后无需重连即可搜索与分析。
tg sync @team -
谨慎操作
用明确命令发送消息和管理群组，并通过全局开关控制所有远端写入。
tg config write-access off
常用能力，触手可及
为真实 Telegram 工作打造的工具箱。
管理一个或多个账号；需要实时消息时保持在线，需要快速、可重复的查询时把历史带回本地。
实时
inbox · read · listen在终端里守着这场对话。
监听新消息，在交互式监听中直接回复，并自动下载刚收到的附件。
本地搜索
按关键词、正则、发送者、聊天或时间范围筛选已同步消息。
tg search "incident" --hours 48
归档为 Markdown
创建可增量更新、可重建的聊天归档，并可选择下载媒体附件。
tg archive @team --download-media
账号彼此隔离
每个账号使用独立的身份验证会话和消息数据库。
tg account switch work
需要时提供结构化输出
自动化中可使用稳定的 JSON/YAML 信封、非零退出码和明确错误码。
tg stats --json
群组
成员 · 管理员 · 邀请 · 话题深入查看，需要时才修改。
查看群组状态，再通过明确命令管理成员、设置、邀请、论坛话题和消息。
面向智能体工作流
给智能体命令，
不必给它浏览器。
以交互方式完成账号认证后，编程智能体可以查询同步历史、读取结构化结果，并指定账号，而不会改变你的默认选择。
- JSON 和 YAML 输出
- 稳定 schema 与错误码
- 显式选择
--account - 远端写入总开关
Agent skill01 / 01
让你的编程智能体学会使用 tg。
npx skills add https://github.com/will-17173/telegram-cli \
--skill using-telegram-cli
仓库内置的 skill 覆盖账号认证、同步、结构化查询和安全写入工作流。
从这里开始
三个命令，看到第一份聊天列表。
Telegram CLI 需要 Node.js 22.12.0 或更高版本。账号认证会在终端内交互进行，每个账号的会话都保存在本地。
-
1 全局安装
npm install -g @will-17173/telegram-cli -
2 添加账号
tg account add -
3 列出聊天
tg status tg chats
清晰可见的安全边界
放心读取。
远端写入设一道闸。
全局关闭 Telegram 远端修改，同时保留在线读取和本地数据库命令。确实需要操作时，再有意识地重新打开。
tg config write-access off
tg config write-access on
Telegram 权限和速率限制仍然适用。大量历史或媒体请求可能触发 flood wait。