tg-cli：本地优先的 Telegram 命令行工具

本文介绍 tg-cli，一个基于 Telethon 的 Telegram 命令行工具。该项目采用本地优先的设计理念，将 Telegram 消息同步到本地 SQLite 数据库，支持快速搜索、导出和 AI Agent 友好的数据检索，是 Telegram 高级用户和 AI 应用的理想工具。

项目简介

tg-cli 是一个开源的 Telegram 命令行工具，由 jackwener 开发维护。项目使用 Python 和 Telethon 库构建，通过 MTProto 协议连接 Telegram（而非 Bot API），能够将对话同步到本地 SQLite 缓存，实现快速的本地查询和 AI Agent 集成。

核心特性

• 本地优先架构：将 Telegram 对话同步到本地 SQLite 数据库
• 强大的搜索能力：支持关键词和正则表达式搜索，可按聊天、发送者、时间过滤
• 多种浏览模式：最近消息、今日消息、热门发送者、时间线视图
• 灵活的导出功能：支持导出为文本、JSON、YAML 格式
• 近实时缓存：通过 tg listen --persist 保持缓存最新
• AI Agent 友好：优先使用 YAML 输出，非 TTY 自动切换
• 结构化输出：提供严格的数据模式定义（SCHEMA.md）
• 多平台支持：通过 PyPI 发行，支持 uv、pipx、pip 安装
• 自动调度支持：提供 cron 和 systemd timer 示例
• SKILL.md 集成：原生支持 Claude Code、OpenClaw 等 AI Agent

技术栈

• Python 3.10+ - 核心开发语言
• Telethon - Telegram MTProto 客户端库
• SQLite - 本地数据存储
• Pydantic - 数据验证和序列化
• Rich - 终端 UI 美化
• uv/pipx - Python 包管理和分发

安装指南

前置要求

• Python 3.10 或更高版本
• Telegram 账号
• Telegram API 凭证（api_id 和 api_hash）

获取 API 凭证

1. 访问 my.telegram.org
2. 登录你的 Telegram 账号
3. 创建一个新应用
4. 获取 api_id 和 api_hash
5. 设置环境变量：
   bashCopy

   export TG_API_ID=12345678
   export TG_API_HASH="your_api_hash_here"

安全提示：建议使用自己的 API 凭证，避免使用共享的 api_id=2040（Telegram Desktop），以降低账号受限风险。

安装方法

方法一：使用 uv（推荐）

uv tool install kabi-tg-cli

方法二：使用 pipx

pipx install kabi-tg-cli

方法三：使用 pip

pip install kabi-tg-cli

从 GitHub 安装：

uv tool install git+https://github.com/jackwener/tg-cli.git

从源码安装：

git clone git@github.com:jackwener/tg-cli.git
cd tg-cli
uv sync --extra dev

升级到最新版本

uv tool upgrade kabi-tg-cli
# 或: pipx upgrade kabi-tg-cli

快速开始

首次登录

# 首次运行会使用 Telegram Desktop 内置凭证
tg chats

# 检查当前账号
tg status
tg whoami

# 刷新本地缓存
tg refresh

基本使用

# 查看今日消息
tg today

# 查看最近 24 小时的 20 条消息（YAML 格式）
tg recent --hours 24 --limit 20 --yaml

# 搜索包含 "Rust" 的消息
tg search "Rust" --hours 48

# 使用正则表达式搜索
tg search "Rust|Golang" --regex --hours 72

# 多关键词过滤
tg filter "Rust,Golang,remote" --hours 48 --sync-first --yaml

# 保持近实时缓存
tg listen --persist

使用示例

场景 1：搜索和浏览

# 搜索特定关键词
tg search "project update" --chat "Work Group" --hours 24

# 查看最近消息
tg recent --hours 12 --limit 50

# 查看今日消息
tg today --sync-first

# 查看热门发送者
tg top --hours 24 --sync-first

# 按小时查看时间线
tg timeline --by hour --sync-first

# 查看所有对话
tg chats --yaml

场景 2：导出消息

# 导出特定对话为 YAML
tg export "GroupName" -f yaml -o messages.yaml

# 导出为 JSON
tg export "GroupName" -f json -o messages.json

# 导出为纯文本
tg export "GroupName" -f text -o messages.txt

场景 3：发送消息

# 发送文本消息
tg send "GroupName" "Hello from CLI!"

# 发送文件
tg send "username" "Check this file" --file /path/to/file.pdf

场景 4：AI Agent 集成

# 推荐：使用 YAML 输出（更节省 token）
tg refresh --yaml
tg chats --yaml
tg recent --hours 24 --sync-first --yaml
tg search "keyword" --chat "GroupName" --sync-first --yaml

# 非 TTY 环境自动使用 YAML
echo "search query" | tg search --stdin --yaml

场景 5：定时同步

使用 cron：

# 编辑 crontab
crontab -e

# 添加每小时同步一次
0 * * * * /usr/local/bin/tg refresh

使用 systemd timer：

mkdir -p ~/.config/systemd/user
cp examples/systemd/tg-refresh.service ~/.config/systemd/user/
cp examples/systemd/tg-refresh.timer ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now tg-refresh.timer

刷新模型

tg-cli 采用本地优先设计：

• tg refresh：推荐的日常入口点
• tg sync-all：低级原语，用于脚本和调度器
• --sync-first：单次查询前刷新
• tg listen --persist：自动重连保持近实时缓存

大多数查询命令从本地 SQLite 读取，而非直接从 Telegram。

命令参考

同步命令

搜索命令

导出命令

发送命令

选项参数

AI Agent 集成

Claude Code / Antigravity

mkdir -p .agents/skills
git clone git@github.com:jackwener/tg-cli.git .agents/skills/tg-cli

OpenClaw / ClawHub

clawhub install tg-cli

Agent 输出建议

AI Agent 应优先使用 --yaml：

• YAML 比 JSON 更节省 token
• 仍然易于解析
• 保留 --json 用于严格 JSON 工具（如 jq）
• 非 TTY stdout 自动使用 YAML
• 使用 OUTPUT=yaml|json|rich|auto 覆盖默认模式

配置文件

tg-cli 使用以下配置：

• API 凭证：环境变量 TG_API_ID 和 TG_API_HASH
• 会话文件：默认使用 Telegram Desktop 内置凭证
• 缓存位置：本地 SQLite 数据库
• 输出格式：OUTPUT 环境变量

相关项目

作者的其他 CLI 工具：

• xiaohongshu-cli — 小红书 CLI
• twitter-cli — Twitter/X CLI
• bilibili-cli — B站 CLI
• discord-cli — Discord CLI

应用场景

• 消息管理：快速搜索和浏览 Telegram 历史
• 数据备份：本地备份重要对话和媒体
• AI 应用：为 AI Agent 提供结构化的 Telegram 数据
• 自动化工作流：集成到脚本和自动化流程
• 批量操作：批量发送、搜索、导出消息
• 监控和分析：监控群组活动和趋势

注意事项

• 使用自己的 API 凭证以降低账号风险
• 定期更新以获得最新的 API 处理
• 首次使用可能需要 Telegram 认证
• 大量同步可能消耗较多带宽和时间
• 建议使用调度器定期刷新缓存
• YAML 输出更适合 AI Agent 处理

项目链接

• GitHub 仓库：https://github.com/jackwener/tg-cli
• PyPI 包：https://pypi.org/project/kabi-tg-cli/
• SKILL.md：AI Agent 集成文档
• 开源协议：Apache 2.0 License