CLI

ה-CLI של Agent Analytics הוא ה-wrapper הרשמי והמוכוון ל-shell מעל ה-HTTP API המתועד. השתמשו בו כשהסוכן כבר מחזיק בגישת טרמינל ואתם רוצים פלט פקודות צפוי עם פחות overhead מזרימות MCP עתירות tool calls.

החבילה המתפרסמת היא @agent-analytics/cli. לשימוש חד-פעמי, הריצו אותה דרך npx עם גרסה מוצמדת:

npx @agent-analytics/cli@0.5.16 --help

מאגר מקור: Agent-Analytics/agent-analytics-cli

בהמשך העמוד, agent-analytics פירושו הבינארי של אותו CLI מאותה חבילה ואותה גרסה.

מתי להשתמש ב-CLI

בחרו ב-CLI כש:

הסוכן כבר עובד בסביבה שמתחילה מה-shell
אתם רוצים wrapper דק מעל ה-API המארח במקום connector flow
אתם מעדיפים הרכבת פקודות וסקריפטים על פני round trips של tool calls
אתם רוצים עזרי auth מקומיים כמו login, logout, whoami ו-auth status

אם אתם עדיין בוחרים בין מסלולי גישה שונים ולא מחפשים שימושיות CLI ספציפית, התחילו עם Plugin מול Skill מול MCP מול API.

demo בלי התחברות

כדי לתת לסוכן AI לנסות את ה-workflow האמיתי של CLI/API לפני חיבור חשבון, השתמשו ב-public demo עם נתונים seeded:

npx @agent-analytics/cli@0.5.16 demo
npx @agent-analytics/cli@0.5.16 --demo projects
npx @agent-analytics/cli@0.5.16 --demo stats agentanalytics-demo --days 7
npx @agent-analytics/cli@0.5.16 --demo paths agentanalytics-demo --goal signup --since 30d
npx @agent-analytics/cli@0.5.16 --demo funnel agentanalytics-demo --steps "page_view,signup_started,signup"
npx @agent-analytics/cli@0.5.16 --demo experiments list agentanalytics-demo

Prompts שימושיים:

“Run the Agent Analytics demo and tell me which page is leaking signups.”
“Use the demo data to find the highest-friction signup path.”
“Check the demo experiment and tell me whether there is a likely winner.”

--demo מבקש session קצר-חיים ו-read-only מסוג aas_* מ-POST /demo/session, ואז מריץ פקודות קריאה רגילות מול הפרויקט המארח agentanalytics-demo. הוא לא חושף API key גולמי מסוג aak_*, לא קורא או כותב את קובץ ה-config המקומי של ה-CLI, וחוסם פקודות כתיבה מקומית.

התחברות וקונפיגורציה מקומית

ה-CLI הוא agent-session-first:

ברירת מחדל: agent-analytics login פותח אישור בדפדפן עם local loopback callback
handoff מנותק: agent-analytics login --detached מדפיס קישור אישור ויוצא, כדי שסביבות מבוססות issue או remote יוכלו להמשיך עם finish code
polling אופציונלי: agent-analytics login --detached --wait משאיר את התהליך חי עבור shell מקומי שיכול להמתין לאישור בדפדפן
מתקדם/ידני בלבד: agent-analytics login --token aak_...

אל תציגו הדבקה של API keys ארוכי-חיים כנתיב onboarding ראשי. אישור בדפדפן הוא ה-flow המארח הרגיל.

ה-CLI שומר קונפיגורציה מקומית ב-$XDG_CONFIG_HOME/agent-analytics/config.json, עם fallback ל-~/.config/agent-analytics/config.json.

בסביבות agent מנוהלות שבהן קונפיגורציית home לא תמיד נשמרת, הגדירו תיקייה מתמשכת לפני login:

export AGENT_ANALYTICS_CONFIG_DIR="$PWD/.openclaw/agent-analytics"
npx @agent-analytics/[email protected] login --detached
npx @agent-analytics/[email protected] auth status

אפשר גם להעביר --config-dir "$PWD/.openclaw/agent-analytics" לפני או אחרי כל פקודה. סדר הפתרון הוא: --config-dir, אחר כך AGENT_ANALYTICS_CONFIG_DIR, אחר כך $XDG_CONFIG_HOME/agent-analytics, ולבסוף ~/.config/agent-analytics.

עדיין יש עדיפות למשתני סביבה, ולכן AGENT_ANALYTICS_API_KEY ימשיך לנצח עד שתבטלו אותו.

פקודות נפוצות

agent-analytics projects
agent-analytics whoami
agent-analytics auth status
agent-analytics create my-site --domain https://mysite.com
agent-analytics stats my-site --days 7
agent-analytics insights my-site --period 7d
agent-analytics events my-site --days 7 --limit 20
agent-analytics breakdown my-site --property path --event page_view --days 7 --limit 10
agent-analytics funnel my-site --steps "page_view,signup,purchase"
agent-analytics retention my-site --period week --cohorts 8
agent-analytics experiments list my-site
agent-analytics logout

משפחות הפקודות העיקריות הן:

חשבון ו-auth: login, logout, whoami, auth status, revoke-key
הקמת פרויקטים: create, projects
דוחות: stats, insights, breakdown, pages, sessions-dist, events, sessions, query
ניטור חי: live
גילוי סכימה: properties, properties-received
workflows אנליטיים: funnel, retention, experiments
משוב מוצר: feedback

ניהול פרויקטים

projects מדפיסה לכל פרויקט את השם, ה-ID, ה-project token וה-origins המותרים. project, update ו-delete מקבלות שם פרויקט מדויק או ID.

השתמשו ב-update כדי לשנות origins מותרים בלי לצאת מה-CLI. עבור QA בדפדפן מקומי, השאירו את ה-origin של ה-production והוסיפו את ה-origin המקומי הזמני:

agent-analytics update stylio --origins 'https://stylio.app,http://lvh.me:3101'

מיפוי CLI ל-API

רוב ה-workflows של ה-CLI ממופים ישירות לנקודת קצה ב-HTTP. החריג המרכזי הוא פקודות נוחות של auth מקומי כמו logout, שמשנות רק מצב מקומי של ה-CLI.

CLI Command	API Endpoint
`agent-analytics stats my-site`	`GET /stats?project=my-site`
`agent-analytics all-sites --period 7d`	`GET /account/all-sites?period=7d`
`agent-analytics bot-traffic my-site --period 7d`	`GET /bot-traffic?project=my-site&period=7d`
`agent-analytics bot-traffic --all --period 7d`	`GET /account/bot-traffic?period=7d`
`agent-analytics events my-site`	`GET /events?project=my-site`
`agent-analytics query my-site --metrics event_count`	`POST /query`
`agent-analytics query my-site --metrics event_count --count-mode raw`	`POST /query`
`agent-analytics funnel my-site --steps "page_view,signup,purchase"`	`POST /funnel`
`agent-analytics retention my-site --period week --cohorts 8`	`GET /retention?project=my-site&period=week&cohorts=8`
`agent-analytics experiments list my-site`	`GET /experiments?project=my-site`
`agent-analytics experiments create my-site --name signup_cta --variants control,new_cta --goal signup`	`POST /experiments`
`agent-analytics experiments get exp_abc123`	`GET /experiments/{id}`
`agent-analytics projects`	`GET /projects`
`agent-analytics project my-site`	`GET /projects/{id}` אחרי פתרון שם או ID
`agent-analytics update my-site --origins https://mysite.com`	`PATCH /projects/{id}` אחרי פתרון שם או ID
`agent-analytics delete my-site`	`DELETE /projects/{id}` אחרי פתרון שם או ID
`agent-analytics logout`	None. פקודה מקומית בלבד שמוחקת auth שמור של CLI ולא קוראת ל-API.

logout מוחק את מצב ה-auth שה-CLI שמר על הדיסק. הוא לא מבטל קרדנצ’לים בשרת.

הערות על query

הצורה התקינה היא agent-analytics query <project> .... אל תשתמשו ב---project.
/events נשאר raw ו-lossless. ברירת המחדל של /query עבור event_count היא session_then_user.
השתמשו ב---count-mode raw כשהשאלה עוסקת בנפח ingestion או בדיבוג כתיבות כפולות, לא בספירות activation-safe.
שדות query מובנים הם event, user_id, date, country, session_id ו-timestamp.
שדות לא מובנים כמו referrer, utm_source, path, browser ו-hostname צריכים להיכתב כ-properties.<key>.
group_by מוגבל לשדות המובנים בלבד: event, date, user_id, session_id ו-country.
אם צריך לדבג payloads או filters ברמת HTTP, עברו ל-API Reference במקום להעמיס JSON מורכב על ה-CLI.

CLI