telegram

Category: Tools & Productivity | Uploader: skillhq | Downloads: 0 | Version: v1.0（Latest）

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.

Changelog: Source: GitHub https://github.com/skillhq/telegram

Directory Structure

Current level: Root

📁 .github/
- 📁 workflows/
  - 📄 ci.yml 315 B
  - 📄 publish.yml 525 B
📁 scripts/
- 📄 publish-skill.sh 2.3 KB
📁 src/
- 📁 commands/
  - 📄 auth.ts 731 B
  - 📄 chats.ts 1.5 KB
  - 📄 check.ts 1.0 KB
  - 📄 contact.ts 1.4 KB
  - 📄 folder-add.ts 926 B
  - 📄 folder-remove.ts 956 B
  - 📄 folder.ts 1.0 KB
  - 📄 folders.ts 1004 B
  - 📄 groups.ts 1.5 KB
  - 📄 inbox.ts 1.5 KB
  - 📄 index.ts 954 B
  - 📄 kick.ts 1.3 KB
  - 📄 logout.ts 1.0 KB
  - 📄 members.ts 2.5 KB
  - 📄 mute.ts 922 B
  - 📄 read.ts 2.5 KB
  - 📄 reply.ts 1.7 KB
  - 📄 search.ts 1.9 KB
  - 📄 send.ts 1.5 KB
  - 📄 sync.ts 3.4 KB
  - 📄 unmute.ts 818 B
  - 📄 whoami.ts 1.2 KB
- 📁 formatters/
  - 📄 index.ts 358 B
  - 📄 json.ts 94 B
  - 📄 markdown.ts 3.7 KB
  - 📄 plain.ts 6.1 KB
- 📄 audit.ts 825 B
- 📄 auth.ts 2.1 KB
- 📄 client.ts 29.9 KB
- 📄 config.ts 4.3 KB
- 📄 index.ts 1.6 KB
📄 .clawdhubignore 284 B
📄 .gitignore 143 B
📄 CLAUDE.md 748 B
📄 package-lock.json 29.6 KB
📄 package.json 1.1 KB
📄 README.md 3.3 KB
📄 SKILL.md 6.6 KB
📄 tsconfig.json 481 B

SKILL.md

---
name: telegram
description: 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.
---

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

```bash
npm install -g @skillhq/telegram
```

## 🔐 Authentication

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

```bash
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
```bash
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
```bash
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
```bash
telegram send @username "message"            # Send DM
telegram send "GroupName" "message"          # Send to group
telegram reply "ChatName" 12345 "response"   # Reply to message ID
```

### Contacts & Groups
```bash
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
```bash
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
```bash
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
```bash
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    |

```bash
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:
```bash
telegram inbox
```

Read recent messages from a group:
```bash
telegram read "MetaDAO Community" -n 20
```

Get messages from the last 2 hours:
```bash
telegram read "Project Chat" --since "2h"
```

Search for a topic across all chats:
```bash
telegram search "futarchy" --all
```

Search within a specific chat:
```bash
telegram search "deadline" --chat "Work Team"
```

Send a message:
```bash
telegram send @username "Hello, checking in!"
```

Export a chat's history:
```bash
telegram sync --chat "Project Chat" --days 14 --output ~/exports
```

Filter chats by type:
```bash
telegram chats --type channel --json
```

Kick a user from a group:
```bash
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

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

Directory Structure

SKILL.md

Report

Notice