telegram

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

npm install -g @skillhq/telegram

🔐 Authentication

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

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

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

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

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

Contacts & Groups

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

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

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

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

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:

telegram inbox

Read recent messages from a group:

telegram read "MetaDAO Community" -n 20

Get messages from the last 2 hours:

telegram read "Project Chat" --since "2h"

Search for a topic across all chats:

telegram search "futarchy" --all

Search within a specific chat:

telegram search "deadline" --chat "Work Team"

Send a message:

telegram send @username "Hello, checking in!"

Export a chat's complete history:

telegram sync --all --chat "Project Chat" --output ~/exports

Incrementally update an existing export:

telegram sync --resume --output ~/exports

Filter chats by type:

telegram chats --type channel --json

Kick a user from a group:

telegram kick "My Group" @spammer

Promote a member to admin:

telegram promote "My Group" @trustedmember

Transfer ownership of a group to someone else:

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