agenteye CLI 可查询您的数据（会话、事件日志、评估结果）并管理您的组织（API 密钥、用户、设置、告警、事件、已保存查询），非常适合自动化检查、将 Observability 集成到 CI 流程，或让编码智能体检查生产环境。每个命令均支持 --json 标志，因此无论是您在终端交互使用，还是编码智能体（Claude Code、Cursor）调用并解析结果，都同样适用。
使用这一个二进制文件，您可以：
- 读取数据：
sessions、events、evals、errors（按时间、智能体、环境、评分筛选）。 - 管理组织：
keys、users、settings、alerts、incidents。 - 运行分析：已保存的 SQL 和临时查询执行器（
query）。 - 咨询 AI 助手：与控制台中相同的只读分析师（
agent）。
注意： 这是agenteyeCLI，与采集器守护进程（agenteye-collector）是不同的工具。CLI 与您的控制台通信；采集器负责将事件上报到服务器。
快速开始
从零到获得第一个结果只需四行命令。将 CLI 指向您的控制台，登录，确认身份，然后拉取最近一天的运行记录：jq 进行切片处理，或去掉 --json 以获得带边框的彩色表格。每行包含运行状态，以及评估器评分后的指标分数（此处为简略版）：
安装
CLI 是一个公开的 PyPI 包，名为agenteye。建议安装到隔离环境中，以确保其拥有独立的依赖项：
agenteye：
注意： Failproof AI Observability Python SDK 也使用agenteye这个发行包名称。使用pipx或uv tool安装 CLI（而非pip install到共享虚拟环境中）可以避免两者冲突。只有在同一环境中未安装 SDK 的情况下，才可以直接使用pip install agenteye。
认证
CLI 通过邮件一次性验证码向控制台进行身份验证：~/.agenteye/cli.json 中（仅您本人可读，权限为 0600），默认有效期为 24 小时。过期后，重新运行 agenteye login 即可。
whoami 在会话缺失或过期时不会报错，而是返回 logged_in: false，因此脚本或智能体可以安全地探测认证状态（如果未设置 base URL 或控制台不可达，仍可能以非零状态退出）。
要求： 您的邮箱必须获准登录控制台（请联系您的 Failproof AI Observability 管理员），且控制台必须可通过其 base 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、私有子网等）。
遥测与隐私
注意： 目前发布的 CLI 不发送任何使用遥测数据。 主开关处于关闭状态，无论您的环境如何配置，均不会传输任何数据。以下内容描述了一旦遥测功能启用时的退出机制。即使在启用状态下，遥测也仅为匿名使用分析数据，绝不包含您的智能体、会话或事件数据：
- 您的智能体、会话或事件数据绝不会离开您的基础设施。 仅上报 CLI 使用情况：命令和子命令名称（例如
keys create）、您使用的标志名称（绝不包含标志值）、成功/退出状态和耗时，以及变更操作的单次事件（例如api_key_created、query_run，仅包含静态名称/枚举和粗略计数）。您的控制台 URL、会话令牌、邮箱、组织 slug、资源 id、SQL、密钥密文和查询过滤器绝不会被发送。运营者仅以不透明的内部 id 标识，绝不以邮箱标识。 - 提前退出可通过在 CLI 环境中设置
AGENTEYE_ANALYTICS_DISABLED=1（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仅向 stdout 输出纯 JSON，不输出其他内容。 人类可读的状态行、警告和错误均输出到 stderr，因此--json的 stdout 捕获保持干净，即使显示了状态行也可以直接通过管道传给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（别名-n）限制行数，默认为 50；--all自动翻页（每次 200 行）但仍受--limit限制，因此单独使用--all仍会在 50 条时停止。如需完整扫描，请传入较大的显式上限：--all --limit 1000。--page-size N控制每次请求的块大小（最大 200）；--cursor <id>从上一页的next_cursor恢复。 - 时间过滤器：
--since接受相对时间窗口：15m、1h、6h、24h、7d或all（控制台的预设值）。对于更长或自定义的范围（例如最近 30 天），请使用--from/--to：必须包含T和时区的 ISO-8601 UTC 时间戳（例如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代替。- 多值过滤器 使用逗号分隔 → 以集合方式匹配（同一过滤器内为并集，跨过滤器为交集）：
--event-type tool_use,tool_result。Click 选项不支持可变参数，因此--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）可重复使用，多个条件取交集；任一边界均可省略（..0.5 表示 ≤ 0.5，0.9.. 表示 ≥ 0.9）。每次请求最多支持 20 个评分过滤器。evals --scores-full 是仅适用于人类表格的显示标志；它会显示所有评分对，而不是前几个加上 +N 计数。在 --json 模式下无效，--json 始终返回完整的评分对象。如需端到端读取一个会话，可将事件流与其评估结果结合使用：
管理（需要权限）：keys · users · settings · alerts · incidents
keys：API 密钥。密文在本地生成后发送到服务器（服务器仅存储其哈希值），并在创建/重新生成时仅显示一次；请立即保存。使用 --json 时，密文仅出现在 key 字段中。通过名称引用。
(permission-set ∪ --add) − --remove。令牌格式为 slug:action（例如 events:read），或 slug:action.action 在单个资源上展开多个权限（events:read.add → events:read、events:add）。预设值：read-only、standard、admin。人类专用权限（keys:update）不能授予给密钥。
users：组织成员，通过邮箱引用（也接受 UUID id）。
settings：固定注册表（您只能读取和修改现有键；不能创建新键）。
alerts：告警定义，通过名称引用。create 接受位置参数 NAME，以及标志或通过 --file 提供的完整 JSON 请求体。
incidents：告警事件，通过 id 引用（支持短 id）。show 输出完整的活动日志；在操作前请先阅读。
分析与助手：query · agent
query：针对分析存储的已保存 SQL，以及临时查询执行器。已保存查询通过名称引用；SQL 在服务器端验证（仅支持 SELECT/WITH，有语句超时和行数上限）。
agent：与内置 AI 助手对话（与控制台中相同的只读分析师）。对话通过短 chat-id 引用（支持前缀解析）。
退出码
这些退出码使 CLI 适合脚本化使用：编码智能体可以根据
4 提示您重新认证，或根据 5 提示缺少的权限。请参阅 CLI 智能体使用食谱，了解退出码处理模式和 JSON 输出结构。
下一步
- CLI 智能体使用食谱：可直接复用的查询模式、
jq单行命令、--fields投影、退出码处理以及 JSON 输出结构，专为驱动 CLI 的编码智能体编写。 - CLI 智能体技能：将此 CLI 打包为可安装的 Claude Code / Codex 技能，让编码智能体通过自然语言请求驱动 Failproof AI Observability。
- API 密钥：
keys create --add …背后的权限模型。 - AI 助手：启用
agent ask所使用的助手。