# Telegram · Командний рядок

Canonical page: https://phishdestroy.io/tgwitness/uk/docs/reference/cli/

Здійснюйте пошук, читайте контекст, підраховуйте активність та експортуйте збережені повідомлення зі скриптів та агентів із виведенням у форматі --json, стабільними кодами завершення та токенами з обмеженим доступом, призначеними лише для читання.

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

[Documentation index](https://phishdestroy.io/tgwitness/uk/llms.txt)

Translation coverage: this edition includes material from the English original.

Здійснюйте пошук, читайте контекст, підраховуйте активність та експортуйте збережені повідомлення зі скриптів та агентів із виведенням у форматі --json, стабільними кодами завершення та токенами з обмеженим доступом, призначеними лише для читання.

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

![Інтеграції з архівами](https://phishdestroy.io/tgwitness/assets/chapter-integrations.svg?v=367d9d210074)

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

**Preview.** `tgwitness search`, `context`, `messages`, `stats` and `export` read saved observations for scripts and AI agents. They cannot send anything to Telegram, change settings or modify the signed journal. `tgwitness index` and `tgwitness backup` ([below](https://phishdestroy.io/tgwitness/uk/docs/reference/cli/#index-and-backup)) work on a local data directory and need no token.

При цьому `--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.io/tgwitness/uk/docs/reference/search/#search-syntax)) |
| `tgwitness search QUERY --exact [--before SEQ]` | Точний текст, спочатку найновіші записи, без індексу |
| `tgwitness context CHAT_ID MESSAGE_ID [--limit N] [--before SEQ]` | Збережені повідомлення в межах десяти ідентифікаторів повідомлень з обох боків |
| `tgwitness messages [--limit N] [--offset N]` | Чати, які ви можете читати |
| `tgwitness messages CHAT_ID [--since] [--until] [--limit N] [--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`) в інших розділах.

Ranked search stops at 1,000 results. The final page may be shorter than `--limit`. When more observations match, the last page says so (`truncated: true` with `--json`); narrow the query, chat or period.

Кожен результат повідомлення містить `untrusted_content: true` , ідентифікатори робочого простору, чату та повідомлення, послідовність журналу, хеш збереженого запису та посилання на панель. Редагування, повідомлення про видалення та `missing_on_recheck` — це окремі записи. Покриття в `stats` показує періоди, за які відповідає результат пошуку.

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

`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` .

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

### Index and backup

These two commands read the data directory directly and take no token or `--url`.

| Команда | Результат |
| --- | --- |
| `tgwitness index status [--workspace ID] [--data-dir DIR] [--json]` | Search index state of one workspace or, by default, every workspace: mode, `ready`, `building` or `not built`, indexed and journal head sequence. Works while the panel runs |
| `tgwitness index rebuild [--workspace ID] [--data-dir DIR] [--json]` | Rebuilds the index from the first journal record. Rewrites only the derived index, never the signed journal. Exits with code `3` while the panel has the workspace open. Nothing is built when the workspace keeps its index in memory or has search off |
| `tgwitness backup FOLDER [--data-dir DIR] [--json]` | Copies the whole data directory into a new or empty folder outside it while the panel keeps running, and writes `backup-manifest.json` with every file's SHA-256 and the journal heads |

`index` accepts `--workspace default` or a workspace ID; the default is `all`. The backup skips temporary exports, SQLite sidecar files and lock files. The folder holds the Telegram session and signing keys, so keep it as private as the data directory. [Backup, restore, and capacity](https://phishdestroy.io/tgwitness/uk/docs/reference/deployment/#backup-restore-and-capacity) describes restoring and what the next start records.

## Навички агента

[`.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` доступна для обох.
