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

Commands

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

Messaging

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

Search & Browse

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

Group & Channel Management

Command Description

--------- -------------

creategroup  <user1> [user2...]</code></td><td>Create a group</td></tr><tr><td><code>createchannel <title> [about]</code></td><td>Create a channel</td></tr><tr><td><code>join <link_or_username></code></td><td>Join group/channel</td></tr><tr><td><code>leave <chat></code></td><td>Leave group/channel</td></tr><tr><td><code>kick <chat> <user></code></td><td>Kick user</td></tr><tr><td><code>invite <chat> <user></code></td><td>Invite user</td></tr><tr><td><code>editadmin <chat> <user> [--remove]</code></td><td>Set/remove admin</td></tr><tr><td><code>startbot <chat> <bot> [param]</code></td><td>Start bot in chat</td></tr></tbody></table><h3>User & Account</h3><table><thead><tr><th>Command</th><th>Description</th></tr></thead><tbody><tr><td>---------</td><td>-------------</td></tr><tr><td><code>login</code></td><td>Login (phone + code + optional 2FA)</td></tr><tr><td><code>me</code></td><td>Current user info</td></tr><tr><td><code>updateprofile [--first n] [--last n] [--about t]</code></td><td>Update profile</td></tr><tr><td>`setstatus <online\</td><td>offline>`</td><td>Set online status</td></tr><tr><td><code>block <user></code></td><td>Block user</td></tr><tr><td><code>unblock <user></code></td><td>Unblock user</td></tr><tr><td><code>listen [--user id] [--chat id]</code></td><td>Listen for messages</td></tr><tr><td><code>logout</code></td><td>Logout</td></tr></tbody></table><h2>Multi-Account (--profile)</h2><pre><code>tgctl-telethon --profile work login
tgctl-telethon --profile work me
</code></pre><p>Sessions stored in <code>~/.tgctl-telethon/<profile>/</code>.</p><h2>Chat ID Format</h2><ul><li><strong>User</strong>: Positive ID (e.g. <code>8568316820</code>)</li><li><strong>Group/Channel</strong>: Negative ID (e.g. <code>-3842028710</code>)</li><li><strong>@username</strong>: Use directly (e.g. <code>@BotFather</code>)</li></ul><h2>Security</h2><ul><li>All credentials via environment variables, never stored in code</li><li>Session files stored locally in <code>~/.tgctl-telethon/</code>, never transmitted</li><li>Login requires interactive user input</li><li>Auth codes must NOT be sent via Telegram</li><li>Communicates only with official Telegram servers</li></ul></div>
                            </div>
        </div>

        <div id="tab-versions" class="detail-content">
            <div class="detail-section">
                <h2>版本历史</h2>
                                <p style="margin-bottom:12px;font-size:14px;color:#94a3b8;">共 1 个版本</p>
                <ul class="version-list">
                                        <li>
                        <div>
                            <span class="version-tag">v1.0.0</span>
                                                        <span style="font-size:11px;color:#5b6abf;margin-left:8px;background:#eef0ff;padding:1px 8px;border-radius:10px;">当前</span>                        </div>
                        <div style="font-size:12px;color:#94a3b8;">
                            2026-05-07 09:30                             安全 安全                        </div>
                    </li>
                                    </ul>
                            </div>
        </div>

        <div id="tab-security" class="detail-content">
            <div class="detail-section">
                <h2>安全检测</h2>
                                <div class="sec-grid">                    <div class="sec-card">
                        <h4>腾讯云安全 (Keen)</h4>
                        <div class="sec-status sec-safe">
                            安全，无风险                        </div>
                        <a href="https://tix.qq.com/search/skill?keyword=2410368d0456ff33a4fd0e7ffa81ad6c" target="_blank">查看报告</a>                    </div>
                                    <div class="sec-card">
                        <h4>腾讯云安全 (Sanbu)</h4>
                        <div class="sec-status sec-safe">
                            安全，无风险                        </div>
                        <a href="https://static.cloudsec.tencent.com/html-report-v2/2026/05/26/440397_d4054c6e1b0e4debe7488cf4c48cdc59.html?q-sign-algorithm=sha1&q-ak=AKID8JMG1bzBC1dz96qNhssfFftujT1NCoFi&q-sign-time=1781530688%3B1813066688&q-key-time=1781530688%3B1813066688&q-header-list=host&q-url-param-list=&q-signature=1521edbe9597fcd7e99e119defe6e64ec7e5c580" target="_blank">查看报告</a>                    </div>
                </div>
                            </div>
        </div>

        <!-- Recommended Skills -->
                <div style="margin-top:24px;">
            <h2 style="font-size:18px;font-weight:600;margin-bottom:16px;">🔗 相关推荐</h2>
            <div class="rec-grid">
                                <div class="rec-card">
                    <span class="badge-cat" style="margin-bottom:8px;display:inline-block;">ai-agent</span>
                    <h3><a href="/s/self-improving">Self-Improving + Proactive Agent</a></h3>
                    <div class="rec-owner">ivangdavila</div>                    <div class="rec-desc">自我反思+自我批评+自我学习+自组织记忆。智能体评估自身工作、发现错误并持续改进。</div>
                    <div class="rec-stats">
                        <span style="color:#f39c12;">★ 1,378</span>
                        <span style="color:#5b6abf;">📥 320,410</span>
                    </div>
                </div>
                                <div class="rec-card">
                    <span class="badge-cat" style="margin-bottom:8px;display:inline-block;">dev-programming</span>
                    <h3><a href="/s/github">Github</a></h3>
                    <div class="rec-owner">steipete</div>                    <div class="rec-desc">使用 `gh` CLI 与 GitHub 交互，通过 `gh issue`、`gh pr`、`gh run` 和 `gh api` 管理议题、PR、CI 运行及高级查询。</div>
                    <div class="rec-stats">
                        <span style="color:#f39c12;">★ 676</span>
                        <span style="color:#5b6abf;">📥 325,416</span>
                    </div>
                </div>
                                <div class="rec-card">
                    <span class="badge-cat" style="margin-bottom:8px;display:inline-block;">ai-agent</span>
                    <h3><a href="/s/skill-vetter">Skill Vetter</a></h3>
                    <div class="rec-owner">spclaudehome</div>                    <div class="rec-desc">AI智能体技能安全预审工具。安装ClawdHub、GitHub等来源技能前，检查风险信号、权限范围及可疑模式。</div>
                    <div class="rec-stats">
                        <span style="color:#f39c12;">★ 1,226</span>
                        <span style="color:#5b6abf;">📥 267,812</span>
                    </div>
                </div>
                            </div>
        </div>
            </div>
    <script>
    document.addEventListener('DOMContentLoaded',function(){
        document.querySelectorAll('.detail-tab').forEach(function(btn){
            btn.addEventListener('click',function(e){
                var tab = this.getAttribute('data-tab');
                document.querySelectorAll('.detail-tab').forEach(function(b){b.classList.remove('active')});
                document.querySelectorAll('.detail-content').forEach(function(c){c.classList.remove('active')});
                this.classList.add('active');
                var el = document.getElementById('tab-'+tab);
                if(el) el.classList.add('active');
            });
        });
    });
    </script>
    <div class="footer">
    <p>Skill工具集 © 2026</p>
</div></body>
</html>

Telegram Telethon CLI

概述