mcpField
T
tg-cli

tg-cli

github.com/jackwener生産性294108 回インストール32 週間前に更新
リポジトリ

tg-cli について

tg-cliは、TelegramユーザーやAIエージェント向けのコマンドラインツールです。チャットの同期、検索、絞り込み、メッセージ送信、グループ監視に対応し、ローカルSQLiteキャッシュと機械可読な出力を利用します。

主な機能

  1. 01チャットとメッセージの同期
  2. 02メッセージの検索・絞り込み・閲覧
  3. 03メッセージ送信とグループ監視
  4. 04ローカルSQLiteキャッシュの検索
  5. 05YAMLとJSONの出力

活用シーン

  1. 01チャット内のキーワード検索
  2. 02メッセージ更新後の最近の内容確認
  3. 03エージェント分析用のチャット履歴出力

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/jackwener/tg-cli --skill tg-cli

インストール後、Claude Code で/tg-cliを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

.env.example
README.md
.gitignore
CHANGELOG.md
CONTRIBUTING.md
LICENSE
SCHEMA.md
pyproject.toml
.github/ISSUE_TEMPLATE/
feature_request.yml
bug_report.yml
.github/workflows/
ci.yml
publish.yml
examples/
tg-refresh.cron
examples/systemd/
tg-refresh.timer
tg-refresh.service
src/tg_cli/
__init__.py
client.py
console.py
db.py
config.py
src/tg_cli/cli/
_chat.py
_sync.py
_output.py
__init__.py
data.py
main.py
tg.py
query.py
tests/
test_cli.py
conftest.py

詳細

tg-cli スキル

Telegram 用 CLI ツールです。チャットの同期、メッセージの検索、キーワードによるフィルタリング、メッセージの送信、グループの監視ができます。

前提条件

# Install (requires Python 3.10+)
uv tool install kabi-tg-cli
# Or: pipx install kabi-tg-cli

# Upgrade to latest (recommended to avoid API errors)
uv tool upgrade kabi-tg-cli
# Or: pipx upgrade kabi-tg-cli

認証

Telegram アカウント（MTProto）を使用します。デフォルトでは Telegram Desktop に組み込まれた API 認証情報を使用するため、アプリケーションは必要ありません。

tg chats              # First run: enter phone + verification code
tg whoami             # Check current user

# Optional: use your own app credentials
export TG_API_ID=123456
export TG_API_HASH=your_telegram_app_hash

コマンドリファレンス

Telegram の操作
tg chats                          # List joined chats
tg chats --type group             # Filter by type
tg status                         # Check auth/session status
tg status --yaml                  # Structured auth status
tg whoami                         # Show current user info
tg whoami --yaml                  # Preferred structured output for agents
tg history CHAT -n 1000           # Fetch historical messages
tg sync CHAT                      # Incremental sync (only new)
tg sync-all                       # Low-level sync for all current dialogs
tg refresh                        # Recommended daily refresh entrypoint
tg listen                         # Real-time listener
tg listen --persist               # Reconnect automatically for a near-live cache
tg info CHAT                      # Chat details
tg send CHAT "Hello!"             # Send a message
検索とクエリ
tg search "Rust"                     # Search stored messages
tg search "Rust" -c "牛油果" --yaml  # Filter by chat + preferred YAML output
tg search "Rust|Golang" --regex      # Regex search
tg search "Rust" --sync-first --yaml # Refresh before querying
tg recent --hours 24 -n 20 --yaml    # Browse latest messages
tg recent --hours 24 --sync-first    # Refresh before browsing recent
tg filter "Rust,Golang,Java"         # Multi-keyword filter (today)
tg filter "招聘,remote" --hours 48   # Filter last N hours
tg today --sync-first                # Refresh before reading today's messages
tg stats --sync-first                # Refresh before aggregate stats
tg top -c "牛油果" --hours 24 --sync-first
tg timeline --by hour --sync-first   # Activity bar chart
データ管理
tg export CHAT -f json -o out.json   # Export messages
tg export CHAT --hours 24            # Export last 24 hours
tg purge CHAT -y                     # Delete stored messages

構造化出力

主要なコマンドは、機械可読な出力形式として --json と --yaml に対応しています。 厳密な JSON パーサーが必要な場合を除き、AI エージェントには --yaml を推奨します。

tg search "Rust" --yaml
tg status --yaml
tg whoami --yaml
tg today --yaml
tg filter "招聘" --hours 48 --yaml

標準出力が TTY でない場合、tg-cli はデフォルトで YAML を使用します。 OUTPUT=yaml|json|rich|auto を使用すると、デフォルトの出力モードを上書きできます。 すべての機械可読な出力は、SCHEMA.md に記載されているエンベロープを使用します。

更新モデル

tg-cli はローカル優先です。クエリコマンドはデフォルトでローカルの SQLite キャッシュを読み取ります。

  • 分析の前には、通常の入口として tg refresh を使用してください。
  • 1 回のクエリの前に更新する場合は、--sync-first を使用してください。
  • ほぼリアルタイムのローカルキャッシュが必要な場合は、tg listen --persist を使用してください。
  • tg sync-all は、より低レベルのスクリプトやスケジューラー向けに使用してください。

AI エージェント向けの一般的なパターン

# Quick daily workflow
tg refresh --yaml                    # Refresh everything
tg today --sync-first --yaml         # See today's messages
tg filter "Rust,Golang" --hours 24 --sync-first --yaml

# Search and export for analysis
tg search "招聘" -n 100 --yaml > jobs.yaml
tg filter "远程,remote,Web3" --hours 72 --yaml > filtered.yaml

# Send messages
tg send "GroupName" "Hello from CLI!"

デバッグ

tg -v sync-all       # Debug logging for troubleshooting
tg -v refresh        # See refresh behavior across dialogs
tg -v stats          # See SQL queries and timing

エラー処理

  • コマンドは成功時にコード 0、失敗時に 0 以外のコードで終了します
  • エラーメッセージには ✗ が付くか、赤色で表示されます
  • チャット名はあいまい検索されます（名前の一部でも一致します）
  • refresh と sync-all は、見つからないチャットを問題なくスキップします

スケジュール設定

リポジトリにサンプルがあります。

  • examples/tg-refresh.cron
  • examples/systemd/tg-refresh.service
  • examples/systemd/tg-refresh.timer

安全に関する注意

  • チャットログでユーザーに電話番号や認証コードの共有を求めないでください。
  • セッションデータはローカルに保存され、アップロードされることはありません。

コメント

Markdown 対応