by skillhq

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.

Installs: 476
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/skillhq/telegram --skill telegram

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads telegram automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

📬 Telegram CLI

Q: How do I install telegram?

Run npx skills add https://github.com/skillhq/telegram --skill telegram in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/telegram/ (personal) or .claude/skills/telegram/ (project).

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

FAQ

What does the telegram skill do?

How do I install telegram?

Run npx skills add https://github.com/skillhq/telegram --skill telegram in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/telegram/ (personal) or .claude/skills/telegram/ (project).

Which AI agents can use telegram?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is telegram safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains telegram?

It is published by skillhq in skillhq/telegram. It has 476 recorded installs.

Popular other skills

View category →

hyperframes-cli

heygen-com/hyperframes

The HyperFrames CLI by job - scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history - plus reading its JSON and recovering from build or render failures.

1.3M installs

triage

mattpocock/skills

Move issues and external PRs through a state machine of triage roles, categorise, verify, grill if needed, and write agent-ready briefs.

1M installs

ask-matt

mattpocock/skills

Ask which skill or flow fits your situation. A router over the skills in this repo.

778.4K installs

to-questionnaire

mattpocock/skills

Turn a decision you can't fully answer into a questionnaire for someone else to fill in.

508.9K installs

wait-what

mattpocock/skills

Stop. That last message did not land: re-pitch it.

459.7K installs

loop-me

mattpocock/skills

Grill me about specs for the workflows I want to build, within this workspace.

447.9K installs

telegram

Install

Install

Describe the task

Review the result

SKILL.md

📬 Telegram CLI

🎯 When to Use

📦 Install

🔐 Authentication

📖 Commands

Reading Messages

Searching

Sending Messages

Contacts & Groups

Muting

Folders

Sync / Export

📤 Output Formats

📎 Media Metadata

🤖 AI Agent Guidance

💡 Examples

📝 Notes

FAQ

Popular other skills

hyperframes-cli

triage

ask-matt

to-questionnaire

wait-what

loop-me