Установка

Установите CLI через локального агента или в терминале. Это npm-пакет для Windows, macOS и Linux. Агент поможет проверить компьютер, установить CLI и войти в аккаунт.

Установить с помощью агента

Раскройте блок ниже и скопируйте запрос агенту. После входа проверьте свой аккаунт и несколько чатов. Загрузка старой истории — отдельный шаг.

Установка Telegram

Скопируйте запрос своему агенту. Он поможет установить CLI и войти в аккаунт на вашем компьютере.

Промпт

Настрой tg на моём компьютере. Сначала прочитай инструкцию: https://wirecat.dev/llms.mdx/docs/ru/installation/content.md

Проверь, что установлены Node.js 22.16+ (ветка 22.x) или 24+ и npm.

Установи через npm install -g @leemour/tg-cli (в Windows PowerShell используй npm.cmd). Проверь, что tg запускается по имени в твоём терминале и будет доступен в новых терминалах. На Windows узнай папку установки через npm.cmd prefix -g; добавь её в PATH пользователя, если её там нет, сохрани прежние записи и обнови PATH своего терминала. Не предполагай, что npm обновил уже работающий терминал. На macOS/Linux проверь npm prefix -g и подпапку bin; сохрани существующие настройки терминала. Если PowerShell блокирует созданный скрипт, используй запуск через .cmd и восстановление из инструкции без изменения постоянной политики выполнения.

До входа выполни tg skill install --for all. Прочитай tg --help, tg commands --json и tg skill show, затем загрузи и проверь установленный skill для своего агента.

Используй пошаговую настройку, если она есть в установленном cli; иначе следуй инструкции входа. Скажи, что настройка займёт около пяти минут, а скачивание истории чатов — отдельный шаг. Коды и пароли я введу локально или отсканирую QR-код.

Проверь tg --version, выполни tg doctor, проверь аккаунт после входа и покажи первые пять чатов.

Подключение агента →

Установить в терминале

Node.js 22.16+ (ветка 22.x) или 24+ с npm. После установки Node.js откройте новый терминал.

Node.js ↗

Команда

npm install -g @leemour/tg-cli
tg skill install --for all
tg --version
tg doctor

Windows: одна команда PowerShell устанавливает CLI и навык агента, сохраняет PATH пользователя, обновляет текущий терминал и проверяет запуск. PATH вручную менять не нужно:

Команда

& ([scriptblock]::Create((Invoke-RestMethod 'https://wirecat.dev/install.ps1'))) -Tool tg -Agent all

Войти в аккаунт

Команда

tg setup --agent all

Настройка Telegram проверяет аккаунт и пять чатов, устанавливает навыки агентов; история скачивается отдельно. Режим auto получает app ID и hash за вас. Введите код из Telegram в терминале, затем отсканируйте QR: Настройки → Устройства → Подключить устройство. Если auto не сработал, используйте session start --app browser.

Команда

tg account show
tg chats list --limit 5
tg inbox --limit 5

Документация →

На настройку заложите около 5 минут. Скачивание истории чатов — отдельный шаг, который может занять больше времени.

Браузер показывает инструкцию; установку на вашем компьютере выполняет агент или терминал.

Попробовать первые задачи → · Как формулировать запросы

Самостоятельная установка и технические детали

tg устанавливается как обычный npm-пакет. При установке ничего не компилируется: SQLite уже входит в среду выполнения, поэтому сборка нативных модулей не нужна. Фоновые процессы сами по себе не запускаются. Глобальная установка через npm может установить инструкции для агента и исправить пользовательский PATH в Windows. Во время установки инструмент не входит в аккаунт и не читает чаты.

Требования

Node.js 22.16 или новее. Также поддерживается Bun.
Linux, macOS или Windows.
Ваше приложение Telegram с my.telegram.org. tg запросит его при первом входе и может зарегистрировать его за вас (Вход и сессии).

npm install -g --allow-scripts=@leemour/tg-cli --foreground-scripts @leemour/tg-cli
# The global install puts the skill in .agents and .claude. Then: tg setup

pnpm add -g @leemour/tg-cli
bun add -g @leemour/tg-cli

Пакет называется @leemour/tg-cli, а установленная команда — tg.

Попробовать без установки:

npx @leemour/tg-cli --help

Проверить установку:

tg --version
tg --help
tg doctor        # where its files are, and whether a login exists; connects to nothing

Первый запуск

Сразу после установки tg --help показывает настройку и инструкции для агента. tg skill show работает до входа: агенту следует прочитать инструкции перед подключением Telegram. tg commands --json выводит доступные команды и параметры. Подсказки доступны, даже если менеджер пакетов пропустил установочные скрипты.

Запустите в локальном терминале:

tg setup --agent codex
tg setup --help              # examples, login choices and Windows instructions

Выберите codex, cursor, claude, gemini, all или none. Без --agent команда спрашивает выбор в терминале; с --json и без терминала используется none. На регистрацию приложения, вход, проверку первых пяти чатов и установку skill отведите около пяти минут. Загрузка истории — отдельный шаг, который может занять больше времени: выберите чат и объём перед предложенной командой store fetch. Настройка не запускает фоновую службу.

tg setup --app browser открывает инструкции для ручной регистрации приложения; --method phone выбирает вход по телефону вместо QR. Код регистрации приложения на my.telegram.org и код входа в аккаунт относятся к разным шагам. Повторная настройка проверяет существующую сессию без нового входа. Если вход прервался или Telegram завершил сессию, сначала выполните tg session start, затем повторите настройку. См. Вход и профили.

Без глобальной установки используйте npm exec --yes --package=@leemour/tg-cli -- tg setup --agent codex. Настройка предложит последующие команды в таком же виде.

Windows: одна команда установки

Выполните в PowerShell с установленным Node.js 22.16+ или 24+:

& ([scriptblock]::Create((Invoke-RestMethod 'https://wirecat.dev/install.ps1'))) -Tool tg -Agent all

Установщик устанавливает npm-пакет, сохраняет существующие записи пользовательского PATH, один раз добавляет каталог npm-команд, обновляет PATH текущего PowerShell и устанавливает skill до входа. Затем проверяет запуск tg без полного пути. -Agent codex|cursor|claude|gemini|all|none выбирает каталог skill; значение all по умолчанию устанавливает его в оба поддерживаемых каталога. Повторная установка обновляет skill без дублирования PATH. Установщик выполняет эти шаги и при отключённых скриптах жизненного цикла npm.

Политика выполнения PowerShell не меняется. Установщик удаляет только созданную npm обёртку tg.ps1 этого пакета и сохраняет tg.cmd, поэтому tg запускается и при ограничительной политике. Посторонний скрипт с таким именем остаётся на месте; установщик сообщает о конфликте.

Глобальная установка npm также исправляет постоянный PATH Windows и устанавливает оба skill, если разрешён скрипт postinstall:

npm.cmd install -g --allow-scripts=@leemour/tg-cli --foreground-scripts @leemour/tg-cli

Новые версии npm могут пропускать скрипты жизненного цикла без явного разрешения. --ignore-scripts также отключает установочный скрипт пакета. Установщик PowerShell — основной способ для Windows: он обновляет и постоянный PATH, и текущий терминал; дочерний процесс npm не может изменить среду родителя. Агенты, запущенные до установки, должны сами обновить PATH своей оболочки из пользовательской и системной среды, не прося пользователя редактировать PATH.

Глобальный установочный скрипт работает только при глобальной установке npm, не для зависимостей проекта или npx. TG_INSTALL_AGENT=codex|cursor|claude|gemini|all|none выбирает skill; none явно отключает установку. Агент читает tg skill show и проверяет установленный skill перед входом в аккаунт. Отдельный исполняемый файл для Windows не нужен.

Первые команды чтения — в руководстве по использованию.

Из исходного кода

Для разработки или проверки ещё не выпущенной версии:

git clone https://github.com/leemour/tg-cli.git
cd tg-cli
pnpm install
pnpm build

При запуске из репозитория bin/tg хранит настройки, сессию и базу в .tg/ внутри репозитория, отдельно от вашего обычного профиля. node dist/bin/tg.js использует стандартные каталоги, описанные ниже.

Где хранятся файлы

Три каталога соответствуют правилам операционной системы; ещё два используются совместно с другими инструментами:

Данные	Linux	macOS	Windows
Настройки	`~/.config/tg-cli/config.json`	`~/Library/Preferences/tg-cli/config.json`	`%APPDATA%\tg-cli\Config\config.json`
Сессия входа в Telegram	`~/.local/share/tg-cli/sessions/<profile>.session`	`~/Library/Application Support/tg-cli/sessions/<profile>.session`	`%LOCALAPPDATA%\tg-cli\Data\sessions\<profile>.session`
Записи запусков	`~/.local/share/tg-cli/runs/`	`~/Library/Application Support/tg-cli/runs/`	`%LOCALAPPDATA%\tg-cli\Data\runs\`
Журнал отправок	`~/.local/share/tg-cli/sends/<profile>.jsonl`	`~/Library/Application Support/tg-cli/sends/<profile>.jsonl`	`%LOCALAPPDATA%\tg-cli\Data\sends\<profile>.jsonl`
Разрешённые получатели	`~/.local/share/tg-cli/profiles/<profile>.recipients.json`	`~/Library/Application Support/tg-cli/profiles/<profile>.recipients.json`	`%LOCALAPPDATA%\tg-cli\Data\profiles\<profile>.recipients.json`
Позиция чтения входящих	`~/.local/share/tg-cli/inbox/<profile>.json`	`~/Library/Application Support/tg-cli/inbox/<profile>.json`	`%LOCALAPPDATA%\tg-cli\Data\inbox\<profile>.json`
Журнал фонового сервера	`~/.local/share/tg-cli/serve/<profile>.log`	`~/Library/Application Support/tg-cli/serve/<profile>.log`	`%LOCALAPPDATA%\tg-cli\Data\serve\<profile>.log`
Кеш	`~/.cache/tg-cli/`	`~/Library/Caches/tg-cli/`	`%LOCALAPPDATA%\tg-cli\Cache\`
Локальная база сообщений	`~/.local/share/cli-messaging/messages.db`	`~/Library/Application Support/cli-messaging/messages.db`	`%LOCALAPPDATA%\cli-messaging\Data\messages.db`
Модели распознавания речи	`~/.cache/cli-common/models/audio/`	`~/Library/Caches/cli-common/models/audio/`	`%LOCALAPPDATA%\cli-common\Cache\models\audio\`

~ — ваша домашняя папка. В Windows вставьте %APPDATA% или %LOCALAPPDATA% в адресную строку Проводника. <profile> — имя профиля аккаунта, обычно default. Здесь указаны пути по умолчанию; tg doctor покажет фактические пути, включая переопределения.

Настройки сохраняются в config.json. Данные приложения Telegram обычно хранятся в системном хранилище ключей; credentials.json используется, если хранилище недоступно.

Как защищены данные входа?

ID и хеш приложения Telegram сохраняются в Keychain на macOS, Credential Manager на Windows или Secret Service на Linux. Они отделены от настроек, чтобы снизить риск случайной передачи секретов вместе с конфигурацией. Если хранилище недоступно, tg предупреждает и сохраняет данные в файл с ограниченными правами доступа. Сессия Telegram остаётся отдельным файлом: доступ к нему позволяет использовать ваш вход. Не передавайте его и не добавляйте в Git. Подробнее: Безопасность.

Данные аккаунта и работы CLI: в таблице указаны полные пути к сессии входа, записям запусков, журналу отправок, списку разрешённых получателей и позиции чтения входящих. Фоновые задания загрузки и блокировка сервера также хранятся в каталоге данных аккаунта.
Локальная база используется совместно с другими CLI мессенджеров на той же библиотеке, например max-cli. Подробнее: Локальная база.
Модели речи скачиваются только по запросу (tg models audio download) и используются командой messages transcribe --local.

tg doctor показывает точные пути на текущем компьютере.

Каталоги можно перенести переменными: TG_CONFIG_DIR, TG_STATE_DIR, TG_CACHE_DIR, MESSAGING_STORE (путь к самому файлу базы) и CLI_COMMON_CACHE_DIR (модели).

⚠ TG_CONFIG_DIR, TG_STATE_DIR и TG_CACHE_DIR также меняют запись в хранилище ключей. Сессия, созданная с одной из этих переменных, не видна без неё, и наоборот: команда сообщает «нет сессии», хотя вы уже вошли. Задавайте их всегда или не задавайте вовсе. tg config show показывает, какие переменные установлены.

Обновление

tg upgrade            # with the package manager that installed tg: npm, pnpm or bun
tg upgrade --check    # only say whether a newer version exists; installs nothing

tg upgrade также перезапускает найденный фоновый serve, чтобы сервер не продолжал работать со старым кодом. Обновление никогда не запускается самостоятельно.

JSON-ответ обновления

tg upgrade --check --json сообщает текущую и доступную версии без установки. Общий ответ содержит current, latest, newer, installer, command, updated и restarted — профили, чьи серверы перезапущены после обновления. При проверке, неизменной версии или обновлении без перезапуска возвращается пустой массив; прежние поля сохраняются. Telegram сохраняет свою политику перезапуска управляемых серверов; сервер, требующий ручного перезапуска, указывается в stderr. Скриптам, проверяющим точный набор JSON-ключей, нужно допускать поле restarted во всех случаях.

Раз в день при работе в терминале tg сообщает в stderr о новой версии в npm. При --json, передаче в канал, --quiet и в CI это сообщение отключено. Отключить его вручную: tg config set updateCheck false --defaults или TG_NO_UPDATE_CHECK=1.

Из исходников: git pull && pnpm install && pnpm build. Через npx: npx @leemour/tg-cli@latest.

Удаление

Удаление команды не удаляет данные. Сначала выйдите из аккаунта, пока tg ещё установлен:

tg server uninstall                  # if you installed the background unit; stop it first
tg session end                       # logs out on Telegram's side and deletes the session file
npm uninstall -g @leemour/tg-cli
rm -rf ~/.config/tg-cli ~/.local/share/tg-cli ~/.cache/tg-cli

tg session end не удаляет идентификатор и хеш приложения из хранилища ключей. Они находятся в записи сервиса tg-cli; при необходимости удалите её системным инструментом управления ключами.

Локальная база общая для нескольких инструментов. Удаляйте ~/.local/share/cli-messaging/, только если она больше никому не нужна: там хранятся сообщения, прочитанные всеми этими инструментами.

Дальше

Использование — вход и первые команды.

Установка

Установить с помощью агента

Самостоятельная установка и технические детали

ТребованияCopy Anchor Link