A secure, read-only command-line interface for Telegram that utilizes the MTProto protocol to fetch messages, media, and chat data without Bot API limitations.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install tg-mtproto-cli
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install tg-mtproto-cli using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is Telegram MTProto CLI (tg-cli)?
The tg-cli skill is a specialized technical tool designed for high-performance interaction with Telegram via the MTProto protocol. Unlike standard bot-based solutions, this skill allows users to access Telegram data as a regular user, providing deeper access to chat histories, media, and account metadata while maintaining a strict read-only architecture.
Integrating this tool into Openclaw Skills enables developers to automate complex data extraction tasks, archive communication logs, and manage multiple Telegram sessions directly from the terminal. It prioritizes security by using system keychains for credential storage and ensures that no write operations are ever performed on the Telegram account, making it a safe choice for research and automation.
Telegram MTProto CLI (tg-cli) Use Cases
- Extracting and archiving chat histories from private groups or public channels for data analysis.
- Automated media retrieval and downloading of attachments like photos and documents from specific threads.
- Searching and monitoring multiple Telegram accounts simultaneously for specific keywords using JSON output.
- Creating developer workflows that pipe Telegram message data into other CLI tools or processing pipelines.
How Telegram MTProto CLI (tg-cli) Works
- The skill initiates an authentication flow using Telegram API credentials (api_id and api_hash) to establish a secure MTProto session.
- Upon successful authentication, the tool generates local SQLite session files to maintain persistent access without re-entering OTPs.
- The user executes commands to query chat lists, forum topics, or message batches from the Telegram Data Center (DC) servers.
- The skill fetches the requested data and outputs it in either a human-readable format or structured JSON for programmatic consumption.
- If media is requested, the skill handles the multi-part download process and saves the files to a designated local directory.
Telegram MTProto CLI (tg-cli) Setup
To integrate this capability into your Openclaw Skills environment, you must install the required binaries and authenticate your account:
npm install -g tg-mtproto-cli
# Optional: Install jq for advanced JSON filtering
brew install jq
Once installed, run the interactive authentication command:
tg auth
You will need your API credentials from my.telegram.org to complete the setup.
Telegram MTProto CLI (tg-cli) Data Schema & Taxonomy
The skill produces structured data primarily in JSON format. The core message object includes the following fields:
| Property | Type | Description |
|---|---|---|
id |
Number | Unique identifier for the message |
chatId |
Number | Numeric ID (negative for groups/channels) |
senderName |
String | Name of the message author |
text |
String | Content of the message |
media |
Object | Metadata regarding attachments (type, size, mimeType) |
date |
String | ISO 8601 formatted timestamp |
Local session data is stored in ~/.tg-mtproto-cli/sessions/ using SQLite database files.
Telegram MTProto CLI (tg-cli) Advanced Features
- Multi-account support allowing users to switch between personal and professional aliases seamlessly.
- Advanced date-based filtering using the --after flag for targeted history extraction.
- Full support for Telegram Forum Topics, allowing for granular message retrieval within large communities.
- Read-only safety guardrails that prevent any accidental sending or deletion of Telegram data.
- Comprehensive JSON output mode for every command, making it highly compatible with Openclaw Skills automation scripts.
SKILL.md
Loading
Related Openclaw Skills
Grok Image CLI
A secure command-line tool for generating and editing high-quality images using the xAI Grok API models.
Claude Usage CLI
A command-line interface for monitoring Anthropic Admin API usage and spend directly from your terminal.
claude-cost-cli
A secure macOS command-line tool for auditing Anthropic Admin API usage and token costs with Keychain integration.
CalDAV CLI
A comprehensive command-line interface for managing multiple CalDAV calendar accounts with secure OS keychain integration and JSON output support.
PMP-Agentclaw
An AI-powered project management assistant that automates planning, risk assessment, and performance tracking using professional PMP methodologies.
MOPO Texas Hold'em Player Strategy (ABC)
A high-performance AI player skill for MOPO Texas Hold'em using ABC strategy baselines and real-time state management.
Featured*
