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

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#

bash

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#

markdown

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

bash

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

Messaging#

CommandDescriptionsend <chat> <msg>Send messageforward <from> <to> <msg_id>Forward a messageedit <chat> <msg_id> <text>Edit a messagedelete <chat> <msg_id>Delete a messagepin <chat> <msg_id>Pin a messageunpin <chat> [msg_id]Unpin message (or all)read <chat>Mark chat as readsendfile <chat> <file> [--caption text]Send file or imagedownload <chat> <msg_id> [-o path]Download mediacallback <chat> <msg_id> <data>Click inline buttontyping <chat>Send typing status

Search & Browse#

CommandDescriptionchats [limit]List chatshistory <chat> [limit]Chat historysearch <query>Search chats and userssearch-msg <chat> <query> [--limit N]Search messages in chatcontactsList contactsmembers <chat> [limit]List group/channel memberschatinfo <chat>Get chat/user detailsresolve <username>Resolve username to IDresolvephone <phone>Resolve phone to user

Group & Channel Management#

CommandDescriptioncreategroup <title> <user1> [user2...]Create a groupcreatechannel <title> [about]Create a channeljoin <link_or_username>Join group/channelleave <chat>Leave group/channelkick <chat> <user>Kick userinvite <chat> <user>Invite usereditadmin <chat> <user> [--remove]Set/remove adminstartbot <chat> <bot> [param]Start bot in chat

User & Account#

CommandDescriptionloginLogin (phone + code + optional 2FA)meCurrent user infoupdateprofile [--first n] [--last n] [--about t]Update profilesetstatus <online|offline>Set online statusblock <user>Block userunblock <user>Unblock userlisten [--user id] [--chat id]Listen for messageslogoutLogout

Multi-Account (--profile)#

bash

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