Failproof Cloud CLI

使用 fp 查看 Cloud 遥测数据，以及管理审计、发现项、问题、告警、密钥、用户、查询和设置。使用 failproofai 处理本地钩子、策略、采集和机器注册。以独立工具的形式安装已发布的 Cloud CLI：

uv tool install fp-cli
fp version

语法

fp [GLOBAL_OPTIONS] COMMAND [SUBCOMMAND] [ARGUMENTS] [OPTIONS]

全局选项必须放在命令之前：

fp --json sessions --since 24h

运行 fp COMMAND --help 或 fp COMMAND SUBCOMMAND --help 可在终端查看帮助信息。

CLI 命令

认证

命令	用途	选项
`fp login`	通过邮件发送的一次性验证码登录，并选择组织。	`--email`, `-e`; `--org`; `--force`
`fp logout`	吊销并删除已保存的用户会话。	—
`fp whoami`	显示当前身份、认证模式、组织和权限。	—
`fp version`	显示已安装的 CLI 版本。	—
`fp help`	显示顶层命令帮助。	—

fp login --email you@example.com --org reliability-team
fp whoami

事件

fp events [OPTIONS]

列出单个 Agent 事件。默认的轻量信息流不包含原始载荷；仅在有限范围的调查时使用 --full。

选项	描述
`--limit`, `-n <n>`	最大总行数。默认值：`50`。
`--since <window>`	`all`、`15m`、`1h`、`6h`、`24h` 或 `7d`。
`--from <timestamp>` / `--to <timestamp>`	ISO 8601 UTC 时间范围；覆盖 `--since`。
`--env <value>`	环境过滤器；可重复或以逗号分隔多个值。
`--event-type <value>`	事件类型过滤器；可重复或以逗号分隔多个值。
`--agent-id <value>`	Agent 过滤器；可重复或以逗号分隔多个值。
`--session-id <value>`	会话过滤器；可重复或以逗号分隔多个值。
`--search <text>`	载荷文本搜索；可重复，任意词条匹配即可。
`--order asc\|desc`	时间排序。默认：最新优先。
`--all`	自动分页直至达到 `--limit`。
`--cursor <token>`	从不透明游标处恢复。
`--page-size <n>`	与 `--all` 配合使用时每次请求的行数；最大值 `200`。
`--full`	通过更重量级的事件端点包含原始载荷。
`--fields <csv>`	仅返回选定字段；请求 `payload` 将启用完整模式。

fp events --session-id <session-id> --order asc --all
fp --json events --full --session-id <session-id> --all

会话

fp sessions [OPTIONS]

选项	描述
`--limit`, `-n <n>`	最大总行数。默认值：`50`。
`--since <window>`	`all`、`15m`、`1h`、`6h`、`24h` 或 `7d`。
`--from <timestamp>` / `--to <timestamp>`	ISO 8601 UTC 时间范围；覆盖 `--since`。
`--env <value>`	环境过滤器；可重复或以逗号分隔多个值。
`--status <value>`	`done`、`error` 或 `timeout`；可重复或以逗号分隔多个值。
`--agent-id <value>`	匹配包含任意所选 Agent 的会话。
`--session-id <value>`	会话过滤器；可重复或以逗号分隔多个值。
`--all`	自动分页直至达到 `--limit`。
`--cursor <token>`	从不透明游标处恢复。
`--page-size <n>`	与 `--all` 配合使用时每次请求的行数；最大值 `200`。
`--fields <csv>`	仅返回选定字段。
`--full-ids`	在终端输出中不缩短会话 ID。
`--agents`	展开多 Agent 会话的 Agent 列表。

评估

fp evals [OPTIONS]

选项	描述
`--aggregate`	显示总计和每个评分的统计信息，而非单条评估记录。
`--limit`, `-n <n>`	最大列表行数。默认值：`50`。
`--since`, `--from`, `--to`	选择时间范围。
`--env`, `--status`, `--agent-id`, `--session-id`	每个过滤器限定为一个精确值。
`--score KEY:MIN..MAX`	评分范围；可重复，所有范围均须匹配。
`--all`, `--cursor`, `--page-size`	控制列表分页。
`--fields <csv>`	仅返回选定字段。
`--full-ids`	显示完整会话 ID。
`--scores-full`	在终端输出中显示所有评分。

错误

fp errors [OPTIONS]

选项	描述
`--aggregate`	汇总匹配的错误，而非逐行列出。
`--limit`, `-n <n>`	最大列表行数。默认值：`50`。
`--since`, `--from`, `--to`	选择时间范围。
`--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id`	缩小错误范围。
`--search <text>`	搜索载荷文本；可重复。
`--order asc\|desc`	时间排序。
`--all`, `--cursor`, `--page-size`	控制列表分页。
`--fields <csv>`	仅返回选定字段。
`--full-ids`	显示完整会话 ID。

用量与过滤值

命令	用途
`fp usage`	显示当前计量窗口的用量。
`fp list envs`	列出已观察到的环境。
`fp list agents`	列出已观察到的 Agent ID。
`fp list event_types`	列出事件类型。
`fp list score_filters`	列出评估评分键。
`fp list models`	列出模型名称。
`fp list hooks`	列出钩子名称。
`fp list tools`	列出工具名称。
`fp list error_types`	列出错误类型。

组织

命令	用途
`fp orgs list`	列出可访问的组织。
`fp orgs switch [SLUG]`	保存活动组织；省略时会进行提示。
`fp orgs current`	显示当前活动组织。
`fp orgs perms`	显示您在活动组织中的权限。

API 密钥

命令	用途	选项
`fp keys list`	列出组织密钥。	`--show-id`; `--fields <csv>`
`fp keys show NAME`	显示一个密钥及其授权。	—
`fp keys create NAME`	创建密钥并一次性显示其密钥值。	`--permission-set`; `--add`; `--remove`
`fp keys update NAME`	替换权限集或调整授权。	`--permission-set`; `--add`; `--remove`; `--yes`, `-y`
`fp keys regenerate NAME`	轮换密钥并一次性显示新密钥值。	`--yes`, `-y`
`fp keys disable NAME`	永久吊销一个密钥。	`--yes`, `-y`

权限令牌使用 resource:action 格式，例如 events:add。可重复使用 --add，以逗号分隔多个令牌，或使用点式操作如 events:read.add。

查询

命令	用途	选项
`fp query list`	列出已保存的查询。	`--show-id`; `--fields <csv>`
`fp query show NAME`	显示一个查询。	—
`fp query create NAME`	保存一个查询。	`--sql <text\|@file>`; `--description`
`fp query update NAME`	更新或重命名一个查询。	`--name`; `--sql`; `--description`; `--yes`, `-y`
`fp query delete NAME`	删除一个已保存的查询。	`--yes`, `-y`
`fp query run [NAME]`	运行已保存的查询或临时 SQL。	`--sql`; `--limit`; `--all`; `--arg`, `--param`
`fp query schema [TABLE]`	列出可查询的表或检查某张表。	—

用户

命令	用途	选项
`fp users list`	列出组织成员。	`--active-only`; `--show-id`
`fp users show EMAIL`	显示一个成员及其授权。	—
`fp users create EMAIL`	添加一个成员。	`--permission-set`; `--add`; `--remove`
`fp users update EMAIL`	修改成员的授权。	`--permission-set`; `--add`; `--remove`; `--yes`, `-y`
`fp users disable EMAIL`	禁用登录。	`--yes`, `-y`
`fp users enable EMAIL`	重新启用登录。	`--yes`, `-y`

设置

命令	用途	选项
`fp settings list`	列出组织设置及当前值。	—
`fp settings schema`	显示可接受的值和描述。	—
`fp settings set KEY`	修改某个现有设置。	三选一：`--value`、`--json-value`、`--file`；可选 `--yes`, `-y`

告警

命令	用途	选项
`fp alerts list`	列出告警规则。	`--show-id`
`fp alerts show NAME`	显示一条告警。	—
`fp alerts create NAME`	创建一条告警。	`--file`; `--description`; `--severity`; `--trigger-kind`; `--trigger-spec`; `--channels`; `--eval-interval-secs`; `--min-breaches`; `--eval-window`
`fp alerts update NAME`	更新或重命名一条告警。	创建选项加上 `--name`; `--yes`, `-y`
`fp alerts delete NAME`	删除一条告警。	`--yes`, `-y`
`fp alerts test NAME`	发送测试通知。	`--channels`; `--yes`, `-y`

告警严重级别为 info、warning 和 critical。触发类型为 metric_threshold、custom_sql、evaluation_score、eval_compound 和 per_event。评估间隔必须在 30 到 86,400 秒之间。

审计

命令	用途	选项
`fp audits list`	列出审计。	`--enabled-only`; `--show-id`
`fp audits show NAME`	显示一个审计定义及其状态。	—
`fp audits create NAME`	创建一个审计，并立即将其首次运行加入队列。	参见创建选项。
`fp audits edit NAME`	替换审计设置，同时保留未指定的值。	创建定义选项；`--name`; `--yes`, `-y`
`fp audits delete NAME`	删除一个审计及其发现项和运行历史。	`--yes`, `-y`
`fp audits run NAME`	手动将一次运行加入队列。	—
`fp audits runs NAME`	列出运行历史。	`--limit`, `-n`; `--show-id`
`fp audits context-show NAME`	显示简报和参考 URL 的抓取状态。	—
`fp audits context-set NAME`	修改简报或参考 URL。	`--text`; `--text-file`; `--url`; `--clear-urls`
`fp audits context-refresh NAME`	重新抓取参考 URL。	—
`fp audits findings`	列出发现项。	`--audit`; `--run-id`; `--status`; `--limit`, `-n`; `--offset`; `--show-id`
`fp audits finding FINDING_ID`	显示一条发现项及其证据。	—
`fp audits ack FINDING_ID`	确认一条发现项。	`--reason`
`fp audits mute FINDING_ID`	抑制一个反复出现的模式。	`--reason`; `--yes`, `-y`
`fp audits dismiss FINDING_ID`	将一个模式标记为不可操作并抑制它。	`--reason`; `--yes`, `-y`
`fp audits resolve FINDING_ID`	将发现项标记为已修复，且不进行后续抑制。	`--yes`, `-y`
`fp audits reopen FINDING_ID`	将发现项返回实时队列并清除抑制。	—
`fp audits assign FINDING_ID`	设置发现项的负责人。	必填 `--to <email>`

审计创建选项

fp audits create checkout-reliability \
  --description "Find checkout failures that agents do not recover from" \
  --scope '{"environments":["production"],"agent_ids":["checkout-agent"]}' \
  --schedule-interval-secs 86400 \
  --window-mode since_last \
  --sensitivity medium \
  --text-file ./checkout-audit-brief.txt \
  --url https://runbooks.example.com/checkout

选项	描述
`--file <path>`	基于 JSON 构建定义，或使用 `-` 从 stdin 读取。显式标志会覆盖文件中的值。
`--description <text>`	说明故障问题或目的。
`--enabled` / `--disabled`	启动时开启或关闭调度。默认：启用。
`--schedule-interval-secs <n>`	`3600`–`604800`。默认值：`86400`。
`--schedule-anchor <timestamp>`	ISO 8601 格式的固定 UTC 相位。默认：下一个 09:00 UTC。
`--window-mode since_last\|fixed`	从上一个完全分析的窗口之后继续，或反复检查滚动窗口。默认：`since_last`。
`--lookback-window-secs <n>`	`3600`–`7776000`。默认值：`604800`。
`--scope '<json>'`	按 `environments`、`agent_ids` 或其他支持的范围字段进行过滤。
`--ignore-error-type <type>`	排除错误类型；可重复或以逗号分隔。
`--llm` / `--no-llm`	启用或禁用 Agent 式分析。默认：启用。
`--top-k <n>`	保留 `1`–`500` 条发现项。默认值：`50`。
`--sensitivity low\|medium\|high`	设置报告敏感度。默认：`medium`。
`--channels '<json>'`	通知渠道数组。
`--text <brief>`	内联简报，最多 8,192 个字符。
`--text-file <path>`	从文件读取简报；与 `--text` 互斥。
`--url <https-url>`	添加公开的 HTTPS 参考链接；最多重复五次。

在首次运行需要上下文时，请在创建阶段一并包含。创建操作会在队列中的运行开始前，将定义和上下文一起提交。

fp audits run 是异步操作。请轮询 fp audits runs NAME，直到最新一次运行成功或失败后，再读取其发现项。

问题

命令	用途	选项
`fp issues list`	列出问题。	`--state`; `--alert-id`; `--limit`, `-n`; `--show-id`
`fp issues count`	统计开放或指定状态的问题数量。	`--state`
`fp issues show INCIDENT_ID`	显示问题详情、评论、订阅者和活动记录。	—
`fp issues open`	创建手动问题或与告警关联的问题。	必填 `--summary`；可选 `--title`、`--alert-id`、`--severity`
`fp issues ack INCIDENT_ID`	确认一个问题。	—
`fp issues assign INCIDENT_ID`	替换指派人；省略选项则清除指派人。	可重复 `--assignee`
`fp issues resolve INCIDENT_ID`	解决一个问题。	`--yes`, `-y`
`fp issues comment-list INCIDENT_ID`	列出评论。	—
`fp issues comment-add INCIDENT_ID`	添加评论。	二选一：`--body`、`--file`
`fp issues comment-delete INCIDENT_ID COMMENT_ID`	删除评论。	`--yes`, `-y`
`fp issues subscribers INCIDENT_ID`	列出订阅者。	—
`fp issues subscribe INCIDENT_ID`	订阅自己或其他操作员。	`--email`
`fp issues unsubscribe INCIDENT_ID`	取消订阅。	`--email`

有效的问题状态为 firing、acknowledged 和 resolved。独立问题的严重级别为 info、warning 和 critical。

Cloud 助手

命令	用途	选项
`fp agent health`	检查助手可用性和配置。	—
`fp agent models`	列出可用的助手模型。	—
`fp agent chats`	列出已保存的对话。	—
`fp agent ask [MESSAGE]`	开始或继续一次对话；省略消息时从 stdin 读取。	`--chat`; `--model`; `--page-context`
`fp agent show CHAT_ID`	显示一次已保存的对话。	—
`fp agent rename CHAT_ID`	重命名一次对话。	必填 `--title`
`fp agent delete CHAT_ID`	删除一次对话。	`--yes`, `-y`

全局标志

标志	描述
`--json`	输出机器可读的 JSON。
`--base-url <url>`	使用自托管或开发环境的控制台。
`--org <slug>`	为本次调用选择一个组织。
`--token <token>`	覆盖已保存的用户会话令牌。
`--api-key <key>`	使用 API 密钥进行自动化认证；不会被保存。
`--timeout <seconds>`	HTTP 超时时间；必须为正数。默认值：`30`。
`--quiet`, `-q`	抑制 stderr 上的状态输出。
`--no-color`	禁用彩色输出。
`--insecure` / `--secure`	禁用或恢复 TLS 证书验证。
`--version`	打印版本号并退出。
`--help`, `-h`	显示帮助。

--api-key 适用于自动化场景。登录、切换组织和助手命令需要用户会话。

环境变量

变量	等效选项或用途
`AGENTEYE_DASHBOARD_URL`	`--base-url`
`AGENTEYE_ORG`	`--org`
`AGENTEYE_CLI_TOKEN`	`--token`
`AGENTEYE_CLI_API_KEY`	`--api-key`
`AGENTEYE_CLI_JSON`	`--json`
`AGENTEYE_INSECURE`	`--insecure`
`AGENTEYE_HOME`	重新定位当前 CLI 配置目录。
`AGENTEYE_ANALYTICS_DISABLED` 或 `DO_NOT_TRACK`	禁用匿名 CLI 分析。
`NO_COLOR`	禁用彩色输出。

显式标志会覆盖环境变量，环境变量会覆盖已保存的配置。在 API 密钥模式下，请使用 --org 或 AGENTEYE_ORG 显式指定租户。

执行删除、吊销、抑制、解决或替换配置的命令默认会有确认提示。请在验证活动组织和目标后再使用 --yes。

Connect your agents

Reference

HTTP API

登录

语法

CLI 命令

认证

事件

会话

评估

错误

用量与过滤值

组织

API 密钥

查询

用户

设置

告警

审计

审计创建选项

问题

Cloud 助手

全局标志

环境变量

​登录

​语法

​CLI 命令

​认证

​事件

​会话

​评估

​错误

​用量与过滤值

​组织

​API 密钥

​查询

​用户

​设置

​告警

​审计

​审计创建选项

​问题

​Cloud 助手

​全局标志

​环境变量

登录

语法

CLI 命令

认证

事件

会话

评估

错误

用量与过滤值

组织

API 密钥

查询

用户

设置

告警

审计

审计创建选项

问题

Cloud 助手

全局标志

环境变量