CLI

Agent Analytics CLI 是已文档化 HTTP API 的官方 shell-first 包装层。当你的代理已经具备终端访问能力，并且你希望获得可预测的命令输出、同时避免 MCP 工具调用式流程的额外开销时，就应该使用它。

已发布的包名是 @agent-analytics/cli。如果你想一次性直接运行，请通过 npx 并固定版本：

npx --yes @agent-analytics/cli@0.5.33 --help

源码仓库：Agent-Analytics/agent-analytics-cli

在本页后续内容里，agent-analytics 指的都是来自同一包、同一版本的 CLI 可执行文件。

何时使用 CLI

在以下情况下优先选择 CLI：

你的代理本来就运行在 shell-first 环境中
你想要的是托管 API 之上的轻量包装层，而不是 connector 流程
你更喜欢命令组合和脚本化，而不是工具调用往返
你希望使用 login、logout、whoami、auth status 这类本地 auth 辅助命令

如果你还在不同接入路径之间做选择，而不是专门寻找 CLI 用法，请先看 Skill、MCP 与 API。

免登录 demo

如果你想让 AI agent 在连接真实账号前先试用真实 CLI/API workflow，可以使用公开 seeded demo：

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

可以直接给 agent 的提示：

“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 会从 POST /demo/session 获取一个短期只读 aas_* session，然后对托管的 agentanalytics-demo 项目运行正常读取命令。它不会暴露原始 aak_* API key，不会读写你保存的 CLI config，并会在本地拦截写入命令。

登录与本地配置

CLI 现在是 agent-session-first：

默认方式：agent-analytics login 会打开浏览器审批，并使用本地 loopback 回调
分离式交接：agent-analytics login --detached 会打印审批链接并退出，方便 issue/thread 或远程运行环境用 finish code 继续
可选轮询：agent-analytics login --detached --wait 会保持进程运行，适合可以等待浏览器审批的本地 shell
Pro 付费交接：agent-analytics upgrade-link --detached

不要把粘贴长期 API key 作为主要 onboarding 路径。浏览器审批才是标准托管流程。

CLI 会把本地配置保存到 $XDG_CONFIG_HOME/agent-analytics/config.json，如果该变量不存在，则回退到 ~/.config/agent-analytics/config.json。

在托管 agent runtime 中，home 目录下的配置不一定可靠持久化。登录前请指定一个持久目录：

export AGENT_ANALYTICS_CONFIG_DIR="$PWD/.openclaw/agent-analytics"
npx --yes @agent-analytics/[email protected] login --detached
npx --yes @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 还在环境中，CLI 就会继续优先使用它。

常用命令

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

主要命令族包括：

账户与认证：login、logout、whoami、auth status、upgrade-link
项目设置：create、projects
报表分析：stats、insights、breakdown、pages、sessions-dist、events、sessions、query
实时监控：live
结构发现：properties、properties-received
分析工作流：funnel、retention、experiments
产品反馈：feedback

项目管理

projects 会打印每个项目的名称、ID、project token 和允许的 origins。project、update、delete 可以接收精确项目名或项目 ID。

使用 update 可以直接在 CLI 中修改允许的 origins。做本地浏览器 QA 时，保留生产 origin，并添加临时本地 origin：

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

CLI 到 API 的映射

大多数 CLI 工作流都直接映射到某个 HTTP 端点。像 logout 这样的 auth 便利命令也会更新本地 CLI 状态，并可能尽力清理 session。

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`	解析名称或 ID 后调用 `GET /projects/{id}`
`agent-analytics update my-site --origins https://mysite.com`	解析名称或 ID 后调用 `PATCH /projects/{id}`
`agent-analytics delete my-site`	解析名称或 ID 后调用 `DELETE /projects/{id}`
`agent-analytics logout`	清除已保存的 CLI auth；如果有已保存的 agent session ID 和可用 token material，会尽力撤销该 agent session。

logout 会清除 CLI 保存在本地磁盘上的认证状态，并可能撤销已保存的 agent session。它不是 logout-all-devices。浏览器 /auth/logout 仅支持 POST，只清除当前浏览器 session，不会断开 CLI agents。要明确断开选定的 agent sessions，请使用 Dashboard Settings / Agent Sessions。

Query 注意事项

标准语法是 agent-analytics query <project> ...，不要使用 --project。
/events 仍然保持原始且不丢失；/query 在 event_count 上默认使用 session_then_user。
当你关心的是摄取量或重复写入排查，而不是更安全的激活计数时，请使用 --count-mode raw。
内建查询字段只有 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。
如果你需要调试底层 payload 或过滤条件，请转到 API Reference，不要把过于复杂的 shell JSON 强塞进 CLI。

CLI