Конфигурация
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_NAME | tguser | Имя сессии (имя файла <name>.session) |
TGUSER_LANG | en | Язык вывода CLI: en или ru |
Язык интерфейса
По умолчанию CLI (--help, сообщения, ошибки) выводится на английском. Чтобы
переключить на русский, задайте TGUSER_LANG=ru — через переменную окружения или в .env:
export TGUSER_LANG=ru
tguser --help # справка на русскомНеизвестное значение откатывается к английскому.
Источники настроек и приоритет
Настройки читаются из двух источников (более высокий приоритет — у переменных окружения):
- Переменные окружения
TGUSER_*. - Файл
~/.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/):
| Файл | Назначение |
|---|---|
.env | api_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