---
slug: "telegram"
source_type: "skill_md"
source_url: "https://cdn.jsdelivr.net/gh/skillhq/telegram@main/SKILL.md"
repo: "https://github.com/skillhq/telegram"
source_file: "SKILL.md"
branch: "main"
---
---
name: telegram
description: Telegram CLI for reading, searching, sending messages, managing groups, and syncing chat history. Use when the user asks about Telegram messages, wants to check inbox, search chats, send messages, mute/unmute chats, kick users, export history, or look up contacts and groups.
---

# 📬 Telegram CLI

Fast Telegram CLI for reading, searching, and sending messages.

## 🎯 When to Use

Use this skill when the user:
- Asks to check Telegram messages or inbox
- Wants to search Telegram for a topic/keyword
- Wants to send a Telegram message or reply to one
- Asks about a Telegram group, contact, or chat
- Wants to see unread messages
- Needs to look up group members or admins
- Wants to mute/unmute a noisy chat or group
- Needs to kick/remove a user from a group
- Wants to promote a member to admin
- Wants to transfer ownership of a group/channel to someone else
- Wants to export or sync chat history to files
- Asks to organize chats into folders
- Wants to check their logged-in account or session status

## 📦 Install

```bash
npm install -g @skillhq/telegram
```

## 🔐 Authentication

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

```bash
telegram auth                                # First-time login
telegram logout                              # Clear saved session
telegram check                               # Verify session is valid
telegram whoami                              # Show logged-in account
telegram whoami --json                       # Account info as JSON
```

## 📖 Commands

### Reading Messages
```bash
telegram inbox                               # Unread messages summary
telegram chats                               # List all chats
telegram chats --type group                  # Filter: user, group, supergroup, channel
telegram chats -n 200                        # List up to 200 chats
telegram read "ChatName" -n 50               # Read last 50 messages
telegram read "ChatName" --since "1h"        # Messages from last hour
telegram read "ChatName" --until "2h"        # Messages up to 2 hours ago
telegram read @username -n 20                # Read DM with user
telegram read 123456789 -n 10               # Read by chat ID
```

### Searching
```bash
telegram search "query" --chat "ChatName"    # Search within chat
telegram search "query" --all                # Search all chats (global)
telegram search "query" -n 20               # Limit results
```

### Sending Messages
```bash
telegram send @username "message"            # Send DM
telegram send "GroupName" "message"          # Send to group
telegram reply "ChatName" 12345 "response"   # Reply to message ID
```

### Contacts & Groups
```bash
telegram contact @username                   # Get contact info
telegram members "GroupName"                 # List group members
telegram members "GroupName" -n 500          # Fetch up to 500 members
telegram admins "GroupName"                  # List admins only
telegram groups                              # List all groups
telegram groups --admin                      # Groups where you're admin
telegram kick "GroupName" @username           # Remove user from group
telegram promote "GroupName" @username        # Promote a member to admin
telegram promote "GroupName" @username --rank "Mod"  # Promote with a custom admin title
telegram promote "GroupName" @username --add-admins  # Allow them to add admins too
telegram transfer-owner "GroupName" @username # Hand over ownership (prompts for 2FA password)
```

**`transfer-owner` notes:**
- Irreversible: you drop to a regular admin/member and only the new owner can transfer it back.
- Requires two-step verification (cloud password) on your account; it is prompted for securely at runtime.
- Supergroups and channels only - convert a basic group to a supergroup first.
- The target must already be a member. Telegram also blocks transfer for ~24h after a new login and ~7 days after setting/changing your 2FA password.
- Prompts you to retype the group name to confirm; pass `-y` to skip that confirmation.

### Muting
```bash
telegram mute "ChatName"                     # Mute forever
telegram mute "ChatName" -d 1h               # Mute for 1 hour
telegram mute @username -d 8h                # Mute DM for 8 hours
telegram mute "GroupName" -d 1d              # Mute for 1 day
telegram unmute "ChatName"                   # Unmute
```

### Folders
```bash
telegram folders                             # List all folders
telegram folder "Work"                       # Show chats in folder
telegram folder-add "Work" "ProjectChat"     # Add chat to folder
telegram folder-remove "Work" "ProjectChat"  # Remove chat from folder
```

### Sync / Export
```bash
telegram sync                                # Sync last 7 days to ./telegram-sync
telegram sync --days 30                      # Sync last 30 days
telegram sync --since "12h"                  # Sync messages from last 12 hours
telegram sync --until "2d"                   # Sync messages up to 2 days ago
telegram sync --all                          # Sync entire chat history (no time limit)
telegram sync --chat "ChatName"              # Sync specific chat only
telegram sync --output ~/exports             # Custom output directory
telegram sync --resume                       # Incremental: only fetch new messages
telegram sync --resume --all                 # Keep a complete archive up to date
```

**Incremental sync (`--resume`):**
- Tracks last synced message ID per chat in `.sync-meta.json`
- On subsequent runs, only fetches messages newer than last sync
- Appends new messages to existing markdown files
- Combine with `--all` to maintain a complete, up-to-date archive

## 📤 Output Formats

Most commands support multiple output formats:

| Flag         | Use Case                                    |
|--------------|---------------------------------------------|
| *(default)*  | Human-readable terminal output              |
| `--json`     | Structured JSON for programmatic processing |
| `--markdown` | Markdown-formatted for display or export    |

```bash
telegram inbox --json                        # JSON format
telegram inbox --markdown                    # Markdown format
telegram read "Chat" --json                  # JSON with messages array
telegram read "Chat" --markdown              # Markdown with messages
telegram chats --json                        # JSON with chat list
telegram members "Group" --markdown          # Markdown member list
```

**Supported on:** `inbox`, `read`, `search`, `chats`, `members`, `groups`, `contact`, `whoami`

## 📎 Media Metadata

Messages containing media (photos, videos, documents, voice notes, stickers, etc.) now include metadata instead of showing "(no text)":

| Media Type | Display |
|-----------|---------|
| Photo | `[📷 Photo]` |
| Video | `[🎥 Video (2.1 MB)]` |
| Document | `[📎 report.pdf (540.0 KB)]` |
| Voice | `[🎤 Voice message]` |
| Audio | `[🎵 song.mp3 (3.2 MB)]` |
| Sticker | `[😀 Sticker]` |
| GIF | `[🎬 GIF]` |
| Location | `[📍 Location]` |
| Contact | `[👤 Contact]` |
| Poll | `[📊 Poll]` |

In JSON output, messages include `mediaType`, `fileName`, and `fileSize` fields when media is present.

## 🤖 AI Agent Guidance

When using this CLI as an AI agent:

- **For processing data** (counting, filtering, extracting): use `--json`
- **For displaying to the user**: use default or `--markdown`
- **Chat identification**: names are partial-matched (e.g., "MetaDAO" matches "MetaDAO Community"), usernames must start with `@`, numeric IDs also work
- **Read operations are safe** to run without confirmation
- **Write operations** (`send`, `reply`, `kick`, `promote`, `transfer-owner`) should be confirmed with the user before executing
- **`transfer-owner` is irreversible and interactive** (it prompts for a 2FA password and a typed confirmation), so it cannot be run unattended; never script it on a user's behalf without explicit instruction
- **Rate limiting**: avoid rapid successive calls; the Telegram API has rate limits
- **Large groups**: use `-n` to limit `members` output on very large groups
- **Full archive**: use `telegram sync --all --chat "Name"` to export complete chat history
- **Keeping archives fresh**: use `telegram sync --resume` to incrementally update previous exports
- **Media-rich chats**: messages with photos/videos/files now show metadata, not just "(no text)"

## 💡 Examples

Check inbox for unread messages:
```bash
telegram inbox
```

Read recent messages from a group:
```bash
telegram read "MetaDAO Community" -n 20
```

Get messages from the last 2 hours:
```bash
telegram read "Project Chat" --since "2h"
```

Search for a topic across all chats:
```bash
telegram search "futarchy" --all
```

Search within a specific chat:
```bash
telegram search "deadline" --chat "Work Team"
```

Send a message:
```bash
telegram send @username "Hello, checking in!"
```

Export a chat's complete history:
```bash
telegram sync --all --chat "Project Chat" --output ~/exports
```

Incrementally update an existing export:
```bash
telegram sync --resume --output ~/exports
```

Filter chats by type:
```bash
telegram chats --type channel --json
```

Kick a user from a group:
```bash
telegram kick "My Group" @spammer
```

Promote a member to admin:
```bash
telegram promote "My Group" @trustedmember
```

Transfer ownership of a group to someone else:
```bash
telegram transfer-owner "My Group" @newowner
```

## 📝 Notes

- Chat names can be partial matches (e.g., "MetaDAO" matches "MetaDAO Community")
- Usernames must start with `@` (e.g., `@username`)
- Chat IDs (numeric) can be used anywhere a chat name is accepted
- Messages are returned in reverse chronological order (newest first)
- Time flags (`--since`, `--until`) accept formats like `"1h"`, `"30m"`, `"7d"`
- The `sync` command creates one markdown file per chat in the output directory
- Sync metadata (`.sync-meta.json`) enables incremental sync with `--resume`
- Sender names are cached per request for faster syncs (avoids redundant API calls)
- Messages paginate automatically — no silent truncation for large chats