gem-hunter
Language: Python
A CLI for Telegram — local-first sync, search, export via MTProto
PyPI package name:
kabi-tg-cli— install withuv tool install kabi-tg-cli
Telethon-powered Telegram CLI for local-first sync, search, export, and agent-friendly retrieval.
tg-cli uses your own Telegram account over MTProto, not the Bot API. It syncs messages into local
SQLite so humans and AI agents can query the same cache quickly with --json or --yaml.
tg listen --persistOUTPUT=yaml|json|rich|auto# Recommended: uv tool uv tool install kabi-tg-cli # Or: pipx / pip pipx install kabi-tg-cli pip install kabi-tg-cli
Upgrade to the latest version:
uv tool upgrade kabi-tg-cli
# Or: pipx upgrade kabi-tg-cliTip: Upgrade regularly to avoid unexpected errors from outdated API handling.
Install from GitHub:
uv tool install git+https://github.com/jackwener/tg-cli.git
Install from source:
git clone git@github.com:jackwener/tg-cli.git
cd tg-cli
uv sync --extra dev# First login (uses Telegram Desktop built-in credentials by default) tg chats # Check the current account tg status tg whoami # Refresh the local cache tg refresh # Read and search tg today tg recent --hours 24 --limit 20 --yaml tg search "Rust" --hours 48 tg filter "Rust,Golang,remote" --hours 48 --sync-first --yaml # Keep a near-real-time cache tg listen --persist
tg-cli is intentionally local-first:
tg refresh is the recommended daily entrypointtg sync-all is the lower-level primitive for scripts and schedulers--sync-first refreshes before a single querytg listen --persist reconnects automatically for a near-live cacheMost query commands read from local SQLite, not directly from Telegram.
# Sync tg status --yaml tg refresh tg sync-all --yaml tg sync "GroupName" # Search / browse tg search "Rust" tg search "Rust|Golang" --regex --hours 72 tg recent --hours 24 --limit 20 --yaml tg today --sync-first tg top --hours 24 --sync-first tg timeline --by hour --sync-first # Export tg export "GroupName" -f yaml -o messages.yaml # Send tg send "GroupName" "Hello!"
If you do not want to run tg refresh manually, use a scheduler.
See:
Typical flow:
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 ships with a SKILL.md for AI agent integration.
If an AI agent needs machine-readable output, prefer --yaml first:
--yaml is usually more token-efficient than pretty-printed JSON--json for jq, strict JSON-only tooling, or exact downstream schemasOUTPUT=yaml|json|rich|auto to override the default modeRecommended agent workflow:
tg refresh --yaml tg chats --yaml tg recent --hours 24 --sync-first --yaml tg search "keyword" --chat "GroupName" --sync-first --yaml
npx skills add jackwener/tg-cli
| Flag | Description |
|---|---|
-g |
Install globally (user-level, shared across projects) |
-a claude-code |
Target a specific agent |
-y |
Non-interactive mode |
mkdir -p .agents/skills git clone git@github.com:jackwener/tg-cli.git .agents/skills/tg-cli
⚠️ ClawHub install method is deprecated and no longer supported. Use Skills CLI or Manual Install above.
tg-cli uses your personal Telegram account via MTProto. To reduce the risk of account restrictions:
Get your own API credentials — Go to my.telegram.org, create an app, and set:
export TG_API_ID=12345678 export TG_API_HASH="your_api_hash_here"
The default api_id=2040 (Telegram Desktop) is shared by many third-party tools and may attract stricter scrutiny.
Limit sync frequency — Avoid running tg refresh more than 1–2 times per day.
Use --delay and --max-chats — Both refresh and sync-all support:
--delay 3.0 — seconds between each chat sync (default: 2.0, with ±20% jitter)--max-chats 30 — only sync the first N chats per runPrefer established accounts — New or rarely-used accounts are more likely to be flagged.
Prefer read-only operations — tg send carries higher risk than read commands.
No messages today
tg refresh first, or use tg today --sync-first.Chat '...' not found in database
tg refresh first, or use the numeric chat_id from tg chats --yaml.sync-all
tg refresh for daily use, --sync-first for single queries, or tg listen --persist.tg-cli 是一个基于 Telethon 的 Telegram CLI。它不是 Bot API 工具，而是使用你自己的
Telegram 账号走 MTProto，把消息同步到本地 SQLite，方便你在终端里做搜索、筛选、导出，
也方便 AI agent 直接把它当作本地 retrieval tool 调用。
recent、today、top、timeline 等本地分析命令tg listen --persist，维持近实时本地缓存--json / --yaml，其中 AI agent 更推荐 --yamlOUTPUT=yaml|json|rich|auto 覆盖# 推荐：uv tool uv tool install kabi-tg-cli # 或者：pipx / pip pipx install kabi-tg-cli pip install kabi-tg-cli
升级到最新版本：
uv tool upgrade kabi-tg-cli
# 或：pipx upgrade kabi-tg-cli提示： 建议定期升级，避免因版本过旧导致的 API 调用异常。
从 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# 首次登录（默认使用 Telegram Desktop 内置的 API 凭证） tg chats # 检查当前账号 tg status tg whoami # 刷新本地缓存 tg refresh # 浏览和搜索 tg today tg recent --hours 24 --limit 20 --yaml tg search "Rust" --hours 48 tg filter "招聘,remote,Web3" --hours 48 --sync-first --yaml # 保持近实时缓存 tg listen --persist
tg-cli 是 local-first 设计：
tg refresh
tg sync-all
--sync-first
today、search、recenttg listen --persist
大多数查询命令默认读本地 SQLite，而不是每次都直接请求 Telegram。
# 同步 tg status --yaml tg refresh tg sync-all --yaml tg sync "群名" # 搜索 / 浏览 tg search "Rust" tg search "Rust|Golang" --regex --hours 72 tg recent --hours 24 --limit 20 --yaml tg today --sync-first tg top --hours 24 --sync-first tg timeline --by hour --sync-first # 导出 tg export "群名" -f yaml -o messages.yaml # 发送消息 tg send "群名" "Hello!"
如果你不想每次手动执行 tg refresh，可以配合调度器。
参考：
典型流程：
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 自带 SKILL.md，方便 AI agent 自动学习并调用。
如果下游不是严格要求 JSON，优先使用 --yaml：
--yaml 通常比 pretty-printed JSON 更省 tokenjq 或严格 JSON-only tooling 场景下再优先用 --jsonOUTPUT=yaml|json|rich|auto 强制覆盖默认输出模式推荐的 agent 调用顺序：
tg refresh --yaml tg chats --yaml tg recent --hours 24 --sync-first --yaml tg search "keyword" --chat "GroupName" --sync-first --yaml
npx skills add jackwener/tg-cli
| 参数 | 说明 |
|---|---|
-g |
全局安装（用户级别，跨项目共享） |
-a claude-code |
指定目标 Agent |
-y |
非交互模式 |
mkdir -p .agents/skills git clone git@github.com:jackwener/tg-cli.git .agents/skills/tg-cli
⚠️ ClawHub 安装方式已过时，不再支持。请使用上方的 Skills CLI 或手动安装。
tg-cli 使用你的个人 Telegram 账号走 MTProto。为了降低账号被风控的风险：
申请自己的 API 凭证 — 前往 my.telegram.org，创建应用后设置：
export TG_API_ID=12345678 export TG_API_HASH="your_api_hash_here"
默认的 api_id=2040（Telegram Desktop）被大量第三方工具共用，风控更严格。
控制同步频率 — 避免每天执行 tg refresh 超过 1-2 次。
使用 --delay 和 --max-chats — refresh 和 sync-all 支持：
--delay 3.0 — 每个 chat 同步间隔秒数（默认 2.0，±20% 随机抖动）--max-chats 30 — 每次最多同步前 N 个 chat优先使用老号 — 新注册或长期未活跃的账号更容易被标记。
优先只读操作 — tg send 比读取类命令风险更高。
No messages today
tg refresh，或直接使用 tg today --sync-firstChat '...' not found in database
tg refresh，或用 tg chats --yaml 找到准确的 chat_idtg-cli 是 local-first 设计，大多数查询命令默认读本地 SQLite，不直接查 TelegramApache-2.0