# Telegram · Wiersz poleceń

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

Wyszukiwanie, odczytywanie kontekstu, zliczanie aktywności oraz eksportowanie zapisanych wiadomości ze skryptów i agentów, z wyjściem w formacie --json, stabilnymi kodami zakończenia oraz tokenami o ograniczonym zakresie dostępu, przeznaczonymi wyłącznie do odczytu.

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

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

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

Wyszukiwanie, odczytywanie kontekstu, zliczanie aktywności oraz eksportowanie zapisanych wiadomości ze skryptów i agentów, z wyjściem w formacie --json, stabilnymi kodami zakończenia oraz tokenami o ograniczonym zakresie dostępu, przeznaczonymi wyłącznie do odczytu.

[TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Dokumentacja](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md)

![Integracje z archiwami](https://phishdestroy.io/tgwitness/assets/chapter-integrations.svg?v=367d9d210074)

[MCP tylko do odczytu](https://phishdestroy.io/tgwitness/pl/docs/reference/mcp/) · [Wyszukiwanie pełnotekstowe](https://phishdestroy.io/tgwitness/pl/docs/reference/search/) · [Wiki](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/pl/docs/reference/cli/#index-and-backup)) work on a local data directory and need no token.

Przy `--json`, stdout przekazuje dokładnie jeden dokument JSON (`export` zapisuje wiersze JSON). Postęp, podpowiedzi i błędy są kierowane do stderr. Kody wyjścia są stałe:

| Kod | Znaczenie |
| --- | --- |
| `0` | Pomyślny wynik, w tym wynik pusty |
| `1` | Błąd: niedostępny panel, nieczytelne dane, przerwany eksport |
| `2` | Błąd użytkowania lub nieprawidłowe żądanie: nieprawidłowa data, nieznana opcja, indeks wyszukiwania wyłączony |
| `3` | Obecnie niedostępne: obszar roboczy jest otwarty w uruchomionym panelu lub panel prosi o ponowną próbę później (limit częstotliwości, przekroczenie limitu czasu) |
| `4` | Odmowa dostępu: brakujący, wygasły lub unieważniony token, czat poza zakresem działania narzędzia, narzędzie, które tego nie zezwala |

## Dwa sposoby czytania

**Poprzez panel (`--url`).** Polecenie wykorzystuje ten sam API archiwum o ograniczonym zakresie, co MCP. Utwórz połączenie w sekcji **Więcej narzędzi → Integracje → MCP**: wybierz obszary robocze i czaty, narzędzia oraz okres ważności, a następnie skopiuj token jednokrotnie. Połączenie ma charakter wyłącznie do odczytu, jest ograniczone do tych czatów, ma limit 60 żądań na minutę i może zostać cofnięte lub odnowione w dowolnym momencie. Tokeny logowania do panelu oraz dane uwierzytelniające z Telegrama nie działają w tym przypadku.

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

Panel zdalny wymaga protokołu HTTPS; zwykły protokół HTTP jest akceptowany wyłącznie w przypadku `127.0.0.1`, `localhost` oraz `::1`. Zmienne środowiskowe proxy są ignorowane, a przekierowania są odrzucane, dzięki czemu token dociera wyłącznie pod podany przez Ciebie adres.

**Bezpośrednio z zatrzymanego obszaru roboczego (`--data-dir`).** Odczytuje katalog danych z pełnym dostępem lokalnym, bez tokenu. Należy używać tej opcji na kopii katalogu danych lub gdy gromadzenie danych jest zatrzymane. Podpisane rekordy nigdy nie są modyfikowane; podobnie jak w przypadku panelu, otwarcie obszaru roboczego może spowodować aktualizację indeksów pochodnych. Gdy panel ma otwarty obszar roboczy, polecenie kończy działanie z kodem `3`; należy zamiast tego odczytywać dane za pośrednictwem panelu. W przypadku braku `--data-dir`, `TGWITNESS_DATA`, `./data/live` lub wykorzystywany jest katalog danych instalacji, w której uruchomiono polecenie.

`--workspace ID` wybiera obszar roboczy (domyślnie `default`). `tgwitness messages
--workspaces` wyświetla listę tych, do których masz dostęp.

## Polecenia

| Polecenie | Wynik |
| --- | --- |
| `tgwitness search QUERY [--chat ID] [--since] [--until] [--any] [--limit N] [--offset N]` | Najlepsze wyniki na początku, uwzględniając formy słów, dokładne frazy w cudzysłowie, domeny oraz `@username` ([składnia](https://phishdestroy.io/tgwitness/pl/docs/reference/search/#search-syntax)) |
| `tgwitness search QUERY --exact [--before SEQ]` | Dokładny tekst, najnowsze wpisy na początku, bez indeksu |
| `tgwitness context CHAT_ID MESSAGE_ID [--limit N] [--before SEQ]` | Zapisane wiadomości w zakresie dziesięciu identyfikatorów wiadomości po obu stronach |
| `tgwitness messages [--limit N] [--offset N]` | Czat, który można przeczytać |
| `tgwitness messages CHAT_ID [--since] [--until] [--limit N] [--before SEQ]` | Zapisane wiadomości z czatu, najnowsze na początku |
| `tgwitness messages CHAT_ID --message ID` | Każda zapisana wersja i zapis usunięcia jednej wiadomości |
| `tgwitness stats [--chat ID] [--sender ID] [--since] [--until] [--top N]` | Statystyki aktywności poniżej |
| `tgwitness export [--chat ID] [--since] [--until] [--output FILE]` | Zapisane obserwacje w formacie JSON Lines w kolejności zgodnej z dziennikiem |

Daty podaje się jako `2026-10-01` (północ czasu UTC) lub w formacie ISO z podaniem strefy czasowej `2026-10-01T09:00+03:00`. W przypadku `search`, `messages` i `export` wybierają czas obserwacji. Strony mieszczą do 50 rekordów: postępuj zgodnie z `next_offset` (`--offset`) w celu wyszukiwania według rankingu oraz `next_before` (`--before`) w innych miejscach.

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.

Każdy wynik wiadomości zawiera `untrusted_content: true` , identyfikatory obszaru roboczego, czatu i wiadomości, sekwencję dziennika, skrót zapisanego rekordu oraz link do panelu. Edycje, powiadomienia o usunięciu oraz `missing_on_recheck` są oddzielnymi rekordami. Zakres w `stats` pokazuje okresy, których dotyczą wyniki wyszukiwania.

### Statystyki aktywności

`stats` zlicza zapisane obserwacje dla jednej rozmowy, jednego nadawcy lub wszystkich rozmów objętych zakresem:

- wiadomości według godziny UTC i dnia tygodnia (z poniedziałkiem na początku), godziny i dni o największym natężeniu ruchu;
- edytowane, usunięte i `missing_on_recheck` udostępnienia;
- nadawców wraz z liczbą wiadomości oraz czasem wysłania pierwszej i ostatniej wiadomości;
- najczęściej występujące domeny oraz `@handles`, zliczane raz na wiadomość we wszystkich jej zapisanych wersjach;
- zakres: `coverage.gap` zapisy oraz, w celu uzyskania dostępu do całego obszaru roboczego, okresy bez sygnału kontrolnego z podłączonego kolektora (`collector_liveness`).

Okres określa **czas wiadomości zgłoszony przez Telegram**. Liczba godzin i dni tygodnia pomaga oszacować strefę czasową nadawcy. Dane liczbowe są obliczane na żądanie z dziennika i nie są przechowywane. Każdy wynik określa nagłówek dziennika, który obejmuje, gdy dostęp rozciąga się na obszar roboczy. Odczyt zatrzymuje się po pięciu sekundach w panelu lub po upływie `--timeout` sekund lokalnie (domyślnie 30); wówczas `complete` ma wartość false, a `partial` wskazuje pierwszy rekord, który nie został odczytany. W takim przypadku liczone są tylko najnowsze rekordy.

### Eksportuj

`export` tworzy jeden obiekt JSON na każdą zapisaną obserwację (nowe wiadomości, zrzuty ekranu, edycje, odzyskane wiadomości, powiadomienia o usunięciu, `missing_on_recheck` oraz zapisanych plików multimedialnych ) w kolejności z dziennika. Każdy wiersz zawiera te same pola co pozostałe wyniki, wraz z pełnym tekstem. W przypadku `--output`, plik jest zapisywany pod `.partial` nazwą i jest przemianowywany dopiero po zapisaniu zakończenia działania panelu; przerwany eksport nie pozostawia żadnego pliku i kończy działanie z kodem `1`. `--output` nigdy nie nadpisuje istniejącego pliku. Przy użyciu opcji `--output` i `--json`, stdout zawiera podsumowanie: liczbę rekordów, ostatnią sekwencję dziennika oraz, w przypadku dostępu do całego obszaru roboczego, nagłówek dziennika.

Eksport za pośrednictwem panelu wymaga połączenia umożliwiającego wysyłanie**komunikatów Export (tylko z wiersza poleceń)** ; opcja ta nie jest domyślnie zaznaczona. Niniejszy plik jest kopią roboczą; w celu weryfikowalnego przekazania należy skorzystać z podpisanego eksportu w **sekcji Exports** , który sprawdza polecenie `python -m tgwitness.verify` .

Panel ponownie sprawdza uprawnienia dostępu przed wysłaniem każdego rekordu, w tym rekordu zakończenia. Cofnięte lub wygasłe uprawnienia powodują niekompletny eksport. Odroczone odczyty stron dzielą limit procesów archiwizujących z innymi zapytaniami i mają ograniczony czas oczekiwania.

### Index and backup

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

| Polecenie | Wynik |
| --- | --- |
| `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/pl/docs/reference/deployment/#backup-restore-and-capacity) describes restoring and what the next start records.

## Umiejętności agenta

[`.agents/skills/tgwitness-cli/SKILL.md`](https://github.com/phishdestroy/TgWitness/blob/main/.agents/skills/tgwitness-cli/SKILL.md) informuje agenta, jak korzystać z tych poleceń, jak cytować zapisy oraz jak postępować z przechwyconym tekstem. Agenci, którzy `.agents/skills` pobierają go z repozytorium po wygenerowaniu kopii roboczej. W przypadku Claude Code należy skopiować `tgwitness-cli` folder do `.claude/skills/` w swoim projekcie lub `~/.claude/skills/`.

## MCP i wiersz poleceń

Oba korzystają z tych samych połączeń, kontroli zakresu i ograniczeń. Wyniki MCP są ograniczone do jednej strony o rozmiarze 64 KiB, więc MCP nie oferuje eksportu zbiorczego; wiersz poleceń przesyła dane strumieniowo. `get_activity_stats` jest dostępna dla obu.
