> ## Documentation Index
> Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# وصفات CLI للوكلاء

> وثائق وصفات CLI للوكلاء في AgentEye.

اسحب بيانات الجلسة والحدث والتقييم (وشغّل إعادة التقييمات) مباشرة من سكريبت أو وكيل ترميز، مع JSON نظيف على stdout يتم توجيهه مباشرة إلى `jq`. تحول هذه الوصفات بيانات المراقبة في AgentEye إلى شيء يمكن لمستخدم الطرفية أو وكيل ترميز AI (Claude Code، Cursor) أن يستعلم عنه ويأتمتته، دون الحاجة للنقر عبر لوحة التحكم.

الأنماط أدناه جاهزة للنسخ واللصق لـ AgentEye CLI (`agenteye`). للتثبيت والمصادقة وقائمة الخيارات الكاملة، انظر [CLI](/ar/agenteye/cli)؛ شغّل `agenteye -h` أو `agenteye <command> -h` للمساعدة المدمجة.

## القواعد الذهبية

1. **الخيارات العامة تأتي *قبل* الأمر.** `agenteye --json sessions` صحيح؛ `agenteye sessions --json` غير صحيح. الخيارات العامة هي `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`.
2. **مرّر `--json` كلما قمت بتحليل الإخراج.** تذهب البيانات إلى **stdout** كـ JSON؛ رسائل الحالة والأخطاء البشرية تذهب إلى **stderr**، لذا يبقى stdout نظيفًا للتوجيه إلى `jq`.
3. **تفرع بناءً على رمز الخروج**، وليس على نص stderr: `0` حسنًا · `2` وسائط سيئة · `3` لا يمكن الوصول إلى لوحة التحكم · `4` لم تقم بتسجيل الدخول أو انتهت الجلسة · `5` إذن مفقود.
4. **اكتشف مع `-h`.** كل أمر يوثّق مرشحاته وتنسيقات القيمة وشكل JSON.

## إعداد لمرة واحدة

```bash theme={null}
export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com   # حتى لا تكرر --base-url
agenteye login --email you@example.com                       # الصق الرمز المرسل بالبريد؛ صالح ~24h
```

## تأكد من المصادقة قبل القيام بالعمل

`whoami` لا يخطئ أبدًا على جلسة مفقودة أو منتهية الصلاحية؛ بدلاً من ذلك يبلّغ عن `logged_in:false`، لذا يمكن للوكيل أن يفحص حالة المصادقة بأمان. (لا يزال يمكنه الخروج برمز غير صفري إذا لم يتم تعيين عنوان URL أساسي أو كانت لوحة التحكم غير قابلة للوصول.)

```bash theme={null}
if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then
  echo "Not authenticated. Run: agenteye login" >&2; exit 1
fi
```

## ابحث عن الجلسات التي تفشل أو ذات الدرجات المنخفضة

```bash theme={null}
# الجلسات في آخر 24h التي فشل تقييمها
agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id'

# التقييمات التي تسجل ≤ 0.5 على المساعدة، لوكيل واحد
agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \
  | jq '.evaluations[] | {session_id, scores}'
```

يعيش تصفية الدرجات على **`evals`**، وليس `sessions`. `--score KEY:MIN..MAX` قابل للتكرار ويتم دمجه مع AND؛ كلا الحدين اختياري (`..0.5` يعني ≤ 0.5، `0.9..` يعني ≥ 0.9). يمكنك تمرير ما يصل إلى 20 مرشح درجة لكل طلب؛ المزيد يعيد HTTP 400. `sessions` يشارك مرشحات `--env`, `--status`, `--agent-id`, `--session-id` ونطاق الوقت مع `evals`، لكنه لا يحتوي على `--score`.

## اقرأ جلسة واحدة من البداية للنهاية

لا يوجد أمر واحد `session show` — ادمج مسار الحدث مع تقييم الجلسة:

```bash theme={null}
# أحدث تقييم للجلسة (الحالة + الدرجات)
agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}'

# كل حدث في المشغل (ارفع --limit للفحص الكامل)
agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}'

# فقط استدعاءات الأدوات في جلسة
agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all \
  | jq '.events[].payload'
```

## احصل على كل شيء (الترقيم)

النتائج هي الأحدث أولاً والترقيم بواسطة المؤشر.

```bash theme={null}
# لقطة واحدة: احصل على ما يصل إلى 500 صف في صفحات بـ 200 صف
agenteye --json events --session-id run-001 --limit 500 --all > events.json

# الترقيم اليدوي: مرّر next_cursor للخلف
page=$(agenteye --json events --limit 100)
cursor=$(echo "$page" | jq -r '.next_cursor // empty')
[ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor"
```

## اختصر الإخراج مع --fields

قيّد المفاتيح (في الجدول و`--json`) لتقليل ما يجب على الوكيل قراءته.

```bash theme={null}
agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]'
agenteye --json events --session-id run-001 --fields ts,event_type --all
```

أسماء الحقول غير المعروفة يتم رفضها (خروج `2`) مع القائمة الصحيحة، وهي طريقة رخيصة لاكتشاف أسماء الحقول.

## اكتشف قيم المرشح الصحيحة

```bash theme={null}
agenteye --json list envs | jq -r '.values[]'           # قيم --env
agenteye --json list tools | jq -r '.values[]'          # أسماء الأدوات؛ أيضًا وكلاء، نماذج، event_types، إلخ
agenteye --json list score_filters | jq -r '.values[]'  # KEY الصحيح لـ --score KEY:MIN..MAX
```

## اختر منظمتك (متعدد المستأجرين)

إذا كنت تنتمي إلى أكثر من منظمة واحدة، اختر المستأجر النشط عند تسجيل الدخول (سيتم حفظه):

```bash theme={null}
agenteye login --org acme --email you@corp.com   # عيّن المستأجر في نفس خطوة تسجيل الدخول
agenteye --json orgs list | jq -r '.orgs[].org_slug'
agenteye --org globex --json sessions --since 24h   # اجعله قيد السريان لأمر واحد
```

تسجيل دخول متعدد المنظمات بدون `--org` يخرج برمز غير صفري ويطبع المنظمات للاختيار من بينها.

## توفير مفتاح API لـ SDK/المجمِّع

```bash theme={null}
# يتم طباعة السر مرة واحدة فقط — مع --json إنه حقل .key
key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key')
agenteye keys regenerate ci-bot --yes    # دوّر؛ agenteye keys disable ci-bot --yes للإلغاء
```

## شغّل استعلامًا محفوظًا أو مخصصًا

```bash theme={null}
agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows'
agenteye --json query run errs --arg prod | jq '.rows'   # استعلام محفوظ + وسيط موضعي $1
```

## فرز حادثة طارئة بدون تفاعل

```bash theme={null}
id=$(agenteye --json incidents list --state firing | jq -r '.incidents[0].id')
agenteye incidents ack "$id"
agenteye incidents assign "$id" --assignee you@corp.com
agenteye incidents resolve "$id" --yes
```

> التغييرات تخطي تلقائيًا مطالبة التأكيد الخاصة بها تحت `--json` أو عندما لا تكون stdin TTY، لذا لا تتعلق الوكلاء؛ مرّر `--yes`/`-y` لتخطيها صراحة في مكان آخر.

## معالجة رمز الخروج في سكريبت

```bash theme={null}
out=$(agenteye --json sessions --since 1h) || code=$?
case "${code:-0}" in
  0) echo "$out" | jq '.sessions | length' ;;
  4) echo "Session expired - run 'agenteye login'." >&2 ;;
  5) echo "Missing permission (ask an admin for evaluations:read)." >&2 ;;
  3) echo "Dashboard unreachable - check the URL." >&2 ;;
  *) echo "Unexpected error (exit ${code})." >&2 ;;
esac
```

## أشكال إخراج JSON

| الأمر                            | stdout JSON (مع `--json`)                                                                                                                     |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `whoami`                         | `{"logged_in": true, "id", "email", "is_instance_admin", "active_org", "permissions": [...], "memberships": [...]}` أو `{"logged_in": false}` |
| `orgs list`                      | `{"active_org", "orgs": [{"org_slug","org_name","permission_set","permissions"}]}`                                                            |
| `events`                         | `{"events": [...], "next_cursor": <cursor or null>}`                                                                                          |
| `evals`                          | `{"evaluations": [...], "next_cursor": <cursor or null>}`                                                                                     |
| `sessions`                       | `{"sessions": [...], "next_cursor": <cursor or null>}`                                                                                        |
| `errors`                         | `{"errors": [...], "next_cursor": <cursor or null>}`                                                                                          |
| `list <kind>`                    | `{"kind", "values": [...]}`                                                                                                                   |
| `keys list` / `keys create`      | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (يظهر `key` مرة واحدة)                                                         |
| `query run`                      | `{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}`                                                                              |
| `users list` / `settings list`   | `{"users": [...]}` / `{"settings": [...]}`                                                                                                    |
| `alerts list` / `incidents list` | `{"alerts": [...]}` / `{"incidents": [...]}`                                                                                                  |
| إنشاء/تحديث/حذف (أي)             | كائن المورد، أو `{"deleted": true, "id"}` للحذف                                                                                               |
| فشل (أي، مع `--json`)            | `{"error": "...", "exit_code": <n>, "status"?: <http>, "hint"?: "..."}` على stdout                                                            |

* كل عنصر **حدث** (`events`): `id, session_id, agent_id, event_type, ts, payload, environment`.
* كل عنصر **تقييم** (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`.
* كل عنصر **جلسة** (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`.

يقبل `--fields` لكل أمر بالضبط أسماء حقول عنصره الخاص — تختلف المجموعة بين `sessions` و`evals`، لذا قد يتم رفض الاسم الصحيح لأحدهما من قبل الآخر.