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

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 --chat "ChatName"

Sync specific chat only

telegram sync --output ~/exports

Custom output directory

📤 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

🤖 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

) should be confirmed with the user before executing

Rate limiting

avoid rapid successive calls; the Telegram API has rate limits

Large groups

use -n to limit members output on very large groups 💡 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 history: telegram sync --chat "Project Chat" --days 14 --output ~/exports Filter chats by type: telegram chats --type channel --json Kick a user from a group: telegram kick "My Group" @spammer 📝 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