# Telegram · کمانڈ لائن

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

تلاش کریں، سیاق و سباق پڑھیں، سرگرمی کی گنتی کریں اور اسکرپٹس اور ایجنٹس سے محفوظ شدہ پیغامات برآمد کریں، --json آؤٹ پٹ، مستحکم ایگزٹ کوڈز اور محدود دائرہ کار کے ریڈ-اونلی ٹوکنز کے ساتھ۔

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

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

تلاش کریں، سیاق و سباق پڑھیں، سرگرمی کی گنتی کریں اور اسکرپٹس اور ایجنٹس سے محفوظ شدہ پیغامات برآمد کریں، --json آؤٹ پٹ، مستحکم ایگزٹ کوڈز اور محدود دائرہ کار کے ریڈ-اونلی ٹوکنز کے ساتھ۔

[ٹی جی وٹنس](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/ur/docs/reference/mcp/) · [مکمل متن تلاش](https://phishdestroy.github.io/TgWitness/ur/docs/reference/search/) · [ویکی](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Archive-and-Integrations.md)

**پریویو۔** `tgwitness search`, `context`, `messages`, `stats` اور `export` پڑھیں محفوظ شدہ مشاہدات اسکرپٹس اور AI ایجنٹس کے لیے۔ وہ ٹیلیگرام پر کچھ بھی بھیج نہیں سکتے، سیٹنگز تبدیل نہیں کر سکتے یا دستخط شدہ جرنل میں ترمیم نہیں کر سکتے۔

کے ساتھ `--json`، stdout بالکل ایک JSON دستاویز منتقل کرتا ہے (`export` JSON Lines لکھتا ہے). پیش رفت، اشارے اور غلطیاں stderr پر جاتی ہیں۔ ایگزٹ کوڈز مستحکم ہیں:

| کوڈ | معنی |
| --- | --- |
| `0` | کامیابی، بشمول خالی نتیجہ |
| `1` | ناکامی: ناقابلِ رسائی پینل، ناقابلِ مطالعہ ڈیٹا، منقطع برآمد |
| `2` | استعمال میں غلطی یا غیر درست درخواست: غلط تاریخ، نامعلوم آپشن، تلاش کا انڈیکس درست نہیں |
| `3` | فی الحال دستیاب نہیں: ورک اسپیس ایک چلتی ہوئی پینل میں کھلا ہوا ہے، یا پینل بعد میں دوبارہ کوشش کرنے کو کہتا ہے (ریٹ لمیٹ، ٹائم آؤٹ) |
| `4` | رسائی سے انکار: ٹوکن غائب، ختم شدہ یا منسوخ شدہ، اس کے دائرہ اختیار سے باہر ایک چیٹ، ایک ایسا ٹول جس کی اجازت نہیں ہے۔ |

## پڑھنے کے دو طریقے

**پینل کے ذریعے (`--url`).** یہ کمانڈ MCP کی طرح اسی اسکوپڈ آرکائیو API کا استعمال کرتی ہے۔ **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`پراکسی ماحول کے متغیرات کو نظر انداز کیا جاتا ہے اور ری ڈائریکٹس کو مسترد کر دیا جاتا ہے، لہٰذا ٹوکن صرف آپ کے دیے گئے پتے تک پہنچتا ہے۔

**براہِ راست ایک روکے ہوئے ورک اسپیس (`--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/ur/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`).

یہ مدت **ٹیلیگرام کی رپورٹ کردہ پیغام کے وقت کا** انتخاب کرتی ہے۔ گھنٹے اور ہفتے کے دنوں کی گنتی بھیجنے والے کے ٹائم زون کا اندازہ لگانے میں مدد کر سکتی ہے؛ یہ اسے قطعی طور پر متعین نہیں کرتی۔ اعداد و شمار جرنل سے درخواست پر شمار کیے جاتے ہیں اور محفوظ نہیں کیے جاتے۔ ہر نتیجہ اس جرنل ہیڈ کا نام بتاتا ہے جسے یہ کور کرتا ہے جب آپ کی رسائی ورک اسپیس میں پھیلی ہوتی ہے۔ پانچ سیکنڈ کے بعد پڑھنا پینل کے ذریعے رک جاتا ہے، یا `--timeout` سیکنڈز مقامی طور پر (ڈیفالٹ 30)؛ پھر `complete` غلط ہے اور `partial` پہلے ریکارڈ کا نام بتاتا ہے جو پڑھا نہیں گیا تھا۔ اس صورت میں صرف تازہ ترین ریکارڈز ہی گنے جاتے ہیں۔

### ایکسپورٹ

`export` ہر محفوظ شدہ مشاہدے کے لیے ایک JSON آبجیکٹ لکھتا ہے (نئے پیغامات، اسنیپ شاٹس، ترمیمات، بازیافت شدہ پیغامات، حذف کرنے کے نوٹس، `missing_on_recheck` اور محفوظ شدہ میڈیا ریکارڈز) جرنل کی ترتیب میں۔ ہر لائن میں دیگر نتائج کی طرح وہی فیلڈز ہوتے ہیں، مکمل متن کے ساتھ۔ کے ساتھ `--output`، فائل ایک کے تحت لکھی جاتی ہے `.partial` نام اور دوبارہ نام صرف پینل کے مکمل ریکارڈ کے بعد لکھا جاتا ہے؛ ایک منقطع ایکسپورٹ کوئی فائل نہیں چھوڑتا اور کوڈ کے ساتھ نکل جاتا ہے `1`. `--output` موجودہ فائل کو کبھی اووررائٹ نہیں کرتا۔ کے ساتھ `--output` اور `--json` کے ساتھ، stdout ایک خلاصہ دکھاتا ہے: ریکارڈز کی تعداد، آخری جرنل ترتیب اور پورے ورک اسپیس تک رسائی کے لیے، جرنل ہیڈ۔

پینل کے ذریعے ایکسپورٹ کے لیے ایک ایسے کنکشن کی ضرورت ہوتی ہے جو **پیغامات کو ایکسپورٹ کرنے** **کی** اجازت دیتا ہو **(صرف کمانڈ لائن)**؛ یہ بطورِ ڈیفالٹ منتخب نہیں ہوتا۔ یہ فائل ایک کام کرنے والی کاپی ہے، ثبوت نہیں: تصدیق شدہ حوالگی کے لیے **Exports** میں موجود دستخط شدہ ایکسپورٹ استعمال کریں، جو `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 KiB صفحے تک محدود ہیں، لہٰذا MCP کسی بھی بلک ایکسپورٹ کی سہولت فراہم نہیں کرتا؛ کمانڈ لائن اسے اسٹریم کرتی ہے۔ `get_activity_stats` دونوں کے لیے دستیاب ہے۔