# Tgcli

> 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.

- **Type:** Skill
- **Install:** `agentstack add skill-kfastov-tgcli-tgcli`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [kfastov](https://agentstack.voostack.com/s/kfastov)
- **Installs:** 0
- **Category:** [Communication](https://agentstack.voostack.com/c/communication)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [kfastov](https://github.com/kfastov)
- **Source:** https://github.com/kfastov/tgcli

## Install

```sh
agentstack add skill-kfastov-tgcli-tgcli
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

```bash
npm install -g @kfastov/tgcli
```

Or:
```bash
brew install kfastov/tap/tgcli
```

## Authentication

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

```bash
tgcli auth
```

## Common Commands

### Reading
```bash
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
```bash
tgcli media download --chat @channel --id 12345
tgcli send file --to @channel --file ./report.pdf --caption "FYI"
```

### Writing
```bash
tgcli send text --to @username --message "Hello"
```

### Backfill & Service
```bash
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
```bash
tgcli contacts search "alex"
tgcli groups list --query "Nha Trang"
```

## Output Formats

All commands support `--json` for structured output:

```bash
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.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [kfastov](https://github.com/kfastov)
- **Source:** [kfastov/tgcli](https://github.com/kfastov/tgcli)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-kfastov-tgcli-tgcli
- Seller: https://agentstack.voostack.com/s/kfastov
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.