How do I install the Tgcli skill?

Run npx skillmds@latest add kfastov/tgcli in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Tgcli safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Tgcli?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Tgcli free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

kfastov (@kfastov) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Tgcli by kfastov — Agent Skill

Name: Tgcli
Author: kfastov

File contents

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.

---name: tgclidescription: Telegram CLI for reading/searching messages, syncing archives, and sending or downloading files. Use when the user asks about Telegram chats, messages, contacts, groups, or files.---# tgcliTelegram CLI with background sync.## When to UseUse 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```bashnpm install -g @kfastov/tgcli```Or:```bashbrew install kfastov/tap/tgcli```## AuthenticationFirst-time setup needs Telegram API credentials from https://my.telegram.org/apps```bashtgcli auth```## Common Commands### Reading```bashtgcli channels list --limit 20tgcli messages list --chat @username --limit 50tgcli messages search "query" --chat @channel --source archivetgcli topics list --chat @channel --limit 20```### Files & Media```bashtgcli media download --chat @channel --id 12345tgcli send file --to @channel --file ./report.pdf --caption "FYI"```### Writing```bashtgcli send text --to @username --message "Hello"```### Backfill & Service```bashtgcli backfill --chat @channel # backfill one chat (auto-starts the server, follows progress)tgcli backfill --chat @channel --background # enqueue and return the job idtgcli backfill --chat @channel --depth 5000 --min-date 2024-01-01T00:00:00Ztgcli backfill status # active backfills + server statustgcli backfill count # number of in-progress backfillstgcli backfill wait # block until the queue drainstgcli backfill cancel --chat @channel # stop a chat's backfillstgcli channels watch --chat @channel # subscribe a chat for archiving (queues a backfill)tgcli channels unwatch --chat @channel # stop archiving a chattgcli backfill --follow # track the server's queue to completion (`sync` is a silent alias)tgcli service installtgcli 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 thebackground when one isn't running, has it execute the operation against its warmconnection and database, then renders the result; the server shuts itself downonce idle. `config`, `service`, `doctor`, and `auth` stay local. Foreground`backfill --chat` follows progress on stderr; **Ctrl-C detaches** (the job keepsrunning — check `tgcli backfill status`).### Contacts & Groups```bashtgcli contacts search "alex"tgcli groups list --query "Nha Trang"```## Output FormatsAll commands support `--json` for structured output:```bashtgcli messages list --chat @username --limit 5 --jsontgcli 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.

Frequently asked questions

Tgcli