Настройка и обслуживание

Вход, профили, настройки, фоновый сервер, локальное хранилище, диагностика, подключение агента и обновления.

Здесь собраны команды настройки и обслуживания. Вы найдёте параметры входа, профилей, настроек, фонового сервера, локального хранилища, диагностики и подключения агента.

Вход, профили, настройки, фоновый сервер, локальное хранилище, диагностика, подключение агента и обновления.

Общие параметры

ПараметрНазначение
-V, --versionпоказать номер версии.
-v, --verboseподробности: -v — идентификаторы, -vv — все известные данные. По умолчанию: 0.
--jsonмашиночитаемый вывод: единственное значение JSON в stdout.
--agent-jsonJSON для ИИ-агента: невидимые управляющие символы показаны явно; обычный --json сохраняет текст.
--jsonlмашиночитаемый вывод: объект JSON на строку для потоковой обработки и jq.
--quietотключить диагностику; ошибки остаются.
--traceжурнал соединения в stderr, без содержимого сообщений.
--debugпри сбое — полная запись о нём, с причиной и стеком, вместо короткой строки.
--timeout <duration>ограничить время всей команды: 30s, 2m, 500ms.
--offlineчитать сохранённое без подключения; ошибка, если данных нет.
--no-inputне запрашивать ввод и не открывать интерактивный вход; ввод через канал остаётся доступным.
--max-input-bytes <bytes>максимальный размер буферизованного ввода в байтах (по умолчанию: 16777216).
--max-output-bytes <bytes>максимальный размер машинного вывода в байтах (по умолчанию: 4194304; 0 отключает ограничение).
--fields <paths>поля элементов или объекта через запятую: id,text; сохранять пагинацию и идентификаторы операций.
--briefнайденные сообщения и письма — только ссылка, заголовок, время, отправитель и фрагмент.
--fullнайденные сообщения и письма с полным текстом и всеми полями провайдера.
--dry-runпредварительно показать разобранные аргументы и разрешения перед выполнением действия.
--yesвыполнить изменение без подтверждения уровня ask.
--recordсохранить запуск: идентификаторы и время, без текста сообщений.
--no-recordне сохранять независимо от настроек.

Команды

tg session

войти в Telegram или выйти для этого профиля

tg session start

войти по QR-коду (по умолчанию) или телефону, коду и паролю 2FA

tg session start [method] [options]
АргументОбязательностьОписание
methodнеобязателенспособ входа: qr, phone. По умолчанию: qr.
ПараметрНазначение
--app <how>только первый раз: способ получения приложения профиля с my.telegram.org: browser, auto. По умолчанию: browser.
--qr-file <png>сохранить QR-код в PNG для передачи агентом вместо отображения.
--smsвход по телефону: попросить код по SMS; Telegram всё равно может отказать.

tg session end

завершить сессию профиля в Telegram и удалить её локально

Changes something in Telegram.

tg session end

tg setup

настроить Telegram и подключить агента

Changes something in Telegram.

tg setup [options]
ПараметрНазначение
--agent <agent>установить skill для агента; в терминале спрашивает выбор, иначе не устанавливает. Варианты: none, codex, cursor, claude, gemini, all.
--app <how>как получить ключи приложения Telegram при первом входе. Варианты: auto, browser. По умолчанию: auto.
--method <method>как войти, если сессии нет. Варианты: qr, phone. По умолчанию: qr.
--qr-file <png>записать временное QR-изображение входа для агента; без терминала требуются сохранённые ключи приложения.

tg account

аккаунт текущей сессии

tg account list

все профили на этом компьютере и аккаунт каждого; не обращается к мессенджеру

tg account list

tg account show

под каким аккаунтом вошёл профиль; последние четыре цифры телефона

tg account show [options]
ПараметрНазначение
--show-phoneпоказать полный номер телефона.

tg account update

изменить видимые всем имя, описание или фото профиля

Changes something in Telegram.

tg account update [options]
ПараметрНазначение
--first-name <name>ваше имя.
--last-name <name>ваша фамилия.
--description <text>описание профиля.
--photo <file>новое фото профиля: файл изображения.

tg account sessions

другие сессии аккаунта; tg session управляет только входом этого инструмента

tg account sessions list

все подключённые устройства и приложения; ничего не завершается

tg account sessions list

tg account sessions end

завершить все другие сессии, включая телефон; текущая остаётся

Changes something in Telegram.

tg account sessions end [options]
ПараметрНазначение
--othersвсе сессии кроме текущей.

tg models

модели, работающие на компьютере

tg models audio

модели распознавания голосовых сообщений

tg models audio list

модели от наиболее подходящих, наличие загрузки и выбор по умолчанию

tg models audio list

tg models audio download

однократно скачать модель с проверкой ожидаемого sha256

tg models audio download <model>
АргументОбязательностьОписание
modelобязателенидентификатор модели из models audio list.

tg models text

модели векторизации для поиска разговоров по смыслу

tg models text list

модели от наиболее подходящих, наличие загрузки и выбор по умолчанию

tg models text list

tg models text download

однократно скачать модель с проверкой ожидаемого sha256

tg models text download <model> [options]
АргументОбязательностьОписание
modelобязателенидентификатор из models text list.
ПараметрНазначение
--accept-termsпринять собственные лицензионные условия модели.

tg models text key

ключи API сервисов векторов и анализа

tg models text key set

сохранить ключ через скрытый ввод или stdin, никогда аргументом

tg models text key set <provider>
АргументОбязательностьОписание
providerобязателенopenai, anthropic или хост сервера --base-url, требующего ключ.

tg models text key remove

удалить сохранённый ключ

tg models text key remove <provider>
АргументОбязательностьОписание
providerобязателенopenai, anthropic или хост сервера.

tg watch

выводить новые сообщения до Ctrl-C или --timeout; оба завершают штатно

tg watch [options]
ПараметрНазначение
--eventsтакже правки, удаления и реакции; строка содержит тип события.

tg serve

поддерживать базу актуальной до остановки; запускается systemd или launchd

tg serve

tg server

tg serve в фоне: запуск, остановка, перезапуск, состояние, журнал; install добавляет systemd или launchd

tg server start

запустить serve в фоне, через установленную службу, и ответить после подключения

tg server start

tg server stop

остановить serve профиля, через службу, если используется

tg server stop

tg server restart

остановить и запустить снова

tg server restart

tg server status

работает ли serve, с какого времени, кто запустил и какая служба используется

tg server status

tg server logs

последние строки serve из журнала systemd или файла

tg server logs [options]
ПараметрНазначение
-n, --lines <n>количество строк. По умолчанию: 50.

tg server install

создать службу systemd или агент launchd профиля; ничего не запускает

tg server install

tg server uninstall

удалить службу профиля; сначала остановите

tg server uninstall

tg store

локальная база сообщений

tg store status

по чатам: число сообщений, крайние даты, полностью сохранённые участки

tg store status [chat]
АргументОбязательностьОписание
chatнеобязателенчат: название или его часть, идентификатор, @username или me для «Избранного».

tg store gaps

проверить записанные внутренние пробелы охвата и явно загрузить данные для них

tg store gaps plan

локальный план охвата; отсутствие идентификаторов сообщений само по себе не означает нехватку истории

tg store gaps plan <chat>
АргументОбязательностьОписание
chatобязателенчат: название или его часть, идентификатор, @username или me для «Избранного».

tg store gaps repair

загрузить данные внутренних пробелов с ограничениями и перепроверить охват; никогда не удалять сообщения, которые не встретились при загрузке

tg store gaps repair <chat> [options]
АргументОбязательностьОписание
chatобязателенчат: название или его часть, идентификатор, @username или me для «Избранного».
ПараметрНазначение
--limit <n>общее число сообщений при этом устранении пробелов, по умолчанию 500.
--max-gaps <n>не более указанного числа пробелов, по умолчанию 5.
--repair-time <duration>лимит времени устранения пробелов, по умолчанию 30s. По умолчанию: 30s.
--page-size <n>число сообщений на страницу провайдера.
--pause <duration>пауза между страницами провайдера. По умолчанию: 1s.
--fingerprint <hash>отказать, если этот ранее проверенный план охвата изменился.
--catch-upподготовить локальный поиск после устранения пробелов; переопределяет searchCatchUp.
--no-catch-upпропустить подготовку локального поиска после устранения пробелов.
--catch-up-chunks <n>максимальное число подготавливаемых локальных фрагментов.
--catch-up-messages <n>максимальное число сохранённых сообщений, читаемых для подготовки.
--catch-up-time <duration>время подготовки в пределах оставшегося лимита устранения пробелов.
--backgroundустранять пробелы через существующий механизм заданий хранилища; проверять через store jobs show.

tg store jobs

фоновые задания синхронизации

tg store jobs list

задания от новых к старым

tg store jobs list [options]
ПараметрНазначение
--state <state>только задачи в этом состоянии. Одно из: running, done, partial, failed, cancelled, died.

tg store jobs show

задание (по умолчанию последнее) и сохранённые данные его чата

tg store jobs show [job]
АргументОбязательностьОписание
jobнеобязателенидентификатор задания из messages sync --background.

tg store jobs cancel

остановить после текущей страницы; следующая синхронизация продолжит

tg store jobs cancel <job>
АргументОбязательностьОписание
jobобязателенидентификатор задания.

tg store jobs retry

повторить неудачное или прерванное задание как новое; синхронизация продолжается с места остановки базы

tg store jobs retry [job] [options]
АргументОбязательностьОписание
jobнеобязателенидентификатор задания.
ПараметрНазначение
--failedкаждый чат, чьё последнее задание неудачно или прервано.

tg store jobs clear

забыть завершённые задания и удалить их журналы; запущенное задание сохраняется

Изменяет данные только на этом компьютере.

tg store jobs clear

tg store export

сохранённые сообщения чата от старых к новым: --jsonl — сообщение на строку, --json — один объект { items, page, limit, hasMore }; без запросов

tg store export [chats] [options]
АргументОбязательностьОписание
chatsнеобязателенчат: название или его часть, идентификатор, @username или me для «Избранного»; несколько — с --to.
ПараметрНазначение
--format <format>jsonl: сообщение на строку, по умолчанию с --output; markdown: переписка с дневными заголовками и цитатами ответов и пересылок.
--since-time <time>после времени ISO 8601 или 30m / 2h / 1d назад.
--output <file>записать JSON по строкам или переписку в новый закрытый файл.
--to <dir>записать в этот каталог файл на каждый чат и manifest; повторный запуск добавляет только изменения.
--kind <kinds>с --to: все сохранённые чаты этих типов через запятую: dialog, group, channel, saved.
--allс --to: все сохранённые чаты этого аккаунта.
--encryptсжать и зашифровать паролем, введённым в скрытом запросе или переданным через stdin; пароль нигде не хранится — без него файл не открыть.

tg store clear

удалить покинутые чаты из базы вместе с сообщениями

tg store clear [options]
ПараметрНазначение
--leftтолько покинутые этим аккаунтом чаты.
--allow-dangerousподтвердить необратимое удаление; историю покинутого чата нельзя загрузить снова.

tg store info

файл базы: путь, размер, структура, количество строк; без изменений

tg store info

tg store check

проверка целостности, поисковых индексов, диска и отстающих чатов

tg store check

tg store migrate

обновить структуру до текущей версии, затем нормализовать, проиндексировать и разобрать на основы старые сообщения и заметки

tg store migrate

tg store reindex

перестроить словесный индекс, словарь опечаток, основы слов, словесный индекс файлов и индексы заметок из сохранённых данных; ничего не теряется

tg store reindex

tg store backup

скопировать работающую базу в новый файл без перезаписи

tg store backup <file> [options]
АргументОбязательностьОписание
fileобязателенновый файл.
ПараметрНазначение
--encryptсжать и зашифровать паролем, введённым в скрытом запросе или переданным через stdin; пароль нигде не хранится — без него файл не открыть.

tg store restore

восстановить копию вместо базы; заменяемая база сохраняется рядом

tg store restore <file>
АргументОбязательностьОписание
fileобязателенфайл, созданный store backup; для файла, записанного с --encrypt, запрашивается пароль.

tg store decrypt

расшифровать файл, записанный с --encrypt, в новый файл; запрашивает пароль

tg store decrypt <file> [options]
АргументОбязательностьОписание
fileобязателенфайл, созданный store backup --encrypt или store export --encrypt.
ПараметрНазначение
--output <file>новый файл, доступный только вам.

tg store repair

привести каждую таблицу к виду этой сборки, ничего не удаляя: таблица неправильного вида сохраняется копией рядом с новой

tg store repair [options]
ПараметрНазначение
--dry-runпоказать, что будет сделано, ничего не меняя.

tg store reset

back the store up beside itself, then delete it and start an empty one at this build's schema; asks first, or --yes

tg store reset [options]
ОпцияЧто делает
--no-backupdelete the store without backing it up first.

tg store copies

таблицы, которые store repair сохранил копиями

tg store copies delete

удалить одну копию, сохранённую store repair, по точному имени; другие таблицы не удаляет

tg store copies delete <name>
АргументОбязательностьОписание
nameобязателенимя копии, как его вывел store repair.

tg flood

ожидания, которые Telegram попросил соблюдать этот профиль, и запрет на его запись

tg flood clear

забыть их, снять блокировку и ограничение частоты профиля, когда Telegram больше не ограничивает аккаунт; в Telegram ничего не меняет

tg flood clear

tg runs

записи запусков: действия инструмента и время

tg runs list

записи от новых к старым

tg runs list [options]
ПараметрНазначение
--limit <n>количество результатов. По умолчанию: 20.

tg runs show

запуск: что это было, чем он закончился и что пошло не так; -v — все события

tg runs show <run-id>
АргументОбязательностьОписание
run-idобязателенидентификатор из tg runs list.

search recorded diagnostic metadata and events; no message contents

tg runs search [query] [options]
АргументОбязательностьЧто это
queryнеобязательныйcase-insensitive literal diagnostic text.
ОпцияЧто делает
--status <status>run outcome. Одно из: success, failed, partial, running.
--error-code <code>one stable error code.
--operation <name>one operation, such as messages.download.
--profile <name>one recorded profile.
--since-time <time>runs starting on or after an ISO time or 2h / 1d ago.
--limit <n>matches per page, at most 100. По умолчанию: 20.
--page <n>result page. По умолчанию: 1.

tg runs path

каталог запуска

tg runs path <run-id>
АргументОбязательностьОписание
run-idобязателенидентификатор из tg runs list.

tg config

действующие настройки и источники значений

tg config migrate

заменить прежние настройки доступа разрешениями, сохранив действующие уровни в этом файле

Изменяет данные только на этом компьютере.

tg config migrate [options]
ПараметрНазначение
--dry-runпоказать преобразование без записи в файл.

tg config show

профиль, существующие профили, настройки и их источники

tg config show [options]
ПараметрНазначение
--botнастройки бота этого профиля вместо личного аккаунта.

tg config set

сохранить настройку в файл

Изменяет данные только на этом компьютере.

tg config set <setting> <value> [options]
АргументОбязательностьОписание
settingобязательныйодно из: limit, timeoutMs, color, senderColors, record, keepRunsForDays, readOnly, allow, permissions, sendsPerHour, requestsPerMinute, transcribeWith, speechModel, catchUpMarksRead, searchCatchUp, embeddingProvider, embeddingModel, embeddingBaseUrl, embeddingDims, analysisProvider, analysisModel, analysisBaseUrl, models, proxy, readOtherBots, updateCheck, skillHint, defaultProfile, searchStemmers.cyrillic, searchStemmers.latin, accountGroups..
valueобязателенчисло, true, false или список allow, например send,reaction; для группы — tg:work,max:Alice,email:me@x.
ПараметрНазначение
--defaultsобщая настройка всех профилей вместо текущего.
--personalтолько личные аккаунты: соответствующий раздел файла.
--botтолько боты: раздел bot файла.

tg config unset

удалить настройку из файла

Изменяет данные только на этом компьютере.

tg config unset <setting> [options]
АргументОбязательностьОписание
settingобязательныйодно из: limit, timeoutMs, color, senderColors, record, keepRunsForDays, readOnly, allow, permissions, sendsPerHour, requestsPerMinute, transcribeWith, speechModel, catchUpMarksRead, searchCatchUp, embeddingProvider, embeddingModel, embeddingBaseUrl, embeddingDims, analysisProvider, analysisModel, analysisBaseUrl, models, proxy, readOtherBots, updateCheck, skillHint, defaultProfile, searchStemmers.cyrillic, searchStemmers.latin, accountGroups..
ПараметрНазначение
--defaultsобщая настройка всех профилей вместо текущего.
--personalтолько личные аккаунты: соответствующий раздел файла.
--botтолько боты: раздел bot файла.

tg doctor

состояние установки без подключения, кроме --online

tg doctor [options]
ПараметрНазначение
--onlineподключиться один раз и прочитать аккаунт; без отправки.

tg doctor report

содержимое отчёта без записи

tg doctor report create

записать отчёт в файл и показать, куда отправить

tg doctor report create [options]
ПараметрНазначение
--run <id>запуск для отчёта; по умолчанию последний неудачный.
--output <file>путь записи; по умолчанию новый файл здесь.

tg commands

команды, параметры и коды завершения в JSON — один путь команды за вызов

tg commands schema

argv и схемы результатов одной команды, эффекты, разрешения и указания по повторным попыткам

tg commands schema <path>
АргументОбязательностьОписание
pathобязательныйодин путь команды, например stats messages show.

tg complete

автодополнение: tg complete zsh выводит подключаемый скрипт

tg complete [words]
АргументОбязательностьОписание
wordsнеобязателен

tg upgrade

обновить tg установившим его менеджером пакетов; --check только проверяет

tg upgrade [options]
ПараметрНазначение
--checkпроверить новую версию без установки.

tg mcp

доступ агента к профилю через MCP по stdin/stdout: claude mcp add tg -- tg mcp

tg mcp [options]
ПараметрНазначение
--permission <key=level>переопределить разрешение только для этого сервера; повторите для нескольких ключей.
--confirm-sendбольше не используется — операции записи не показывают форму; решение определяют разрешения профиля.
--allow-dangerousбольше не используется — операции записи не показывают форму; решение определяют разрешения профиля.
--allow-sendустарел: решение принимает профиль; сохранён для запуска старых настроек.
--allow-mark-readустарел: решение принимает профиль.
--allow-deleteустарел: решение принимает профиль.
--httpобслуживать через HTTP на 127.0.0.1 для ChatGPT и Claude в браузере, за вашим туннелем.
--http-confirmation <mode>больше не используется — операции записи не показывают форму; решение определяют разрешения профиля.
--port <port>локальный порт для --http (по умолчанию 8765).
--public-url <url>https-адрес туннеля для браузерных приложений, например https://.ts.net.
--revokeзабыть все входы, выданные браузерным приложениям; каждому придётся войти заново.

tg mcp config

вывести mcpServers для Claude Desktop, Cursor и других с полными путями; без записи

tg mcp config [options]
ПараметрНазначение
--permission <key=level>переопределить разрешение только для этого сервера; повторите для нескольких ключей.
--confirm-sendбольше не используется — операции записи не показывают форму; решение определяют разрешения профиля.
--allow-dangerousбольше не используется — операции записи не показывают форму; решение определяют разрешения профиля.
--allow-sendустарел: решение принимает профиль; сохранён для запуска старых настроек.
--allow-mark-readустарел: решение принимает профиль.
--allow-deleteустарел: решение принимает профиль.

tg mcp setup

добавить локальный MCP-сервер этого профиля в Codex или Claude Code

Изменяет данные только на этом компьютере.

tg mcp setup <client> [options]
АргументОбязательностьОписание
clientобязательноcodex или claude-code.
ПараметрНазначение
--allow-writesподтвердить, что профиль предоставляет инструменты изменения данных.
--permission <key=level>переопределить разрешение только для этого сервера; повторите для нескольких ключей.
--confirm-sendбольше не используется — операции записи не показывают форму; решение определяют разрешения профиля.
--allow-dangerousбольше не используется — операции записи не показывают форму; решение определяют разрешения профиля.
--allow-sendустарел: решение принимает профиль; сохранён для запуска старых настроек.
--allow-mark-readустарел: решение принимает профиль.
--allow-deleteустарел: решение принимает профиль.

tg mcp doctor

проверить локальное подключение MCP и список инструментов этого профиля

tg mcp doctor [options]
ПараметрНазначение
--permission <key=level>переопределить разрешение только для этого сервера; повторите для нескольких ключей.
--confirm-sendбольше не используется — операции записи не показывают форму; решение определяют разрешения профиля.
--allow-dangerousбольше не используется — операции записи не показывают форму; решение определяют разрешения профиля.
--allow-sendустарел: решение принимает профиль; сохранён для запуска старых настроек.
--allow-mark-readустарел: решение принимает профиль.
--allow-deleteустарел: решение принимает профиль.

tg skill

инструкции агенту по инструменту

tg skill show

вывести SKILL.md; tg skill install устанавливает для Claude Code, Codex и Gemini CLI

tg skill show [name]
АргументОбязательностьОписание
nameнеобязателенвстроенный skill для задачи: follow-ups, link-conversations.

tg skill install

записать SKILL.md в ~/.claude/skills/tg-cli/ (Claude Code) и ~/.agents/skills/tg-cli/ (Codex, Gemini CLI)

tg skill install [options]
ПараметрНазначение
--for <agents>агенты: claude, agents, all. По умолчанию: all.

Коды завершения

Выбирайте ветвь по коду, а не по тексту: текст может измениться, код — нет.

КодКогда
0успех
2validation_error
3configuration_error
4authentication_error
5permission_error
6not_found
7confirmation_required
8rate_limited
9timeout
10network_error
11provider_error
12provider_unavailable
13invalid_response
14outcome_unknown
130cancelled
1остальные случаи

0 и только 0 означает, что операция выполнена. 14 (outcome_unknown) означает, что сообщение могло быть отправлено: повторяйте только с тем же --send-id, по которому Telegram отбрасывает вторую копию.