Установка
Требования
- Python 3.13 (зафиксирован в
.python-version). - uv — менеджер пакетов и окружений.
- Аккаунт Telegram и доступ к https://my.telegram.org для получения
api_id/api_hash(см. 02. Авторизация).
Рекомендуемый способ: глобальная установка из GitHub
tguser — это инструмент, а не библиотека: его запускают из любой директории, в том числе
ИИ-агенты, у которых рабочий каталог заранее неизвестен. Поэтому основной способ установки —
uv tool install прямо из репозитория, без клонирования:
uv tool install git+https://github.com/yerza06/tguser-cli.gituv сам скачает исходники, соберёт пакет и поставит его в изолированное окружение.
Исходный код репозитория при этом нигде не остаётся — только собранный инструмент.
Можно закрепиться на конкретной ветке или теге:
uv tool install git+https://github.com/yerza06/tguser-cli.git@dev # ветка
uv tool install git+https://github.com/yerza06/tguser-cli.git@v1.0.1 # тегПосле этого команда доступна просто как tguser — без uv run и без привязки к каталогу репозитория:
cd ~/любая/директория
tguser --version # tguser 1.0.1Что делает uv tool install
uv tool — это менеджер «инструментов» (аналог pipx). Команда uv tool install:
- Собирает пакет из указанного источника — локальной директории (
.— корень проекта сpyproject.toml) или Git-репозитория (git+https://…). - Создаёт отдельное изолированное окружение для
tguserв~/.local/share/uv/tools/tguser/. Зависимости (Kurigram, Typer, SQLAlchemy и др.) ставятся туда и не смешиваются ни с системным Python, ни с окружениями других проектов. - Кладёт исполняемый файл
tguserв~/.local/bin/— этот путь берётся из секции[project.scripts]вpyproject.toml(tguser = "tguser.cli:main"). - Благодаря тому, что
~/.local/binесть вPATH, командаtguserработает из любой директории.
Важно: изолированное окружение относится только к коду и зависимостям. Данные (.env с
api_id/api_hash, файл сессии и база чатов) лежат в ~/.config/tguser/ и общие для любого
способа запуска — см. 03. Конфигурация. Поэтому после uv tool install
повторно авторизовываться не нужно, если вы уже входили через uv run tguser login.
Проверка
which tguser # /home/<user>/.local/bin/tguser
tguser --version # tguser 1.0.1
tguser version # версия + окружение (см. ниже)
tguser --help # дерево всех команд
uv tool list # показать все установленные через uv инструментыЕсли вывод --help показывает команды login, chat, send, sendphoto и т.д. — установка
прошла успешно.
tguser version — более полная проверка: кроме версии она показывает, где лежит конфигурация и
выполнен ли вход в аккаунт. Это самый быстрый способ описать своё окружение в баг-репорте:
$ tguser version
╭──────────────────────────── Информация о версии ─────────────────────────────╮
│ Версия: 1.0.1 │
│ Python: 3.13.11 │
│ Kurigram: 2.2.23 │
│ Конфигурация: /home/user/.config/tguser │
│ Сессия: есть │
│ Учётные данные: заданы │
│ Язык: ru │
╰──────────────────────────────────────────────────────────────────────────────╯
Сессия: нет или Учётные данные: не заданы означают, что вход в аккаунт ещё не выполнен — см.
02. Авторизация. Команда только читает и никогда не создаёт каталог
конфигурации.
Если после установки терминал отвечает
tguser: command not found, значит~/.local/binне вPATH. Выполнитеuv tool update-shellи перезапустите терминал (см. 07. Решение проблем).
Обновление и удаление
# установлено из GitHub — подтянуть свежую версию
uv tool install git+https://github.com/yerza06/tguser-cli.git --force
# установлено из клона — переустановить после изменений в коде
uv tool install . --force
uv tool uninstall tguser # удалить инструментuv tool install копирует код в момент установки, поэтому новые коммиты (или правки в клоне) не
попадают в уже установленный инструмент автоматически — нужна переустановка с --force.
Альтернатива для разработки — установить клон в editable-режиме, тогда изменения подхватываются
сразу, без переустановки:
uv tool install -e .Альтернатива: установка из клона репозитория
Если вы хотите иметь исходники под рукой (читать код, вносить правки, запускать тесты):
git clone https://github.com/yerza06/tguser-cli.git
cd tguser-cli
uv tool install . # из корня проектаРезультат тот же самый — глобальная команда tguser из любой директории; разница только в том,
откуда берутся исходники.
Для разработки: запуск из репозитория
Если вы разрабатываете сам tguser и не хотите ставить его глобально, достаточно склонировать
репозиторий и синхронизировать зависимости:
git clone https://github.com/yerza06/tguser-cli.git
cd tguser-cli
uv syncКоманда создаст виртуальное окружение .venv/, установит все зависимости из pyproject.toml
и сам пакет tguser в editable-режиме. Запуск — с префиксом uv run и только изнутри
репозитория (из корня или его подкаталогов):
uv run tguser <команда> [аргументы]В остальной документации команды записаны просто как tguser … — в расчёте на глобальную установку.
Что дальше
Перейдите к 02. Авторизация, чтобы войти в свой Telegram-аккаунт.