# Telegram · خط فرمان

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

جستجو، خواندن زمینه، شمارش فعالیت و صادر کردن پیام‌های ذخیره‌شده از اسکریپت‌ها و ایجنت‌ها، با خروجی --json، کدهای خروجی پایدار و توکن‌های محدودخوانی.

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

[Documentation index](https://phishdestroy.io/tgwitness/fa/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/fa/docs/reference/mcp/) · [جستجوی متن کامل](https://phishdestroy.io/tgwitness/fa/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/fa/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 آرشیو محدود (scoped) استفاده می‌کند که MCP. در **More tools → Integrations → MCP** یک اتصال ایجاد کنید: فضاهای کاری و چت‌ها، ابزارها و یک تاریخ انقضا را انتخاب کرده، سپس توکن را یک‌بار کپی کنید. این اتصال فقط-خواندنی است، به همان چت‌ها محدود است، با نرخ محدودی برای 60درخواست در دقیقه و قابل لغو یا چرخش در هر زمان است. توکن‌های ورود پنل و اطلاعات کاربری تلگرام در اینجا کار نمی‌کنند.

```
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`متغیرهای محیطی پروکسی نادیده گرفته می‌شوند و هدایت‌ها (redirects) رد می‌شوند، بنابراین توکن فقط به آدرسی که شما وارد می‌کنید می‌رسد.

**مستقیماً از یک فضای کاری متوقف‌شده (`--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/fa/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` آنها زمان مشاهده را انتخاب می‌کنند. صفحات تا ۵۰ رکورد را در خود جای می‌دهند: دنبال کنید `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`).

این دوره، **زمان پیام گزارش‌شده توسط تلگرام را** انتخاب می‌کند. شمارش ساعت و روز هفته به تخمین منطقه زمانی فرستنده کمک می‌کند. اعداد در صورت درخواست از ژورنال محاسبه می‌شوند و ذخیره نمی‌شوند. هر نتیجه، سرتیتر ژورنالی را که پوشش می‌دهد نام می‌برد، زمانی که دسترسی شما کل فضای کاری را در بر می‌گیرد. خواندن از طریق پنل پس از پنج ثانیه، یا به صورت محلی پس از `--timeout` ثانیه (پیش‌فرض 30) متوقف می‌شود؛ در این صورت `complete` نادرست است و `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/fa/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 به یک صفحه ۶۴ کیلوبایتی محدود است، بنابراین MCP هیچ‌گونه خروجی انبوهی ارائه نمی‌دهد؛ خط فرمان آن را استریم می‌کند. `get_activity_stats` برای هر دو در دسترس است.
