# Telegram · שורת הפקודה

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

חפשו, קראו את ההקשר, ספרו פעילויות וייצאו הודעות שנשמרו באמצעות סקריפטים וסוכנים, עם פלט בפורמט --json, קודי יציאה יציבים ואסימוני קריאה בלבד בעלי תחום מוגדר.

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

[Documentation index](https://phishdestroy.github.io/TgWitness/he/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/he/docs/reference/mcp/) · [חיפוש בטקסט מלא](https://phishdestroy.github.io/TgWitness/he/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. צרו חיבור ב**-Integrations → 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/he/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`, את מזהי סביבת העבודה, הצ'אט וה הודעה, את מספר הרצף ביומן, את ה-hash של הרשומה השמורה וקישור לפאנל. עריכות, הודעות מחיקה ו `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 KiB, ולכן ה-MCP אינו מציע ייצוא בכמות גדולה; שורת הפקודה מעבירה את הנתונים בזרם. `get_activity_stats` זמינה לשניהם.