Диагностика: что сделала команда

Эта страница помогает понять, что произошло, если команда завершилась ошибкой или работает слишком долго. Начните с tg doctor: он проверит локальную установку без подключения к мессенджеру. Трассировка показывает операции во время работы команды, а запись запуска сохраняет диагностические сведения для последующего просмотра. Это не копия переписки. Ниже объясняется, какой режим выбрать.

Если команда завершается ошибкой или работает слишком долго, tg может показать выполненные операции, сохранить запись запуска и создать отчёт для обращения в поддержку. Тексты сообщений в них не попадают.

Показать операции: --traceCopy Anchor Link

tg --trace messages list "Book club" --limit 5

--trace выводит операции в stderr по мере выполнения: → — запрос, ← — ответ. Указываются идентификаторы, количество объектов, длительность и код ошибки, если она возникла.

→ messages.list    chat -1001234567890
← messages.list    chat -1001234567890  118ms  5 messages

Также выводятся журналы используемой библиотеки Telegram. stdout остаётся без изменений: в канал передаются только данные.

Сохранить запуск: --recordCopy Anchor Link

tg --record chats list
tg runs list                 # recorded runs, newest first
tg runs show <run-id>        # one run: its outcome, and one line per operation
tg runs path <run-id>        # the directory that holds it

Запуск сохраняется в каталоге runs/<day>/ внутри каталога состояния (~/.local/share/tg-cli/runs/ в Linux). Имя включает время и команду. Внутри два файла:

• run.json — команда, профиль, версии tg, Node и системы, время начала и завершения, количество запросов, результат и код ошибки;
• events.jsonl — операции, которые показывает --trace, по одной на строку.

Неудачные запуски сохраняются автоматическиCopy Anchor Link

При ошибке запуск сохраняется даже без --record, с отметкой "keptBecauseFailed": true в run.json. Это относится ко всем командам и ошибкам: неверному параметру, неизвестной команде, предварительной проверке, а также командам без подключения (models, server, upgrade). Ошибка до запуска команды, например при чтении конфигурации, сохраняется как запуск tg. Записываются только слова команды, например messages list, без следующих за ними аргументов.

Успешный запуск не оставляет записи, если вы её не запросили. Так для отчёта об ошибке есть данные, а история прочитанных вами чатов не накапливается. --no-record или "record": false в настройках отключают и автоматическое сохранение ошибок.

Как записывать каждый запускCopy Anchor Link

tg config set record true          # this profile
tg --no-record chats list          # but not this one

После включения настройки сохраняется каждый запуск. По умолчанию успешные запуски не записываются: сведения о том, кого и когда вы читали, сохраняются только с вашего согласия.

Срок храненияCopy Anchor Link

30 дней или значение keepRunsForDays в настройках. Старые записи удаляются только при сохранении новой. Удаляются целые дневные каталоги по их имени, без чтения файлов.

Что не попадает в записиCopy Anchor Link

Запись запуска и --trace содержат имена операций, идентификаторы, количество объектов, длительности и коды ошибок. Они никогда не содержат:

• текст сообщения или подпись;
• название чата, имя человека или имя пользователя;
• значение, введённое вместо <chat>, поскольку это часто название чата;
• номер телефона, код входа, пароль 2FA, сессию или хеш приложения.

Эти же ограничения действуют для отчёта, созданного из записи запуска.

Проверить установку: tg doctorCopy Anchor Link

tg doctor              # connects to nothing
tg doctor --online     # also connects once and reads the account; sends nothing

Команда показывает версию, среду выполнения, профиль, файл конфигурации, наличие сессии и данных приложения (без значений), изменение записи хранилища ключей через TG_*_DIR, локальную базу (путь, версию, количество чатов и сообщений), отправки за последний час и сохранённые запуски.

Отчёт об ошибкеCopy Anchor Link

tg doctor report create                   # about the newest failed run
tg doctor report create --run <run-id>    # about this one

Создаётся JSON-файл с результатом tg doctor и записью запуска. Команда предлагает отправить его в новое обращение на GitHub. Сначала прочитайте файл. Текстов сообщений в нём нет; идентификаторы заменены метками, а не настоящими номерами Telegram.

Если записи неудачного запуска нет, повторите проблемную команду: ошибка сохранится автоматически.

Анализ записейCopy Anchor Link

Записи имеют формат JSON, поэтому их можно анализировать через jq. tg runs list --json возвращает { items, page, limit, hasMore }, где items — содержимое run.json для каждого запуска, от новых к старым:

tg runs list --limit 100 --json | jq '[.items[] | select(.status == "failed") | {command, errorCode}]'
tg runs list --limit 100 --json | jq '[.items[] | .durationMs] | add / length'    # average duration
tg runs list --limit 100 --json | jq '[.items[] | select(.requests > 10) | {command, requests}]'

tg runs show <run-id> выводит те же события таблицей без повторяющихся полей. Полный файл находится в каталоге, который показывает tg runs path <run-id>.

ДальшеCopy Anchor Link

• Решение проблем — значения ошибок и дальнейшие действия
• Безопасность — какие данные сохраняются на диске

Список команд для скриптовCopy Anchor Link

tg commands --json выводит команды, глобальные параметры и коды завершения без подключения к аккаунту. cli — название инструмента, version — версия установленного пакета, а contract — версия общего JSON-контракта (0). Она меняется при несовместимых изменениях полей ответа; обновление пакета само по себе не меняет contract. Скрипты могут читать нужные поля вместо сравнения всего JSON с сохранённой строкой.