About

Imported from ishan-parihar/tg-cli (SKILL.md). Install upstream with npx skills add ishan-parihar/tg-cli. Copyright stays with the author.

tg-cli Skill

Name: tg-cli
Author: ishan-parihar

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.

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/ishan-parihar-tg-cli-tg-cli/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

ishan-parihar-tg-cli-tg-cli.ocm.jsonjson

{
  "ocm": "1",
  "id": "ishan-parihar-tg-cli-tg-cli",
  "kind": "skill",
  "name": "tg-cli",
  "description": "CLI skill for Telegram to sync chats, search messages, filter keywords, and monitor groups from the terminal",
  "publisher": "ishan-parihar",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "general"
    ],
    "tags": [
      "skill-md",
      "telegram",
      "tg",
      "chat",
      "monitor",
      "cli",
      "github"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "CLI skill for Telegram to sync chats, search messages, filter keywords, and monitor groups from the terminal"
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "github",
      "repository": "https://github.com/ishan-parihar/tg-cli",
      "path": "SKILL.md",
      "ref": "45feb388e008aff4c34b676433ea4c64c9b9bc63",
      "url": "https://github.com/ishan-parihar/tg-cli/blob/45feb388e008aff4c34b676433ea4c64c9b9bc63/SKILL.md",
      "key": "ishan-parihar/tg-cli/SKILL.md"
    }
  },
  "instructions": "# tg-cli Skill\n\nCLI tool for Telegram — sync chats, search messages, filter keywords, send messages, and monitor groups.\n\n## Prerequisites\n\n```bash\n# Install (requires Python 3.10+)\nuv tool install kabi-tg-cli\n# Or: pipx install kabi-tg-cli\n\n# Upgrade to latest (recommended to avoid API errors)\nuv tool upgrade kabi-tg-cli\n# Or: pipx upgrade kabi-tg-cli\n```\n\n## Authentication\n\nUses your Telegram account (MTProto). Built-in Telegram Desktop API credentials are used by default — no application needed.\n\n```bash\ntg chats              # First run: enter phone + verification code\ntg whoami           ",
  "cost": {
    "context_tokens": 1183
  }
}

Fetch it by URL: GET /api/v1/registry/ishan-parihar-tg-cli-tg-cli/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.