skillhq/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:

| 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