Telegram Telethon CLI

Manage Telegram via tgctl-telethon CLI (Python/Telethon) - send/forward/edit/delete/pin messages, search, list chats/members, join/leave groups, kick/invite users, block/unblock, send files, download media, start bots, create groups/channels, manage admins, update profile, listen for messages. Use when user asks to interact with Telegram as a user account (not bot API). Powered by Telethon (MTProto).

Audits

Warn

ClawScanWarn

Agentic behavior and permission review.

Static analysisPass

Pattern checks against bundled files.

VirusTotalPass

Multi-engine malware detections and file reputation.

Install

openclaw skills install telegram-telethon

Telegram CLI (tgctl-telethon)

User-account-level Telegram management via Python + Telethon. Drop-in replacement for the Go-based tgctl with the same CLI interface.

First-Time Setup

Step 1: Install

bash <skill-dir>/scripts/install.sh

This installs telethon via pip and copies tgctl-telethon to ~/.local/bin/.

Step 2: Get API credentials

Ask the user to go to https://my.telegram.org → API Development → get api_id and api_hash.

Step 3: Login

TELEGRAM_API_ID=${ID} TELEGRAM_API_HASH=${HASH} tgctl-telethon login

User enters phone number, auth code (digits only, no spaces), and optional 2FA password interactively.

Important: Auth codes must NOT be sent via Telegram (will be invalidated).

Step 4: Save config to TOOLS.md

### tgctl-telethon (Telegram CLI)
- Binary: ~/.local/bin/tgctl-telethon
- Env: TELEGRAM_API_ID=${ID} TELEGRAM_API_HASH=${HASH}
- Session: ~/.tgctl-telethon/

Prerequisites

Python 3.9+
telethon pip package
TELEGRAM_API_ID and TELEGRAM_API_HASH env vars
Session persists in ~/.tgctl-telethon/<profile>/

Commands

TELEGRAM_API_ID=${ID} TELEGRAM_API_HASH=${HASH} tgctl-telethon [--profile <name>] <command>

Messaging

Command	Description
`send <chat> <msg>`	Send message
`forward <from> <to> <msg_id>`	Forward a message
`edit <chat> <msg_id> <text>`	Edit a message
`delete <chat> <msg_id>`	Delete a message
`pin <chat> <msg_id>`	Pin a message
`unpin <chat> [msg_id]`	Unpin message (or all)
`read <chat>`	Mark chat as read
`sendfile <chat> <file> [--caption text]`	Send file or image
`download <chat> <msg_id> [-o path]`	Download media
`callback <chat> <msg_id> <data>`	Click inline button
`typing <chat>`	Send typing status

Search & Browse

Command	Description
`chats [limit]`	List chats
`history <chat> [limit]`	Chat history
`search <query>`	Search chats and users
`search-msg <chat> <query> [--limit N]`	Search messages in chat
`contacts`	List contacts
`members <chat> [limit]`	List group/channel members
`chatinfo <chat>`	Get chat/user details
`resolve <username>`	Resolve username to ID
`resolvephone <phone>`	Resolve phone to user

Group & Channel Management

Command	Description
`creategroup <title> <user1> [user2...]`	Create a group
`createchannel <title> [about]`	Create a channel
`join <link_or_username>`	Join group/channel
`leave <chat>`	Leave group/channel
`kick <chat> <user>`	Kick user
`invite <chat> <user>`	Invite user
`editadmin <chat> <user> [--remove]`	Set/remove admin
`startbot <chat> <bot> [param]`	Start bot in chat

User & Account

Command	Description
`login`	Login (phone + code + optional 2FA)
`me`	Current user info
`updateprofile [--first n] [--last n] [--about t]`	Update profile
`setstatus <online\|offline>`	Set online status
`block <user>`	Block user
`unblock <user>`	Unblock user
`listen [--user id] [--chat id]`	Listen for messages
`logout`	Logout

Multi-Account (--profile)

tgctl-telethon --profile work login
tgctl-telethon --profile work me

Sessions stored in ~/.tgctl-telethon/<profile>/.

Chat ID Format

User: Positive ID (e.g. 8568316820)
Group/Channel: Negative ID (e.g. -3842028710)
@username: Use directly (e.g. @BotFather)

Security

All credentials via environment variables, never stored in code
Session files stored locally in ~/.tgctl-telethon/, never transmitted
Login requires interactive user input
Auth codes must NOT be sent via Telegram
Communicates only with official Telegram servers