kfastov/tgcli

tgcli

Telegram CLI with background sync.

When to Use

Use this skill when the user:

• Wants to read or search Telegram messages
• Needs recent updates or an inbox-style view of chats
• Asks to send a Telegram message or file
• Wants to download media or files from Telegram
• Wants to look up channels, groups, or contacts
• Needs archive/backfill sync for a chat

Install

npm install -g @kfastov/tgcli

Or:

brew install kfastov/tap/tgcli

Authentication

First-time setup needs Telegram API credentials from https://my.telegram.org/apps

tgcli auth

Common Commands

Reading

tgcli channels list --limit 20
tgcli messages list --chat @username --limit 50
tgcli messages search "query" --chat @channel --source archive
tgcli topics list --chat @channel --limit 20

Files & Media

tgcli media download --chat @channel --id 12345
tgcli send file --to @channel --file ./report.pdf --caption "FYI"

Writing

tgcli send text --to @username --message "Hello"

Backfill & Service

tgcli backfill --chat @channel                 # backfill one chat (auto-starts the server, follows progress)
tgcli backfill --chat @channel --background    # enqueue and return the job id
tgcli backfill --chat @channel --depth 5000 --min-date 2024-01-01T00:00:00Z
tgcli backfill status                          # active backfills + server status
tgcli backfill count                           # number of in-progress backfills
tgcli backfill wait                            # block until the queue drains
tgcli backfill cancel --chat @channel          # stop a chat's backfills
tgcli channels watch --chat @channel           # subscribe a chat for archiving (queues a backfill)
tgcli channels unwatch --chat @channel         # stop archiving a chat
tgcli backfill --follow                         # track the server's queue to completion (`sync` is a silent alias)
tgcli service install
tgcli service start

Telegram and archive commands (channels, messages, send, media, topics, tags, metadata, contacts, groups, folders) run through the always-on control server, not the CLI. The CLI is a thin client: it auto-starts tgcli server in the background when one isn't running, has it execute the operation against its warm connection and database, then renders the result; the server shuts itself down once idle. config, service, doctor, and auth stay local. Foreground backfill --chat follows progress on stderr; Ctrl-C detaches (the job keeps running — check tgcli backfill status).

Contacts & Groups

tgcli contacts search "alex"
tgcli groups list --query "Nha Trang"

Output Formats

All commands support --json for structured output:

tgcli messages list --chat @username --limit 5 --json
tgcli channels list --limit 10 --json

Notes

• Use --source live|archive|both when listing or searching messages.
• --json is best for AI/tooling pipelines.
• send commands time out after 30s by default so they never hang on a stuck connection. Override with --timeout 5m or disable with --timeout 0. Long-running commands (backfill, --follow, server) are unbounded by default.
• backfill is the canonical archive command; sync (and channels sync --enable/--disable) keep working as aliases. Prefer channels watch/channels unwatch to subscribe/unsubscribe a chat.