mcpField
T
tg-cli

tg-cli

github.com/jackwenerProductivity294108 installsUpdated 32w ago
Repository

About tg-cli

tg-cli is a command-line tool for Telegram users and AI agents to sync chats, search and filter messages, send messages, and monitor groups. Queries use a local SQLite cache by default, with machine-readable YAML and JSON output.

Key features

  1. 01Sync chats and messages
  2. 02Search, filter, and browse messages
  3. 03Send messages and monitor groups
  4. 04Query a local SQLite cache
  5. 05YAML and JSON output

Use cases

  1. 01Find keywords across chats
  2. 02Refresh messages before reviewing recent activity
  3. 03Export chat history for agent analysis

Install

Copy the command and run it in a terminal.

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

After installing, type/tg-cliin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with 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

Details

From the project README

tg-cli Skill

CLI tool for Telegram — sync chats, search messages, filter keywords, send messages, and monitor groups.

Prerequisites

# 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

Authentication

Uses your Telegram account (MTProto). Built-in Telegram Desktop API credentials are used by default — no application needed.

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

Command Reference

Telegram Operations
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
Search & Query
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
Data Management
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

Structured Output

Major commands support --json and --yaml for machine-readable output. AI agents should prefer --yaml unless a strict JSON parser is required:

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

When stdout is not a TTY, tg-cli defaults to YAML automatically. Use OUTPUT=yaml|json|rich|auto to override the default output mode. All machine-readable output uses the envelope documented in SCHEMA.md.

Refresh Model

tg-cli is local-first. Query commands read from the local SQLite cache by default.

  • Use tg refresh as the normal entrypoint before analysis.
  • Use --sync-first when a single query should refresh before reading.
  • Use tg listen --persist if you want a near-real-time local cache.
  • Keep tg sync-all for lower-level scripts or schedulers.

Common Patterns for AI Agents

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

Debugging

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

Error Handling

  • Commands exit with code 0 on success, non-zero on failure
  • Error messages are prefixed with ✗ or shown in red
  • Chat names are fuzzy-matched (partial name works)
  • refresh and sync-all gracefully skip chats that can't be found

Scheduling

Examples live in the repository:

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

Safety Notes

  • Do not ask users to share phone numbers or verification codes in chat logs.
  • Session data is stored locally and never uploaded.

Comments

Markdown supported