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-cliAuthentication
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_hashCommand 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 messageSearch & 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 chartData 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 messagesStructured 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 --yamlWhen 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 refreshas the normal entrypoint before analysis. - Use
--sync-firstwhen a single query should refresh before reading. - Use
tg listen --persistif you want a near-real-time local cache. - Keep
tg sync-allfor 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 timingError 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)
refreshandsync-allgracefully skip chats that can't be found
Scheduling
Examples live in the repository:
examples/tg-refresh.cronexamples/systemd/tg-refresh.serviceexamples/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.