# CLI для Telegram: поиск по архиву и экспорт JSONL

Canonical page: https://phishdestroy.github.io/TgWitness/ru/docs/reference/cli/

Поиск, чтение контекста, подсчёт активности и экспорт сохраненных сообщений из скриптов и агентов с выводом в формате --json, стабильными кодами завершения и токенами с ограниченной областью действия, доступными только для чтения.

[Project context and measured scale](https://phishdestroy.github.io/TgWitness/ru/docs/reference/overview/)

[Documentation index](https://phishdestroy.github.io/TgWitness/ru/llms.txt)

Поиск, чтение контекста, подсчёт активности и экспорт сохраненных сообщений из скриптов и агентов с выводом в формате --json, стабильными кодами завершения и токенами с ограниченной областью действия, доступными только для чтения.

[TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Документация](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md)

![Интеграция с архивами](https://phishdestroy.github.io/TgWitness/assets/chapter-integrations.svg)

[MCP только для чтения](https://phishdestroy.github.io/TgWitness/ru/docs/reference/mcp/) · [Полнотекстовый поиск](https://phishdestroy.github.io/TgWitness/ru/docs/reference/search/) · [Вики](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Archive-and-Integrations.md)

**Предварительный просмотр.** `tgwitness search`, `context`, `messages`, `stats` а также `export` читать сохраненные наблюдения для скриптов и ИИ-агентов. Они не могут отправлять что-либо в Telegram, изменять настройки или модифицировать подписанный журнал.

При этом `--json`, stdout выводит ровно один документ JSON (`export` записывает строки JSON). Информация о ходе выполнения, подсказки и ошибки выводятся в stderr. Коды завершения являются стабильными:

| Код | Значение |
| --- | --- |
| `0` | Успех, включая пустой результат |
| `1` | Ошибки: недоступная панель, нечитаемые данные, прерванный экспорт |
| `2` | Ошибка использования или недопустимый запрос: неверная дата, неизвестный параметр, индекс поиска отключен |
| `3` | В данный момент недоступно: рабочая область открыта в запущенной панели, либо панель просит повторить попытку позже (ограничение частоты запросов, таймаут) |
| `4` | Доступ запрещен: отсутствующий, просроченный или отозванный токен, чат, выходящий за пределы его области действия, инструмент, который это не допускает |

## Два способа чтения

**Через панель (`--url`).** Команда использует тот же API архива с ограниченной областью действия, что и MCP. Создайте подключение в **разделе** **«Интеграции» → «MCP**»: выберите рабочие пространства и чаты, инструменты и срок действия, затем скопируйте токен один раз. Подключение доступно только для чтения, ограничено указанными чатами, имеет ограничение по скорости в 60 запросов в минуту и может быть отозвано или обновлено в любое время. Токены входа в панель и учетные данные Telegram здесь не работают.

```
export TGWITNESS_URL=https://panel.example.org      # default http://127.0.0.1:8787
export TGWITNESS_MCP_TOKEN=tgw_mcp_...              # or --token-file path
tgwitness search 'перевод карта' --json
```

Для удалённой панели требуется HTTPS; простой HTTP допускается только для `127.0.0.1`, `localhost` и `::1`. Переменные среды прокси игнорируются, а перенаправления не допускаются, поэтому токен попадает только по указанному вами адресу.

**Непосредственно из остановленного рабочего пространства (`--data-dir`).** Считывает каталог данных с полным локальным доступом, без токена. Используйте эту команду на копии каталога данных или когда сбор данных остановлен. Подписанные записи никогда не изменяются; как и в панели, открытие рабочего пространства может привести к обновлению производных индексов. Если панель имеет открытое рабочее пространство, команда завершается с кодом `3`; вместо этого читайте данные через панель. Если `--data-dir`, `TGWITNESS_DATA`, `./data/live` используется каталог данных той установки, в которой выполняется команда.

`--workspace ID` выбирает рабочую область (по умолчанию `default`). `tgwitness messages
--workspaces` выводит список тех, которые вы можете читать.

## Команды

| Команда | Результат |
| --- | --- |
| `tgwitness search QUERY [--chat ID] [--since] [--until] [--any] [--limit N] [--offset N]` | Сначала отображаются наиболее подходящие варианты с учетом словоформ, точных фраз в кавычках, доменов и `@username` ([синтаксис](https://phishdestroy.github.io/TgWitness/ru/docs/reference/search/#search-syntax)) |
| `tgwitness search QUERY --exact [--before SEQ]` | Точный текст, сначала самые новые записи, без указателя |
| `tgwitness context CHAT_ID MESSAGE_ID` | Сохраненные сообщения в пределах десяти идентификаторов сообщений в обе стороны |
| `tgwitness messages` | Чаты, которые можно читать |
| `tgwitness messages CHAT_ID [--since] [--until] [--before SEQ]` | Сохраненные сообщения чата, сначала самые новые |
| `tgwitness messages CHAT_ID --message ID` | Каждая сохраненная версия и запись об удалении одного сообщения |
| `tgwitness stats [--chat ID] [--sender ID] [--since] [--until] [--top N]` | Статистика активности приведена ниже |
| `tgwitness export [--chat ID] [--since] [--until] [--output FILE]` | Сохраненные наблюдения в формате JSON Lines в порядке записей в журнале |

Даты указаны `2026-10-01` (полночь по UTC) или время в формате ISO с указанием часового пояса, `2026-10-01T09:00+03:00`. Что касается `search`, `messages` и `export` они выбирают время наблюдения. Страницы вмещают до 50 записей: следуйте `next_offset` (`--offset`) для поиска по рейтингу и `next_before` (`--before`) в других разделах.

Ранжированный поиск ограничивается 1,000 результатами. Последняя страница может быть короче, чем `--limit`; сузьте запрос, чат или период, если существует больше подходящих наблюдений.

Каждый результат сообщения содержит `untrusted_content: true`идентификаторы рабочего пространства, чата и сообщения, порядковый номер в журнале, хеш сохраненной записи и ссылку на панель. Редактирования, уведомления об удалении и `missing_on_recheck` являются отдельными записями. Отсутствие записи не доказывает, что событие никогда не происходило.

### Статистика активности

`stats` подсчитывает количество сохраненных наблюдений для одного чата, одного отправителя или всех чатов в пределах области действия:

- сообщения по часам UTC и по дням недели (начиная с понедельника), часы и дни с наибольшей активностью;
- отредактировано, удалено и `missing_on_recheck` поделился;
- отправителей с указанием количества сообщений, а также времени отправки первого и последнего сообщения;
- наиболее часто встречающиеся домены и `@handles`, учитываемые один раз на сообщение во всех его сохраненных версиях;
- Объем: `coverage.gap` записи и, для доступа ко всему рабочему пространству, периоды без сигналов о работоспособности подключенного коллектора (`collector_liveness`).

Период определяет **время сообщения, указанное Telegram**. Количество часов и дней недели может помочь оценить часовой пояс отправителя, но не позволяет его точно установить. Цифры рассчитываются по запросу из журнала и не сохраняются. Каждый результат указывает начало журнала, который он охватывает, если ваш доступ охватывает рабочую область. Чтение прекращается через пять секунд после прокрутки панели или `--timeout` секунд локально (по умолчанию 30); после этого `complete` имеет значение false, а `partial` указывает первую запись, которая не была прочитана. В этом случае учитываются только самые последние записи.

### Экспорт

`export` Записывает один объект JSON на каждое сохраненное наблюдение (новые сообщения, снимки экрана, редактирования, восстановленные сообщения, уведомления об удалении, `missing_on_recheck` и сохраненные медиафайлы ) в порядке записей журнала. Каждая строка содержит те же поля, что и остальные результаты, включая полный текст. При `--output`файл записывается под `.partial` именем и переименовывается только после записи о завершении работы панели; прерванный экспорт не оставляет файла и завершается с кодом `1`. `--output` никогда не перезаписывает существующий файл. При использовании `--output` и `--json`в stdout выводится сводка: количество записей, последняя последовательность журнала и, при доступе ко всему рабочему пространству, начало журнала.

Для экспорта через панель требуется подключение, поддерживающее **экспорт сообщений (только из командной строки)**; по умолчанию эта опция не выбрана. Данный файл является рабочей копией, а не доказательством: для проверяемой передачи данных используйте подписанный экспорт в **разделе** **«Экспорт»**, который `python -m tgwitness.verify`проходит проверку.

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

## Навык агента

[`.agents/skills/tgwitness-cli/SKILL.md`](https://github.com/phishdestroy/TgWitness/blob/main/.agents/skills/tgwitness-cli/SKILL.md) содержит инструкции для агента о том, как использовать эти команды, как цитировать записи и как обрабатывать захваченный текст. Агенты, которые читают `.agents/skills` загружают его из репозитория после выгрузки. Для Claude Code скопируйте `tgwitness-cli` папку в `.claude/skills/` в ваш проект или `~/.claude/skills/`.

## MCP и командная строка

Оба используют одни и те же подключения, проверки области действия и ограничения. Результаты MCP ограничены одной страницей размером 64 КиБ, поэтому MCP не предоставляет возможности массового экспорта; командная строка передаёт данные потоком. `get_activity_stats` доступна для обоих.