Настройка и обслуживание
Вход, профили, настройки, фоновый сервер, локальное хранилище, диагностика, подключение агента и обновления.
Здесь собраны команды настройки и обслуживания. Вы найдёте параметры входа, профилей, настроек, фонового сервера, локального хранилища, диагностики и подключения агента.
Вход, профили, настройки, фоновый сервер, локальное хранилище, диагностика, подключение агента и обновления.
Общие параметры
| Параметр | Назначение |
|---|---|
-V, --version | показать номер версии. |
-v, --verbose | подробности: -v — идентификаторы, -vv — все известные данные. По умолчанию: 0. |
--json | машиночитаемый вывод: единственное значение JSON в stdout. |
--agent-json | JSON для ИИ-агента: невидимые управляющие символы показаны явно; обычный --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 endtg 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 listtg 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 listtg 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 listtg models audio download
однократно скачать модель с проверкой ожидаемого sha256
tg models audio download <model>tg models text
модели векторизации для поиска разговоров по смыслу
tg models text list
модели от наиболее подходящих, наличие загрузки и выбор по умолчанию
tg models text listtg models text download
однократно скачать модель с проверкой ожидаемого sha256
tg models text download <model> [options]| Параметр | Назначение |
|---|---|
--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 servetg server
tg serve в фоне: запуск, остановка, перезапуск, состояние, журнал; install добавляет systemd или launchd
tg server start
запустить serve в фоне, через установленную службу, и ответить после подключения
tg server starttg server stop
остановить serve профиля, через службу, если используется
tg server stoptg server restart
остановить и запустить снова
tg server restarttg server status
работает ли serve, с какого времени, кто запустил и какая служба используется
tg server statustg server logs
последние строки serve из журнала systemd или файла
tg server logs [options]| Параметр | Назначение |
|---|---|
-n, --lines <n> | количество строк. По умолчанию: 50. |
tg server install
создать службу systemd или агент launchd профиля; ничего не запускает
tg server installtg server uninstall
удалить службу профиля; сначала остановите
tg server uninstalltg 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]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 cleartg 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 infotg store check
проверка целостности, поисковых индексов, диска и отстающих чатов
tg store checktg store migrate
обновить структуру до текущей версии, затем нормализовать, проиндексировать и разобрать на основы старые сообщения и заметки
tg store migratetg store reindex
перестроить словесный индекс, словарь опечаток, основы слов, словесный индекс файлов и индексы заметок из сохранённых данных; ничего не теряется
tg store reindextg 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-backup | delete the store without backing it up first. |
tg store copies
таблицы, которые store repair сохранил копиями
tg store copies delete
удалить одну копию, сохранённую store repair, по точному имени; другие таблицы не удаляет
tg store copies delete <name>tg flood
ожидания, которые Telegram попросил соблюдать этот профиль, и запрет на его запись
tg flood clear
забыть их, снять блокировку и ограничение частоты профиля, когда Telegram больше не ограничивает аккаунт; в Telegram ничего не меняет
tg flood cleartg runs
записи запусков: действия инструмента и время
tg runs list
записи от новых к старым
tg runs list [options]| Параметр | Назначение |
|---|---|
--limit <n> | количество результатов. По умолчанию: 20. |
tg runs show
запуск: что это было, чем он закончился и что пошло не так; -v — все события
tg runs show <run-id>tg runs search
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>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 | успех |
2 | validation_error |
3 | configuration_error |
4 | authentication_error |
5 | permission_error |
6 | not_found |
7 | confirmation_required |
8 | rate_limited |
9 | timeout |
10 | network_error |
11 | provider_error |
12 | provider_unavailable |
13 | invalid_response |
14 | outcome_unknown |
130 | cancelled |
1 | остальные случаи |
0 и только 0 означает, что операция выполнена. 14 (outcome_unknown) означает, что сообщение могло
быть отправлено: повторяйте только с тем же --send-id, по которому Telegram отбрасывает вторую копию.