Telegram

📬 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:

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)":

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