Telegram CLI - Setup Guide¶
Source: skillhq/telegram (425 installs) Category: Communication / Messaging Quality Tier: 🔵 Community
A native Telegram CLI using the MTProto protocol - not the Bot API. This means full access to your Telegram account: read messages, search across all chats, send DMs and group messages, manage group members, mute chats, export history, and organize folders. Much more powerful than bot-only access for Hermes agents that need full Telegram account capabilities.
Installation¶
npm install -g @skillhq/telegram
Prerequisites¶
| Requirement | Details |
|---|---|
| Telegram Account | A registered Telegram account (phone number) |
| API Credentials | Get api_id and api_hash from my.telegram.org/apps |
Key Capabilities¶
Authentication¶
telegram auth # First-time login (prompts for api_id, api_hash, phone, code)
telegram check # Verify session is valid
telegram whoami # Show logged-in account
telegram whoami --json # Account info as JSON
telegram logout # Clear saved session
Reading Messages¶
telegram inbox # Unread messages summary
telegram chats # List all chats
telegram chats --type group # Filter: user, group, supergroup, channel
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
Searching¶
telegram search "query" --chat "ChatName" # Search within a specific chat
telegram search "query" --all # Search all chats globally
telegram search "query" -n 20 # Limit results
Sending Messages¶
telegram send @username "Hello" # Send DM
telegram send "GroupName" "Message" # Send to group
telegram reply "ChatName" 12345 "Response" # Reply to specific message ID
Group Management¶
telegram members "GroupName" # List members
telegram members "GroupName" -n 500 # Fetch up to 500 members
telegram admins "GroupName" # List admins only
telegram mute "GroupName" # Mute noisy group
telegram unmute "GroupName" # Unmute
telegram kick "GroupName" @user # Remove user
telegram promote "GroupName" @user # Promote to admin
Contacts & History¶
telegram contact @username # Get contact info
telegram export "ChatName" --format json # Export chat history
telegram folders # List chat folders
Quick Start - Hermes Agent¶
# Install
npm install -g @skillhq/telegram
# First-time setup (requires api_id + api_hash from my.telegram.org)
telegram auth
# Verify
telegram whoami
# Check unread
telegram inbox
# Monitor CorpusIQ Team topic
telegram read "CorpusIQ Team" -n 10
Verification¶
telegram check && echo "Telegram CLI: OK"
telegram whoami --json | python3 -c "import json,sys; d=json.load(sys.stdin); print(f'Logged in as: {d.get(\"first_name\",\"?\")}')"
Notes¶
- MTProto, not Bot API: Full account access - read all chats, send as yourself, manage groups. Much more powerful than bot-only Telegram access
- First-time auth: Requires API credentials from my.telegram.org (one-time setup per account)
- Session persistence: Session saved locally after
telegram auth- no re-authentication needed - Use case for CorpusIQ: Monitor CorpusIQ Team forum, read Topic 2 messages programmatically, send alerts, export chat history for analysis
- Pitfall: Not for bot accounts - use Telegram Bot API for @corpusiq_bot. This is for human account access
- Related skills: telegram-bot-builder (if using bot API), corpusiq-inbound-communication-monitoring
Integration with CorpusIQ¶
CorpusIQ is the connector layer that lets AI assistants read the systems a business already runs on - accounting, payments, CRM, email, files and analytics - and answer with the source named. It is read-only by design: it retrieves data and never writes to, or acts in, a connected system, which is what makes it safe to point at live accounts.
This page is part of the CorpusIQ directory, the reference we maintain for the MCP server and agent-skill ecosystem. Run alongside CorpusIQ, a third-party server like this one can be combined with a company's own business data in a single answer.