tg-cli

PyPI package name: kabi-tg-cli — install with uv tool install kabi-tg-cli

Telethon-powered Telegram CLI for local-first sync, search, export, and agent-friendly retrieval.

More Projects

• xiaohongshu-cli — Xiaohongshu (小红书) CLI for notes and account workflows
• twitter-cli — Twitter/X CLI for timelines, search, and posting
• bilibili-cli — Bilibili CLI for videos, users, search, and feeds
• discord-cli — Discord CLI for local-first sync, search, and export

English | 中文

English

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.

Features

• Sync Telegram dialogs into a local SQLite cache
• Search by keyword or regex, with chat, sender, and time filters
• Browse recent messages, today's messages, top senders, and timelines
• Export messages as text, JSON, or YAML
• Keep a near-real-time cache with tg listen --persist
• Prefer YAML for AI agents when a strict JSON parser is not required
• Default to YAML automatically on non-TTY stdout; override with OUTPUT=yaml|json|rich|auto
• Structured output contract: SCHEMA.md

Installation

# 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-cli

Tip: 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

Quick Start

# 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

Refresh Model

tg-cli is intentionally local-first:

• tg refresh is the recommended daily entrypoint
• tg sync-all is the lower-level primitive for scripts and schedulers
• --sync-first refreshes before a single query
• tg listen --persist reconnects automatically for a near-live cache

Most query commands read from local SQLite, not directly from Telegram.

Usage

# 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!"

Scheduling

If you do not want to run tg refresh manually, use a scheduler.

cron

See examples/tg-refresh.cron.

systemd user timer

See:

• tg-refresh.service
• tg-refresh.timer

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

Use as AI Agent Skill

tg-cli ships with a SKILL.md for AI agent integration.

Agent Output Recommendation

If an AI agent needs machine-readable output, prefer --yaml first:

• --yaml is usually more token-efficient than pretty-printed JSON
• It is still easy to parse for agents and scripts
• Keep --json for jq, strict JSON-only tooling, or exact downstream schemas
• Non-TTY stdout defaults to YAML automatically
• Use OUTPUT=yaml|json|rich|auto to override the default mode

Recommended agent workflow:

tg refresh --yaml
tg chats --yaml
tg recent --hours 24 --sync-first --yaml
tg search "keyword" --chat "GroupName" --sync-first --yaml

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

⚠️ Account Safety

tg-cli uses your personal Telegram account via MTProto. To reduce the risk of account restrictions:

1. 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.

2. Limit sync frequency — Avoid running tg refresh more than 1–2 times per day.

3. 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 run

4. Prefer established accounts — New or rarely-used accounts are more likely to be flagged.

5. Prefer read-only operations — tg send carries higher risk than read commands.

Troubleshooting

• No messages today
  • Run tg refresh first, or use tg today --sync-first.
• Chat '...' not found in database
  • Run tg refresh first, or use the numeric chat_id from tg chats --yaml.
• Repeatedly running sync-all
  • Prefer 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 调用。

功能特性

• 同步 Telegram dialogs 到本地 SQLite
• 支持关键词搜索和 regex 搜索，可按 chat、sender、时间窗口过滤
• 支持 recent、today、top、timeline 等本地分析命令
• 支持导出为 text、JSON、YAML
• 支持 tg listen --persist，维持近实时本地缓存
• 支持 --json / --yaml，其中 AI agent 更推荐 --yaml
• stdout 不是 TTY 时默认自动输出 YAML，也可以用 OUTPUT=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
  • 推荐的日常入口，刷新所有当前 dialogs
• tg sync-all
  • 更底层的同步原语，适合脚本和调度器
• --sync-first
  • 单次查询前先刷新，适合 today、search、recent
• tg 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，可以配合调度器。

cron

参考 examples/tg-refresh.cron。

systemd user timer

参考：

• tg-refresh.service
• tg-refresh.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

作为 AI Agent Skill 使用

tg-cli 自带 SKILL.md，方便 AI agent 自动学习并调用。

Agent 输出建议

如果下游不是严格要求 JSON，优先使用 --yaml：

• --yaml 通常比 pretty-printed JSON 更省 token
• 对 agent 和脚本来说依然容易解析
• 只有在 jq 或严格 JSON-only tooling 场景下再优先用 --json
• stdout 不是 TTY 时会默认自动输出 YAML
• 也可以用 OUTPUT=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

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

⚠️ 账号安全

tg-cli 使用你的个人 Telegram 账号走 MTProto。为了降低账号被风控的风险：

1. 申请自己的 API 凭证 — 前往 my.telegram.org，创建应用后设置：

   export TG_API_ID=12345678
   export TG_API_HASH="your_api_hash_here"

   默认的 api_id=2040（Telegram Desktop）被大量第三方工具共用，风控更严格。

2. 控制同步频率 — 避免每天执行 tg refresh 超过 1-2 次。

3. 使用 --delay 和 --max-chats — refresh 和 sync-all 支持：

   • --delay 3.0 — 每个 chat 同步间隔秒数（默认 2.0，±20% 随机抖动）
   • --max-chats 30 — 每次最多同步前 N 个 chat

4. 优先使用老号 — 新注册或长期未活跃的账号更容易被标记。

5. 优先只读操作 — tg send 比读取类命令风险更高。

常见问题

• No messages today
  • 先执行 tg refresh，或直接使用 tg today --sync-first
• Chat '...' not found in database
  • 先执行 tg refresh，或用 tg chats --yaml 找到准确的 chat_id
• 为什么总要先同步
  • 因为 tg-cli 是 local-first 设计，大多数查询命令默认读本地 SQLite，不直接查 Telegram

推荐项目

• twitter-cli — Twitter/X 时间线、搜索与发帖 CLI
• bilibili-cli — Bilibili 视频、用户、搜索与动态 CLI
• discord-cli — Discord 本地优先同步、检索与导出 CLI

License

Apache-2.0