Перейти к содержимому
Конфигурация

Конфигурация

tguser настраивается через переменные окружения (Pydantic-Settings) с префиксом TGUSER_.

Переменные окружения

ПеременнаяПо умолчаниюОписание
TGUSER_API_ID—api_id с my.telegram.org
TGUSER_API_HASH—api_hash с my.telegram.org
TGUSER_PHONE_NUMBER—Номер телефона для login (если не задан — спросит интерактивно)
TGUSER_CONFIG_DIR~/.config/tguserКаталог для сессии, БД и .env
TGUSER_SESSION_NAMEtguserИмя сессии (имя файла <name>.session)
TGUSER_LANGenЯзык вывода CLI: en или ru

Язык интерфейса

По умолчанию CLI (--help, сообщения, ошибки) выводится на английском. Чтобы переключить на русский, задайте TGUSER_LANG=ru — через переменную окружения или в .env:

export TGUSER_LANG=ru
tguser --help          # справка на русском

Неизвестное значение откатывается к английскому.

Источники настроек и приоритет

Настройки читаются из двух источников (более высокий приоритет — у переменных окружения):

  1. Переменные окружения TGUSER_*.
  2. Файл ~/.config/tguser/.env.

Пример .env (см. также .env.example в корне проекта):

TGUSER_API_ID=1234567
TGUSER_API_HASH=0123456789abcdef0123456789abcdef
# TGUSER_PHONE_NUMBER=+79991234567
# TGUSER_CONFIG_DIR=~/.config/tguser
# TGUSER_SESSION_NAME=tguser

Расположение файлов

Все рабочие файлы лежат в TGUSER_CONFIG_DIR (по умолчанию ~/.config/tguser/):

ФайлНазначение
.envapi_id/api_hash/номер телефона (создаётся командой login, права 0600)
tguser.sessionФайл сессии Kurigram
tguser.dbБаза SQLite с именованными чатами

Благодаря единому каталогу конфигурации команду tguser можно запускать из любой директории — сессия и база чатов находятся всегда в одном месте.

⚠️ Файлы tguser.session и tguser.db нельзя удалять

Это рабочее состояние инструмента, а не кэш и не временные файлы. tguser нигде их не дублирует, резервных копий не делает и восстановить их автоматически не может. Не удаляйте эти файлы, не переносите их вручную и не чистите ~/.config/tguser/ «на всякий случай».

tguser.session — файл сессии Telegram

Что это. SQLite-файл Kurigram, который создаётся при tguser login. В нём лежит ключ авторизации (auth key), выданный сервером Telegram после ввода телефона и кода, номер дата-центра и кэш известных чатов (peer cache). Именно этот файл делает вас авторизованным пользователем: без него библиотека не может подключиться к Telegram от вашего имени.

Зачем нужен. Пока файл существует и действителен, повторный вход не требуется — tguser send, sendphoto и остальные команды работают сразу, без телефона и кода. Для ИИ-агента это критично: он не может пройти интерактивную авторизацию сам.

Что будет, если удалить. Любая команда, требующая подключения (send*, whoami, dialogs, resolve), завершится ошибкой «нет активной сессии». Придётся заново выполнить tguser login и ввести номер телефона, код из Telegram и, если включена двухфакторная защита, облачный пароль — то есть нужен человек. Сами сообщения и чаты при этом не теряются, они на серверах Telegram.

Отдельно: удаление файла не завершает сессию на стороне Telegram — она останется в списке активных устройств вашего аккаунта, но управлять ею из CLI вы уже не сможете. Правильный способ выйти — tguser logout: он завершает сессию на сервере и только потом удаляет файл.

tguser.db — база именованных чатов

Что это. База SQLite с единственной таблицей chats: имя alias, идентификатор чата (-100…, @username или me), название чата и дата создания записи. Файл наполняется командой tguser chat add.

Зачем нужен. Это ваш «адресный справочник» — он позволяет писать --to work вместо --to -1001234567890. Именно на него рассчитаны скрипты и промпты ИИ-агентов: у агента в инструкции записано понятное имя чата, а не числовой ID.

Что будет, если удалить. При следующем запуске файл будет создан заново — но пустым. Все сохранённые alias исчезнут, а команды вида tguser send "текст" --to work начнут отправлять сообщение по значению work как по «сырому» идентификатору и падать с ошибкой. Автоматически восстановить справочник нельзя: Telegram не хранит ваши локальные имена. Придётся заново находить ID (tguser dialogs, tguser resolve) и добавлять alias руками — а все скрипты и агенты, которые ссылались на эти имена, до тех пор будут сломаны.

Резервная копия

Достаточно скопировать весь каталог конфигурации — там же лежит .env с api_id/api_hash:

cp -r ~/.config/tguser ~/backup/tguser-config

Копию делайте, когда tguser не запущен, и храните её в надёжном месте: файл сессии и .env дают полный доступ к вашему аккаунту Telegram. Восстановление — обратное копирование файлов в ~/.config/tguser/.

Если нужно проверить что-то в изоляции, не трогайте основной каталог — заведите отдельный профиль через TGUSER_CONFIG_DIR (см. ниже).

Отдельное окружение

Чтобы использовать другой аккаунт или изолированную базу (например, для тестов), задайте свой каталог:

export TGUSER_CONFIG_DIR=/path/to/another/profile
tguser login