CLI

נהל את כל Failproof AI Observability מהטרמינל או מסקריפט: ללא צורך בגלישה בדashboard. ה-CLI של agenteye שואל על הנתונים שלך (sessions, event logs, evaluations) וממנהל את הארגון שלך (API keys, users, settings, alerts, incidents, saved queries), אז הפנה אליו כאשר אתה רוצה להוסיף בדיקה אוטומטית, לחבר Observability ל-CI, או להשאיר לagent לבדוק production. כל פקודה תומכת בדגל --json, כך שהיא עובדת באותה מידה טובה בשבילך בשורת הפקודה או לagent שמריץ ודורס את התוצאה. עם בינארי אחד אתה יכול:

קרוא את הנתונים שלך: sessions, events, evals, errors (סנן לפי זמן, agent, env, score).
נהל את הארגון שלך: keys, users, settings, alerts, incidents.
הרץ ניתוחים: SQL שמור ומריץ query ad-hoc (query).
שאל את עוזר ה-AI: אותו analyst read-only שאתה משוחח איתו בdashboard (agent).

הערה: זה ה-CLI של agenteye, כלי שונה מה-collector daemon (agenteye-collector). ה-CLI מדבר עם dashboard שלך; ה-collector שולח events לשרת.

התחלה מהירה

מלא אפס עד התוצאה הראשונה שלך בארבע שורות. אתחל את ה-CLI לdashboard שלך, התחבר, אשר מי אתה, ואז משוך את יום אחרון של runs:

pipx install agenteye
agenteye --base-url https://agenteye.example.com login --email you@example.com   # emailed 6-digit code
agenteye whoami                                                                  # confirm user + active org
agenteye --json sessions --since 24h                                             # one row per agent run, last 24h

הפקודה האחרונה מדפיסה אובייקט JSON של ה-sessions האחרונים ביותר (החדשים ביותר קודם, מוגבלים ל-50 כברירת מחדל). Pipe את זה ל-jq כדי לחתוך אותו, או הסר --json לטבלה boxed וצבעונית. כל שורה נושאת את status של ה-run, ואם evaluator נתן ציון, את ציוני המטריקות שלו (מקוצר כאן):

{
  "sessions": [
    {
      "session_id": "run-8f2a",
      "agent_id": "checkout-bot",
      "environment": "prod",
      "status": "error",
      "scores": { "helpfulness": 0.42, "tool_efficiency": 0.55 },
      "event_count": 37,
      "started_at": "2026-07-16T09:14:02Z",
      "last_event_at": "2026-07-16T09:14:48Z"
    }
  ],
  "next_cursor": null
}

שאר הדף מסביר כל חלק: התקנה בבידוד, התחברות, תצורה, הקונבנציות הגלובליות שכל פקודה משתפת, והפניה המלאה לפקודות.

התקנה

ה-CLI הוא חבילת PyPI ציבורית בשם agenteye. התקן אותו בסביבה מבודדת כך שיהיה לו תמיד תלויות משלו:

pipx install agenteye
# or
uv tool install agenteye

זה דורש Python 3.10+. הפקודה המותקנת היא agenteye:

agenteye --version
agenteye --help

הערה: ה-Python SDK של Failproof AI Observability משתמש גם בשם ההפצה agenteye. התקנת ה-CLI עם pipx או uv tool (במקום pip install לתוך virtualenv משותף) מונעת התנגשות בין השניים. pip install agenteye פשוט בסדר רק אם ה-SDK לא מותקן באותה סביבה.

התחברות

ה-CLI מתחבר ל-dashboard עם קוד חד-פעמי בדואר:

agenteye login --email you@example.com
# A 6-digit code is emailed to you; paste it at the prompt.

토큰ה-session מאוחסן ב-~/.agenteye/cli.json (קריא רק לך, mode 0600) והוא תקף למשך 24 שעות כברירת מחדל. כאשר הוא פג, הרץ agenteye login שוב.

agenteye whoami     # show the current user, active org, and permissions
agenteye logout     # revoke the session and clear the stored token

whoami לעולם לא נכשל בsession חסר או פג; הוא מדווח על logged_in: false במקום זאת, כך שסקריפט או agent יכול לבדוק את מצב ה-auth בבטחה (הוא עדיין יכול להיכשל עם non-zero אם לא מוגדר base URL או ה-dashboard לא זמין). דרישות: הדואר שלך חייב להיות מורשה להתחבר לdashboard (שאל את מנהל Failproof AI Observability שלך), וה-dashboard חייב להיות זמין ב-base URL שלו (ראה Configuration). אם אתה מבקש קוד וכלום לא מגיע, הדואר שלך כנראה עדיין לא מופעל לגישה לdashboard.

בחר את ה-org שלך (multi-tenant)

אם החשבון שלך שייך ליותר מ-org אחד, בחר את ה-active בזמן login; זה נשמר ומשמש לכל פקודה מאוחרת:

agenteye login --org acme           # authenticate and set the active tenant in one step
agenteye orgs list                  # the orgs you can access (the active one is marked)
agenteye orgs switch globex         # change the saved default
agenteye --org globex sessions      # override for a single command

אם אתה שייך בדיוק לorg אחד הוא נבחר אוטומטית ואתה יכול להתעלם מ---org לחלוטין. אם אתה שייך לכמה ולא בחרת אחד, ה-CLI מרשימה אותם ושואל אותך להריץ מחדש עם --org <slug>. ה-org הpublic הactive נשלח לdashboard בכל בקשה, וההרשאות שלך מסולרות per org; agenteye whoami מציגה את ה-org הactive, ההרשאות שלך בו, והחברויות שלך.

תצורה

הגדרה	דגל	משתנה סביבה	ברירת מחדל
Dashboard base URL	`--base-url`	`AGENTEYE_DASHBOARD_URL`	required (no default)
Active org/tenant	`--org`	`AGENTEYE_ORG`	chosen at login; saved in `~/.agenteye/cli.json`
Session token	`--token`	`AGENTEYE_CLI_TOKEN`	from `~/.agenteye/cli.json`
JSON output	`--json`	`AGENTEYE_CLI_JSON`	off
Skip TLS verification	`--insecure` / `--secure`	`AGENTEYE_INSECURE`	off (saved at login)
Request timeout (seconds)	`--timeout`	(none)	30
Disable usage telemetry	(none)	`AGENTEYE_ANALYTICS_DISABLED` (or `DO_NOT_TRACK`)	telemetry is currently disabled; nothing is sent

סדר ההחלטה הוא flag → environment variable → config file. אין ברירת מחדל; חייב לאתחל את ה-CLI לdashboard שלך, או per-command (--base-url https://agenteye.example.com) או פעם אחת דרך הסביבה (זה גם נשמר לאחר login הראשון שלך):

export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com

ספריית התצורה מכבדת AGENTEYE_HOME (אותה קונבנציה המשמשת את ה-SDK וה-collector); אם מוגדר, cli.json חי ב-$AGENTEYE_HOME/cli.json.

TLS חתום עצמי או פנימי

אם ה-dashboard שלך מוזן דרך HTTPS עם תעודה חתומה עצמית או פנימית (לדוגמה, שם host raw load-balancer), אימות TLS דוחה אותו עם שגיאת CERTIFICATE_VERIFY_FAILED. עבור --insecure כדי לדלג על אימות תעודה:

agenteye --base-url https://agenteye.internal --insecure login

--insecure הוא נשמר ל-cli.json כאשר אתה מתחבר, כך שפקודות מאוחרות יותר דילוג אימות אוטומטי; אתה לא צריך לחזור על הדגל. עבור --secure לקול מאומת חד-פעמי, או כדי לשמור אימות חזרה על ב-login הבא שלך. ה-CLI מדפיס אזהרה ל-stderr לפני כל פקודה שמתקשרת לdashboard בזמן אימות מכובה. דילוג אימות מסיר הגנה נגד התקפות man-in-the-middle; ודא שאתה סומך על נתיב הרשת לdashboard (VPN, private subnet, וכו’) לפני שאתה מסתמך עליו.

Telemetry & privacy

הערה: ה-CLI המסופק שולח שום telemetry שימוש היום. מתג הרג ראשי הוא פועל, כך שלום לא משודר בכל סביבה. הקטע שלהלן מתאר את יכולת ה-opt-out לאם וכאשר telemetry כשהוא מופעל אי פעם.

גם כשמופעל, telemetry יהיה analytics שימוש אנונימי בלבד, לא מעולם ה-agent, session, או event שלך:

לא ה-agent, session, או event שלך כשהוא משאיר את התשתית שלך. רק שימוש CLI יהיה מדווח: הפקודה ו-subcommand name (לדוגמה keys create), names של הדגלים שהשתמשת בהם (לא פעם את הערכים שלהם), success/exit status, ודווח, בתוספת per-action event לmutations (לדוגמה api_key_created, query_run) בנשיאה שמות/enums סטטיים בלבד וספירות גס. ה-dashboard URL שלך, session token, דואר, org slug, resource ids, SQL, key secrets, וquery filters היו never שלח. אופרטורים היו מזוהים רק ב-opaque internal id, לא לפי דואר.
Opt out מראש על ידי הגדרה AGENTEYE_ANALYTICS_DISABLED=1 בסביבה של ה-CLI (ה-CLI גם מכבד את ה-cross-tool DO_NOT_TRACK=1 קונבנציה). זה נכנס לתוקף ברגע telemetry הוא אי פעם הופכת, כך שסביבה privacy-conscious יכולה להישאר opted out לצמיתות.
אם telemetry היו מופעל, ה-CLI היה שלח ישירות ל-PostHog (https://us.i.posthog.com); מכונה עם host זה חסום היא שקט לא שלח כלום וה-CLI היה unaffected.

Global options & conventions

קרא את זה פעם אחת; זה חל לכל פקודה.

Global options לך לפני הפקודה. agenteye --json sessions הוא נכון; agenteye sessions --json היא שגיאת שימוש. ה-globals הם --json, --base-url, --org, --token, --insecure/--secure, --timeout, --quiet, ו---no-color.
--json מדפיס pure JSON ל-stdout, וכלום אחר. Human status lines, הערות, ושגיאות לך ל-stderr, כך ש---json stdout capture נשאר נקי ל-pipe לתוך jq גם כאשר status line מוצג. ללא --json אתה משיג boxed, צפוי בחזרה לעיני אדם.
גלה עם --help. כל פקודה וsub-command יש --help (ו--h alias): agenteye -h, agenteye sessions -h, agenteye keys create -h. העזרה ברמה העליונה גם רשימות exit codes וגלובליות אפציות. אין global machine-readable surface dump; השתמש per-command --help, בתוספת domain-specific agenteye query schema ו-agenteye settings schema לשניים אלו registries.
Confirmations auto-skip לscrips וagents. Create/update/delete פקודות הנושא “האם אתה בטוח?” בטרמינל interactive, אבל auto-skip שהנושא תחת --json או בכל פעם stdin אינו TTY (TTY הוא interactive terminal session; pipe או CI runner לא), כך שscrips וagents לא תלויים. עבור --yes/-y כדי לדלג עליו במפורש. מכיוון שהנושא לא יקום לagent, agent צריך לאשר משימות destructive עם אדם ראשון.
Pagination: תוצאות הן newest-first וcursor-paginated (כל עמוד חוזר token אתה משתמש כדי להביא את הבא). --limit N (alias -n) caps rows וdefaults ל-50; --all auto-paginates (בחלקי 200-row) עד --limit, כך צרה --all עדיין עוצר ב-50. לעבור מלא עבור pass a גבוה explicit cap: --all --limit 1000. --page-size N שליטה per-request chunk (max 200); --cursor <id> resumes מא prior page’s next_cursor.
Time filters: --since לוקח a relative window: 15m, 1h, 6h, 24h, 7d, או all (dashboard’s presets). לארוך או custom range (say 30 ימים האחרונים), השתמש --from/--to: explicit ISO-8601 UTC timestamps עם T וtimezone (לדוגמה 2026-06-01T00:00:00Z) כי override --since. space-separated או timezone-less value היא שגיאת שימוש.
--fields a,b,c (על events, sessions, evals, errors) מגביל את הפלט לאלו מקשים, עבור שניהם הטבלה ו---json. שמות לא ידועים דחויים עם הרשימה תקפה, דרך זול לגלות שמות שדה.
--file payload.json (או --file - לקרוא stdin) מספק מלא JSON request body כאשר משאב יש צורה מורכבת (על alerts create/update, settings set, ו-users create/update). Saved-query SQL משתמש --sql @file.sql במקום.
Multi-value filters הם comma-separated → matched כ-set (union בתוך filter אחד, AND throughout filters): --event-type tool_use,tool_result. Click אפציות אינם variadic, כך --add a b שבירות. השתמש --add a,b, חזור הדגל (--add a --add b), או ציטוט (--add "a b").

Command reference

אתה תשתמש בחמשת הפקודות הללו ביותר

יום רביעי של עבודה מתבצעות דרך של קצת read commands. התחל כאן, אז הגע עבור המשטח המלא להלן כאשר אתה צריך:

פקודה	מה זה עושה	נסה את זה
`sessions`	שורה אחת לכל agent run: זמן, env, agent, status, ציון לאחרונה.	`agenteye --json sessions --since 24h --status error`
`events`	ה-raw per-step trail בתוך run (הוסף `--full` לtayloads).	`agenteye --json events --session-id run-001 --all`
`evals`	תוצאות הערכה וציונים; `--aggregate` rolls them up.	`agenteye --json evals --aggregate --since 7d --env prod`
`errors`	רק את errored events; `--aggregate` לספירה לפי סוג.	`agenteye --json errors --since 24h --aggregate`
`list`	גלה את ערכי ה-filter תקפה (agents, envs, models, …).	`agenteye list agents`

כל מה ש-CLI יכול לעשות

המשטח המלא עוקב. ל-CLI יש 18 פקודות top-level. כל read commands קבל --json וגלובליות אפציות לעיל; הרץ agenteye <command> -h (או <command> <subcommand> -h) לexhaustive flag list וJSON shape של כל אחד.

agenteye login --email you@example.com [--org acme]   # emailed one-time code; saves the session
agenteye logout                                       # clear the saved session on this machine
agenteye whoami                                       # current user, active org, permissions
agenteye version                                      # print the CLI version (same as --version)
agenteye help                                         # top-level help (same as --help)

orgs inspects וscreens ה-active tenant:

agenteye orgs list        # your orgs + your role in each (active one marked)
agenteye orgs switch acme # change the saved active org (omit the slug to pick from a list on a TTY)
agenteye orgs current     # identity card for the active org
agenteye orgs perms       # your permissions in the active org, grouped by resource

Observe (read-only): `events` · `sessions` · `evals` · `errors` · `list`

אף אחד מאלה צרך confirmation. Shared filters: --session-id, --agent-id, --env (לא --environment), וה-time range (--since / --from / --to).

# events (alias: the raw per-step trail), newest first
agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all --limit 1000
agenteye --json events --since 1h --search timeout --all | jq '.events[].payload'

# sessions: one row per agent run (time/env/agent/session/status; no score filtering)
agenteye --json sessions --since 24h --status error
agenteye --json sessions --agent-id checkout-bot --env prod --all --limit 1000

# evals: evaluation results + scores; --score filters by metric, --aggregate rolls up
agenteye --json evals --score helpfulness:0.5..0.8 --score tool_efficiency:..0.3
agenteye --json evals --aggregate --since 7d --env prod        # status mix + per-key score stats

# errors: errored events; --aggregate for counts/sessions/agents/last-seen
agenteye --json errors --since 24h --aggregate
agenteye --json errors --since 24h --error-type timeout --all --limit 1000

# list: discover valid filter values before you filter
agenteye list envs        # also: agents event_types score_filters models hooks tools error_types

--score KEY:MIN..MAX (על evals, לא sessions) הוא repeatable וAND-combined; שניהם bound הם אופציוניים (..0.5 אומר ≤ 0.5, 0.9.. אומר ≥ 0.9). עד 20 score filters לבקשה. evals --scores-full היא display flag עבור ה-human table בלבד; זה מראה כל score pair במקום את הראשון כמה בתוספת +N count. זה אין השפעה תחת --json, שתמיד מחזיר את object score מלא. לקרוא one session end-to-end, שלב את ה-event trail עם הערכתו:

agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}'
agenteye --json evals  --session-id run-001                       # its scores + status

Manage (permission-gated): `keys` · `users` · `settings` · `alerts` · `incidents`

keys: API keys. הסוד נוצר מקומית, שלח לשרת (אשר stores רק hash), ו-shown פעם אחת על create/regenerate; capture זה אז. עם --json זה מופיע רק בשדה key. Referenced by name.

agenteye keys list                                   # active keys first, then revoked
agenteye keys show ci-bot
agenteye keys create ci-bot --add events:read.add    # scope to what you need; prints the secret ONCE
agenteye keys create ops --permission-set standard --remove queries:run   # seed a preset, then trim
agenteye keys update ci-bot --add evaluations:read --yes
agenteye keys regenerate ci-bot --yes                # rotate the secret (the old one stops working)
agenteye keys disable ci-bot --yes                   # revoke

הרשאות עבודה כמו (permission-set ∪ --add) − --remove. Tokens הם slug:action (לדוגמה events:read) או slug:action.action להרחיב כמה על משאב אחד (events:read.add → events:read, events:add). Presets: read-only, standard, admin. Human-only הרשאות (keys:update) לא יכול להיות כן ל-key. users: org members, referenced by email (UUID id נכנס גם accepted).

agenteye users list [--active-only]
agenteye users show dev@corp.com
agenteye users create dev@corp.com --permission-set standard
agenteye users update dev@corp.com --add alerts:write --remove queries:delete   # predicts + confirms
agenteye users disable dev@corp.com --yes            # has protected/self guards
agenteye users enable dev@corp.com

settings: fixed registry (אתה קורא ושנה קיים keys; אתה לא יכול ליצור חדש).

agenteye settings list                               # key · value · type · updated (secrets masked)
agenteye settings schema                             # what each key accepts (type · range · description)
agenteye settings set session_ttl_secs --value 86400 --yes

alerts: הגדרות alert, referenced by name. create לוקח positional NAME בתוספת flags או מלא JSON body דרך --file.

agenteye alerts list
agenteye alerts show high-errors
agenteye alerts create high-errors --file alert.json          # NAME is required (positional)
agenteye alerts update high-errors --severity critical --yes
agenteye alerts test high-errors --yes                        # fire a test notification
agenteye alerts delete high-errors --yes

incidents: alert incidents, referenced by id (short ids accepted). show prints ה-full activity log; קרא את זה לפני פועל.

agenteye incidents list --state firing                # also: acknowledged, resolved
agenteye incidents count
agenteye incidents show <id>
agenteye incidents ack <id>
agenteye incidents assign <id> you@corp.com           # assignee must be an operator
agenteye incidents resolve <id> --yes
agenteye incidents open --alert-id <id> --severity critical    # open one manually against an alert
agenteye incidents comment-add <id> "root cause: upstream 5xx"
agenteye incidents comment-list <id> ; agenteye incidents comment-delete <id> <comment-id>
agenteye incidents subscribe <id> ; agenteye incidents unsubscribe <id> ; agenteye incidents subscribers <id>

Analytics & assistant: `query` · `agent`

query: saved SQL נגד analytics store בתוספת ad-hoc runner. Saved queries הם referenced by name; ה-SQL הוא validated server-side (SELECT/WITH רק, statement timeout, row cap).

agenteye query schema [TABLE]                         # column layout of the analytics views
agenteye query run --sql "select count(*) from analytics.events"
agenteye query run errs --arg prod --limit 100        # run a saved query + a positional $1
agenteye query list ; agenteye query show errs
agenteye query create errs --sql @errs.sql --description "errored events (24h)"
agenteye query update errs --sql @errs.sql --yes ; agenteye query delete errs --yes

agent: דברים ל-built-in AI assistant (אותו read-only analyst אתה יכול לשוחח עם בdashboard). Chats הם referenced by short chat-id (prefix-resolved).

agenteye agent health                                 # is the AI assistant configured/reachable
agenteye agent models                                 # models you can pass to --model (default marked)
agenteye agent ask "which agents errored most in the last day?"    # starts a chat; prints its short id
agenteye agent ask --chat <short-id> "and which tools did they call?"   # continue that chat
agenteye agent chats ; agenteye agent show <short-id>
agenteye agent rename <short-id> --title "error triage" ; agenteye agent delete <short-id>

Exit codes

קוד	משמעות
0	הצלחה
1	שגיאה לא צפויה (לדוגמה ה-dashboard החזיר 5xx)
2	שגיאת שימוש (ארגומנטים לא תקפה, פקודה/דגל לא ידוע, שם collision)
3	לא יכול להגיע ל-dashboard
4	לא התחבר או session פג; הרץ `agenteye login`
5	Authenticated, אבל החשבון שלך חסר את ההרשאה הנדרשת (ההודעה קורא את זה)
6	משאב המבוקש לא היה found (לדוגמה session לא ידוע או incident id)

אלה עושים את ה-CLI בטוח לsript: coding agent יכול branch על 4 להנושא אותך re-authenticate, או 5 to surface החסרה הרשאה. ראה CLI recipes לagents עבור exit-code-handling דפוסים וJSON output צורות.

הצעדים הבאים

CLI recipes לagents: copy-paste query דפוסים, jq one-liners, --fields הקרנות, exit-code handling, וJSON output צורות, כתוב עבור agents coding driving ה-CLI.
CLI agent skill: חבילה זה CLI כמו installable Claude Code / Codex skill כך agent coding drives Failproof AI Observability מ-plain-English בקשות.
API keys: דגם ההרשאה מאחוריי keys create --add ….
AI assistant: enabling ה-assistant כי agent ask דברים ל.

Overview

Features

SDK and CLI

Administration

התחלה מהירה

התקנה

התחברות

בחר את ה-org שלך (multi-tenant)

תצורה

TLS חתום עצמי או פנימי

Telemetry & privacy

Global options & conventions

Command reference

אתה תשתמש בחמשת הפקודות הללו ביותר

כל מה ש-CLI יכול לעשות

Observe (read-only): `events` · `sessions` · `evals` · `errors` · `list`

Manage (permission-gated): `keys` · `users` · `settings` · `alerts` · `incidents`

Analytics & assistant: `query` · `agent`

Exit codes

הצעדים הבאים

​התחלה מהירה

​התקנה

​התחברות

​בחר את ה-org שלך (multi-tenant)

​תצורה

​TLS חתום עצמי או פנימי

​Telemetry & privacy

​Global options & conventions

​Command reference

​אתה תשתמש בחמשת הפקודות הללו ביותר

​כל מה ש-CLI יכול לעשות

​Identity: login · logout · whoami · orgs · version · help

​Observe (read-only): events · sessions · evals · errors · list

​Manage (permission-gated): keys · users · settings · alerts · incidents

​Analytics & assistant: query · agent

​Exit codes

​הצעדים הבאים

התחלה מהירה

התקנה

התחברות

בחר את ה-org שלך (multi-tenant)

תצורה

TLS חתום עצמי או פנימי

Telemetry & privacy

Global options & conventions

Command reference

אתה תשתמש בחמשת הפקודות הללו ביותר

כל מה ש-CLI יכול לעשות

Identity: `login` · `logout` · `whoami` · `orgs` · `version` · `help`

Observe (read-only): `events` · `sessions` · `evals` · `errors` · `list`

Manage (permission-gated): `keys` · `users` · `settings` · `alerts` · `incidents`

Analytics & assistant: `query` · `agent`

Exit codes

הצעדים הבאים