---
name: telegram-telethon
description: 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).
---

# 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

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

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