Перейти к содержимому
Установка

Установка

Требования

  • 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.git

uv сам скачает исходники, соберёт пакет и поставит его в изолированное окружение. Исходный код репозитория при этом нигде не остаётся — только собранный инструмент.

Можно закрепиться на конкретной ветке или теге:

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:

  1. Собирает пакет из указанного источника — локальной директории (. — корень проекта с pyproject.toml) или Git-репозитория (git+https://…).
  2. Создаёт отдельное изолированное окружение для tguser в ~/.local/share/uv/tools/tguser/. Зависимости (Kurigram, Typer, SQLAlchemy и др.) ставятся туда и не смешиваются ни с системным Python, ни с окружениями других проектов.
  3. Кладёт исполняемый файл tguser в ~/.local/bin/ — этот путь берётся из секции [project.scripts] в pyproject.toml (tguser = "tguser.cli:main").
  4. Благодаря тому, что ~/.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-аккаунт.