tgcli — Telegram CLI для своего аккаунта

tgcli — командная утилита, которая работает от имени твоего Telegram-аккаунта через MTProto (Pyrogram). Это не бот и не Bot API: это полноценный клиент, авторизованный как ты. Он умеет читать твои диалоги, искать по перепискам, отправлять сообщения и файлы, просматривать контакты и экспортировать чаты.

⚠️ Важно. tgcli — это ключ от твоего аккаунта. Всё, что он делает, Telegram видит как действия тебя. Не публикуй session-файл, не запускай на чужих машинах, не используй для спама — за злоупотребление user-bot аккаунт блокируют.

Возможности

Команда	Что делает
tgcli login	Интерактивно создаёт новую сессию (Telegram запросит код, а при включённой 2FA — также пароль; способ доставки определяет Telegram)
tgcli me	Кто ты в этой сессии
tgcli dialogs [-q фильтр]	Список последних диалогов
tgcli search "запрос"	Поиск сообщений по недавним диалогам (~последние 200, на стороне Telegram)
tgcli history <чат> [-q запрос]	История чата
tgcli send <чат> "текст"	Отправить сообщение от своего имени
tgcli send-file <чат> <путь> [-c подпись]	Отправить файл
tgcli contacts [-q фильтр]	Список контактов
tgcli find-bot "имя"	Найти ботов по имени
tgcli export <чат> out.jsonl	Экспорт истории чата в JSONL

<чат> принимает: @user, числовой id (<chat_id>) или точное название из списка диалогов.

Установка

pip install .

Зависимости: Python ≥ 3.10, Pyrogram ≥ 2.0.100.

Настройка

1. Получи api_id и api_hash на my.telegram.org/apps (нужен аккаунт Telegram; сайт может блокировать часть IP — если не открывается, попробуй другой регион).
2. Передай их через переменные окружения или .env:

export TGCLI_API_ID=<your_api_id>
export TGCLI_API_HASH=<your_api_hash>

Или создай .env в рабочей папке:

TGCLI_API_ID=<your_api_id>
TGCLI_API_HASH=<your_api_hash>
TGCLI_SESSION=<path_to_session>

3. Создай сессию (код придёт в Telegram-приложение или SMS):

tgcli login

Если код не приходит, проверь подсказки Telegram и сетевое подключение. Session-файл переноси только по защищённому каналу, ограничь права файла и удаляй лишние копии. Если подозреваешь утечку сессии — заверши её в настройках Telegram.

Примеры

# Кто я
tgcli me
# id:        <account_id>
# name:      Name (пример)
# username:  @user

# Последние диалоги
tgcli dialogs -n 10

# Найти сообщение по перепискам
tgcli search "VPN конфиг" -n 5

# История чата (по @username)
tgcli history @user -n 20

# История с фильтром
tgcli history @user -q "аренда" -n 10

# Отправить сообщение от себя (после сетевого таймаута не повторяй вслепую —
# сначала проверь историю, чтобы не создать дубль)
tgcli send @user "Привет! Файл во вложении"

# Отправить файл
tgcli send-file @user <file_path> -c "Подпись"

# Найти бота
tgcli find-bot "имя"

# Экспорт чата в JSONL
tgcli export @user <output.jsonl> -n 5000

Как это работает

• Bot API (HTTP) — отдельная сущность-бот, видит только то, что ему разрешено, не может читать твои переписки.
• MTProto + user-сессия (Pyrogram) — полноценный клиент, авторизованный как ты: get_dialogs(), search_messages(), send_message(), send_document(), get_contacts(). Session-файл хранит auth-ключи и привязку к дата-центру Telegram.

tgcli — тонкая обёртка над этими методами. Весь риск и вся ответственность — как у любого клиента твоего аккаунта.

Безопасность

• .gitignore исключает *.session, .env, кэши — но это работает только в этом репозитории. Перед коммитом проверь git status и права файлов; не храни сессию рядом с кодом.
• Не логируй и не коммить api_hash.
• Telegram API Terms of Service и общие Terms of Service ограничивают спам и массовую автоматизацию. Личное использование user-bot — на твоей ответственности: не спамь, не парь чужие чаты, не делай рассылок.
• search итерирует последние ~200 диалогов и делает поиск на стороне Telegram — на больших объёмах упрёшься в FLOOD_WAIT (утилита честно его показывает); уменьшай -n или расширяй зону поиска.

Скилл для Hermes (AI-агента)

Рядом с CLI лежит скилл для Hermes Agent (skill/SKILL.md): триггеры, команды, креды и pitfalls (FLOOD_WAIT, SQLite-lock, дубли отправки, гео-блок). Установка:

cp skill/SKILL.md <skills_dir>/tgcli/SKILL.md

После этого агент сам знает, как искать по перепискам, отправлять сообщения/файлы от твоего имени, находить контакты и ботов, экспортировать чаты — и помнит про лимиты Telegram.

Лицензия

MIT