Skip to main content
قم بتشغيل كل عمليات Failproof AI Observability من المحطة الطرفية أو من نص برمجي: بدون الحاجة إلى لوحة التحكم. يستعلم CLI agenteye عن بيانات النظام (الجلسات وسجلات الأحداث والتقييمات) ويدير مؤسستك (مفاتيح API والمستخدمون والإعدادات والتنبيهات والحوادث والاستعلامات المحفوظة)، لذا استخدمه عندما تريد أتمتة فحص أو دمج الملاحظة في CI أو السماح لوكيل ترميز بفحص الإنتاج. يدعم كل أمر علم --json، لذلك يعمل بنفس الكفاءة سواء كنت في موجه الأوامر أو وكيل ترميز (Claude Code أو Cursor) يقوم بتنفيذ الأمر وتحليل النتيجة. باستخدام ملف ثنائي واحد يمكنك:
  • قراءة بيانانك: sessions و events و evals و errors (تصفية حسب الوقت والوكيل والبيئة والنتيجة).
  • إدارة مؤسستك: keys و users و settings و alerts و incidents.
  • تشغيل التحليلات: SQL محفوظ وأداة استعلام مخصصة (query).
  • اطلب من مساعد الذكاء الاصطناعي: نفس محلل القراءة فقط الذي تتحدث معه في لوحة التحكم (agent).
ملاحظة: هذا هو CLI agenteye، وهي أداة مختلفة عن عفريت المجمع (agenteye-collector). يتحدث CLI مع لوحة التحكم الخاصة بك؛ المجمع يرسل الأحداث إلى الخادم.

البدء السريع

من الصفر إلى أول نتيجة في أربعة أسطر. وجه CLI إلى لوحة التحكم الخاصة بك وقم بتسجيل الدخول والتأكد من هويتك ثم اسحب آخر يوم من التشغيلات:
يطبع الأمر الأخير كائن JSON للجلسات الأخيرة (الأحدث أولاً، محدود بـ 50 افتراضياً). أرسله عبر أنابيب إلى jq لتقطيعه، أو أزل --json للحصول على جدول مربع وملون. يحمل كل صف حالة التشغيل والنتائج المترية إذا قام المقيم بتقييمه (مختصرة هنا):
يشرح بقية هذه الصفحة كل جزء: التثبيت بشكل منفصل و تسجيل الدخول و الإعدادات و الاتفاقيات العامة التي تشاركها كل أمر و مرجع الأمر الكامل.

التثبيت

CLI عبارة عن حزمة PyPI عامة تسمى agenteye. ثبتها في بيئة معزولة حتى يكون لديها دائماً اعتماديات خاصة بها:
تتطلب Python 3.10+. الأمر المثبت هو agenteye:
ملاحظة: SDK Python الخاص بـ Failproof AI Observability يستخدم أيضاً اسم توزيع agenteye. يحافظ تثبيت CLI باستخدام pipx أو uv tool (بدلاً من pip install في virtualenv مشترك) على عدم تضارب الاثنين. pip install agenteye عادي جيد فقط إذا لم يكن SDK مثبتاً في نفس البيئة.

المصادقة

يوثق CLI إلى لوحة التحكم باستخدام كود لمرة واحدة يتم إرساله بالبريد الإلكتروني:
يتم حفظ رمز الجلسة في ~/.agenteye/cli.json (قابل للقراءة فقط من قبلك، mode 0600) وصالح لمدة 24 ساعة افتراضياً. عند انتهاء صلاحيته، قم بتشغيل agenteye login مرة أخرى.
لا يخطئ whoami أبداً في جلسة مفقودة أو منتهية الصلاحية؛ بدلاً من ذلك يبلغ عن logged_in: false، لذا يمكن لنص برمجي أو وكيل التحقق من حالة المصادقة بأمان (لا يزال يمكن أن يخرج مع كود غير صفري إذا لم يتم تعيين عنوان URL أساسي أو كانت لوحة التحكم غير قابلة للوصول). المتطلبات: يجب السماح لبريدك الإلكتروني بتسجيل الدخول إلى لوحة التحكم (اطلب من مسؤول Failproof AI Observability)، ويجب أن تكون لوحة التحكم قابلة للوصول على عنوان URL الأساسي الخاص بها (انظر الإعدادات). إذا طلبت كوداً ولم يصل أي، فمن المحتمل أن بريدك الإلكتروني لم يتم تفعيله بعد للوصول إلى لوحة التحكم.

اختيار مؤسستك (متعدد الإيجار)

إذا كان حسابك ينتمي إلى أكثر من مؤسسة واحدة، اختر المؤسسة النشطة عند تسجيل الدخول؛ يتم حفظها واستخدامها لكل أمر لاحق:
إذا كنت تنتمي إلى مؤسسة واحدة بالضبط، يتم اختيارها تلقائياً ويمكنك تجاهل --org تماماً. إذا كنت تنتمي إلى عدة مؤسسات ولم تختر واحدة، يسرد CLI القائمة ويطلب منك إعادة التشغيل باستخدام --org <slug>. يتم إرسال المؤسسة النشطة إلى لوحة التحكم في كل طلب، وتتم معالجة أذوناتك لكل مؤسسة؛ agenteye whoami يظهر المؤسسة النشطة وأذوناتك فيها وجميع عضوياتك.

الإعدادات

ترتيب الدقة هو العلم → متغير البيئة → ملف الإعدادات. لا يوجد افتراضي؛ يجب عليك توجيه CLI إلى لوحة التحكم الخاصة بك، إما لكل أمر (--base-url https://agenteye.example.com) أو مرة واحدة عبر البيئة (يتم حفظها أيضاً بعد أول login):
يحترم دليل الإعدادات AGENTEYE_HOME (نفس الاتفاقية المستخدمة من قبل SDK والمجمع)؛ إذا تم التعيين، يعيش cli.json في $AGENTEYE_HOME/cli.json.

TLS ذاتي التوقيع أو داخلي

إذا كانت لوحة التحكم الخاصة بك تُقدم عبر HTTPS مع شهادة ذاتية التوقيع أو داخلية (على سبيل المثال، اسم مضيف موازن تحميل خام)، يرفضها التحقق من TLS مع خطأ CERTIFICATE_VERIFY_FAILED. مرر --insecure لتخطي التحقق من الشهادة:
يتم حفظ --insecure إلى cli.json عند تسجيل الدخول، لذلك تتخطى الأوامر اللاحقة التحقق تلقائياً؛ لا تضطر إلى تكرار العلم. مرر --secure لاستدعاء موثق لمرة واحدة، أو لحفظ التحقق مرة أخرى عند تسجيل الدخول التالي. يطبع CLI تحذيراً على stderr قبل أي أمر يتواصل مع لوحة التحكم أثناء تعطيل التحقق. يزيل تخطي التحقق الحماية من هجمات الرجل في الوسط؛ تأكد من أنك تثق بمسار الشبكة إلى لوحة التحكم الخاصة بك (VPN أو subnet خاص وما إلى ذلك) قبل الاعتماد عليه.

قياس الاستخدام والخصوصية

ملاحظة: CLI المُشحون لا يرسل قياس اليستخدام اليوم. مفتاح القتل الرئيسي مفعل، لذلك لا يتم نقل شيء بغض النظر عن البيئة الخاصة بك. يوضح القسم أدناه إمكانية عدم الاشتراك في حالة تفعيل قياس الاستخدام في المستقبل.
حتى عند تفعيله، سيكون قياس الاستخدام فقط تحليلات الاستخدام المجهولة، وليس أبداً وكيلك أو جلستك أو بيانات الحدث:
  • لا تترك بيانات الوكيل أو الجلسة أو الحدث أبداً البنية التحتية الخاصة بك. سيتم الإبلاغ عن استخدام CLI فقط: اسم الأمر والأمر الفرعي (على سبيل المثال keys create)، و أسماء الأعلام التي استخدمتها (وليس قيمها أبداً)، وحالة النجاح/الخروج والمدة، بالإضافة إلى حدث لكل إجراء للطفرات (على سبيل المثال api_key_created و query_run) يحمل فقط الأسماء الثابتة/التعداد والأعداد الإجمالية. عنوان URL لوحة التحكم الخاصة بك ورمز الجلسة والبريد الإلكتروني وslug المؤسسة وhids الموارد و SQL وأسرار المفاتيح وفلاتر الاستعلام لن يتم إرسالها أبداً. سيتم تحديد المشغلين فقط بواسطة معرف داخلي معتم، وليس بالبريد الإلكتروني.
  • لا تشترك مقدماً بتعيين AGENTEYE_ANALYTICS_DISABLED=1 في بيئة CLI (يحترم CLI أيضاً اتفاقية أداة متقاطعة DO_NOT_TRACK=1). يسري هذا في اللحظة التي يتم فيها تفعيل قياس الاستخدام، لذا يمكن للبيئة الواعية بالخصوصية البقاء غير مشترك إلى الأبد.
  • إذا تم تفعيل قياس الاستخدام، فسيرسل CLI مباشرة إلى PostHog (https://us.i.posthog.com)؛ الجهاز الذي لديه هذا المضيف محظور سيرسل بصمت شيء والـ CLI لن يتأثر.

الخيارات العامة والاتفاقيات

اقرأ هذا مرة واحدة؛ ينطبق على كل أمر.
  • تذهب الخيارات العامة قبل الأمر. agenteye --json sessions صحيح؛ agenteye sessions --json خطأ استخدام. العامة هي --json و --base-url و --org و --token و --insecure/--secure و --timeout و --quiet و --no-color.
  • --json يطبع JSON خالص إلى stdout، وشيء آخر. خطوط حالة الإنسان والتحذيرات والأخطاء تذهب إلى stderr، لذا يبقى التقاط stdout --json نظيفاً لأنابيب إلى jq حتى عندما يتم عرض سطر حالة. بدون --json تحصل على عرض مربع وملون لعيون الإنسان.
  • اكتشف باستخدام --help. لكل أمر وأمر فرعي --help (والاسم المستعار -h): agenteye -h و agenteye sessions -h و agenteye keys create -h. تسرد الشرعة عالية المستوى أيضاً أكواد الخروج والخيارات العامة. لا يوجد تفريغ سطح قابل للقراءة من الآلة عالمي؛ استخدم --help لكل أمر، بالإضافة إلى agenteye query schema و agenteye settings schema الخاصة بالمجال لتلك السجلات.
  • الأكثر تأكيداً للتخطي التلقائي للنصوص البرمجية والوكلاء. إنشاء/تحديث/حذف أوامر اطلب “هل أنت متأكد؟” في محطة طرفية تفاعلية، لكن تخطي هذا الطلب تلقائياً تحت --json أو عندما لا تكون stdin TTY (TTY هي جلسة محطة طرفية تفاعلية؛ الأنابيب أو عداء CI ليست)، لذا لا تعلق النصوص البرمجية والوكلاء أبداً. مرر --yes/-y لتخطيها بشكل صريح. لأن الطلب لن يحترق لوكيل، يجب على الوكيل تأكيد الإجراءات المدمرة مع الإنسان أولاً.
  • الترقيم: النتائج هي الأحدث أولاً والترقيم المستند إلى المؤشر (يُرجع كل صفحة رمزاً تستخدمه لجلب النتيجة التالية). --limit N (alias -n) يغطي الصفوف و يفترض 50؛ --all يصفحة تلقائياً (في أجزاء بـ 200 صف) حتى --limit، لذا --all مجرد يتوقف عند 50. لكنسة كاملة قم بتمرير حد أعلى صريح: --all --limit 1000. --page-size N يتحكم في الجزء لكل طلب (max 200)؛ --cursor <id> يستأنف من next_cursor الصفحة السابقة.
  • مرشحات الوقت: --since يأخذ نافذة نسبية: 15m أو 1h أو 6h أو 24h أو 7d أو all (إعدادات لوحة التحكم المسبقة). لنطاق أطول أو مخصص (قل آخر 30 يوماً)، استخدم --from/--to: طوابع زمنية UTC صريحة بصيغة ISO-8601 مع T ومنطقة زمنية (على سبيل المثال 2026-06-01T00:00:00Z) التي تتجاوز --since. القيمة المفصولة بمسافة أو بدون منطقة زمنية هي خطأ استخدام.
  • --fields a,b,c (على events و sessions و evals و errors) يقيد المخرجات إلى تلك المفاتيح، لكل من الجدول و --json. يتم رفض الأسماء غير المعروفة بالقائمة الصحيحة، طريقة رخيصة لاكتشاف أسماء الحقول.
  • --file payload.json (أو --file - لقراءة stdin) توفر جسم طلب JSON كامل حيث يكون لدى مورد شكل معقد (على alerts create/update و settings set و users create/update). يستخدم SQL المحفوظ بدلاً من ذلك --sql @file.sql.
  • مرشحات متعددة القيم مفصولة بفواصل → مطابقة كمجموعة (اتحاد ضمن مرشح واحد، AND عبر المرشحات): --event-type tool_use,tool_result. خيارات النقر ليست متغيرة الطول، لذا --add a b فواصل. استخدم --add a,b أو كرر العلم (--add a --add b) أو علامة اقتباس (--add "a b").

مرجع الأمر

ستستخدم هذه 5 أوامر الأكثر

يعمل معظم العمل اليومي من خلال حفنة من أوامر القراءة. ابدأ هنا، ثم اوصل إلى السطح الكامل أدناه عند الحاجة إليه:

كل شيء يمكن أن يفعله CLI

يتبع السطح الكامل. لديها CLI 18 أمر على المستوى الأعلى. تقبل جميع أوامر القراءة --json والخيارات العامة أعلاه؛ قم بتشغيل agenteye <command> -h (أو <command> <subcommand> -h) لقائمة العلم الشاملة وشكل JSON لأي واحد.

الهوية: login · logout · whoami · orgs · version · help

orgs يفحص ويبدل المستأجر النشط:

ملاحظة (قراءة فقط): events · sessions · evals · errors · list

لا يحتاج أي من هؤلاء تأكيداً. مرشحات مشتركة: --session-id و --agent-id و --env (ليس --environment) ونطاق الوقت (--since / --from / --to).
--score KEY:MIN..MAX (على evals وليس sessions) قابلة للتكرار و AND-combined؛ كل حد اختياري (..0.5 يعني ≤ 0.5 و 0.9.. يعني ≥ 0.9). حتى 20 مرشح نتيجة لكل طلب. evals --scores-full هي علم عرض لـ الجدول البشري فقط؛ يُظهر كل زوج نتيجة بدلاً من الأول والقليل بالإضافة إلى عد +N. لا تأثير تحت --json، الذي يُرجع دائماً كائن النتيجة الكامل. لقراءة جلسة واحدة من البداية إلى النهاية، دمج مسار الحدث مع تقييمه:

إدارة (تحت حراسة الأذونات): keys · users · settings · alerts · incidents

keys: مفاتيح API. يتم إنشاء السر محلياً وإرساله إلى الخادم (الذي يخزن فقط تجزئة) و يظهر مرة واحدة على الإنشاء/إعادة الإنشاء؛ التقطها إذاً. مع --json يظهر فقط في حقل key. المرجعية ب الاسم.
تعمل الأذونات كـ (permission-set ∪ --add) − --remove. الرموز هي slug:action (على سبيل المثال events:read) أو slug:action.action لتوسيع عدة على مورد واحد (events:read.addevents:read و events:add). الإعدادات المسبقة: read-only و standard و admin. الأذونات البشرية فقط (keys:update) لا يمكن منحها لمفتاح. users: أعضاء المنظمة، المرجعية ب البريد الإلكتروني (يُقبل أيضاً معرف UUID).
settings: سجل ثابت (تقرأ وتغير المفاتيح الموجودة؛ لا يمكنك إنشاء واحد جديد).
alerts: تعريفات التنبيه، المرجعية ب الاسم. create يأخذ NAME موضعي بالإضافة إلى الأعلام أو جسم JSON كامل عبر --file.
incidents: حوادث التنبيه، المرجعية بـ id (معرفات قصيرة مقبولة). show يطبع سجل النشاط الكامل؛ اقرأه قبل التصرف.

التحليلات والمساعد: query · agent

query: SQL محفوظ مقابل متجر التحليلات بالإضافة إلى عداء مخصص. الاستعلامات المحفوظة المرجعية ب الاسم؛ يتم التحقق من SQL من جانب الخادم (SELECT/WITH فقط، مهلة البيان، حد الصف).
agent: يتحدث إلى مساعد الذكاء الاصطناعي المدمج (نفس محلل القراءة فقط الذي يمكنك الدردشة معه في لوحة التحكم). يتم الإشارة إلى الدردشات بـ chat-id قصير (قابل للدقة البادئة).

أكواد الخروج

وهذا يجعل CLI آمنة للنص البرمجي: يمكن لوكيل ترميز فرع على 4 لمطالبتك بإعادة المصادقة، أو 5 لسطح الأذن المفقودة. انظر وصفات CLI للوكلاء لأنماط معالجة أكواد الخروج وأشكال مخرجات JSON.

الخطوات التالية

  • وصفات CLI للوكلاء: أنماط استعلام نسخ لصق، jq سطر واحد، إسقاطات --fields، معالجة أكواد الخروج وأشكال مخرجات JSON، مكتوبة لوكلاء ترميز يقودون CLI.
  • مهارة عامل CLI: حزم هذا CLI كمهارة قابلة للتثبيت Claude Code / Codex بحيث يقود وكيل ترميز Failproof AI Observability من طلبات اللغة الطبيعية.
  • مفاتيح API: نموذج الأذن خلف keys create --add ….
  • مساعد الذكاء الاصطناعي: تفعيل المساعد الذي يتحدث معه agent ask.