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 to someone
• Asks about a Telegram group, contact, or chat
• Wants to see unread messages
• Needs to look up group members or admins

Install

npm install -g @skillhq/telegram

Authentication

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

telegram auth

Commands

Reading

telegram inbox                               # Unread messages summary
telegram chats                               # List all chats
telegram read "ChatName" -n 50               # Read last 50 messages
telegram read "ChatName" --since "1h"        # Messages from last hour
telegram read @username -n 20                # Read DM with user
telegram search "query" --chat "ChatName"    # Search within chat
telegram search "query" --all                # Search all chats

Writing

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 admins "GroupName"                  # List admins only
telegram groups --admin                      # Groups where you're admin

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

Status

telegram whoami                              # Show logged-in account
telegram check                               # Verify session

Output Formats

All commands support --json for structured output suitable for processing:

telegram inbox --json                        # JSON format
telegram read "Chat" --json                  # JSON with messages array
telegram chats --json                        # JSON with chat list

Examples

Check inbox:

telegram inbox

Read recent messages from a chat:

telegram read "MetaDAO Community" -n 20

Search for a topic:

telegram search "futarchy" --chat "MetaDAO"

Send a message:

telegram send @username "Hello, checking in!"

Notes

• Chat names can be partial matches (e.g., "MetaDAO" matches "MetaDAO Community")
• Usernames must start with @ (e.g., @username)
• Messages are returned in reverse chronological order (newest first)
• The --since flag accepts formats like "1h", "30m", "7d"