Failproof Cloud CLI

使用 fp 查看 Cloud 遥测数据、管理云端托管的执行策略（策略、机群部署、护栏决策），以及管理审计、发现项、问题、告警、密钥、用户、查询和设置。使用 failproofai 处理本地钩子、策略、数据捕获和机器注册。以独立工具的方式安装正式发布版 Cloud CLI：

uv tool install fp-cloud-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 --limit 10000
fp --json events --full --session-id <session-id> --all --limit 10000

--all 分页获取的记录数最多到 --limit，而 --limit 默认为 50——因此单独使用 --all 时会在 50 条时停止。若提前停止，响应中会携带 next_cursor 以便继续获取；"next_cursor": null 表示数据流已真正耗尽。

会话

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`	启用或禁用智能体分析。默认：启用。
`--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。

云端助手

命令	用途	选项
`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`

策略

云端托管的策略版本。仅限会话 — 此处所有命令在 API 密钥下均会在发出任何请求之前退出并返回 2，因为这些是仅限根用户的写入路由，在 /v1 中刻意不提供。

命令	用途	选项
`fp policies list`	列出策略版本。	`--json`
`fp policies show POLICY_ID`	显示一个策略及其源代码。	—
`fp policies publish NAME PATH`	从本地 `.mjs` 文件创建一个版本。	`--description`；`--no-verify`
`fp policies enable POLICY_ID`	将其重新添加到所有已移除它的部署中，并在每个部署上生成新的代次。	`--yes`, `-y`
`fp policies disable POLICY_ID`	从所有携带它的部署中移除，并在每个部署上生成新的代次。	`--yes`, `-y`
`fp policies delete POLICY_ID`	删除一个策略版本。	`--yes`, `-y`
`fp policies test PATH`	在本地针对合成上下文运行策略。对每个策略的 `match` 过滤器逐一应用，不覆盖给定事件/工具的策略会被报告为 `skipped` 而非运行。	`--event`；`--tool`；`--command`；`--file`；`--expect`
`fp policies compose PROMPT`	使用助手起草策略。需要 `policies:write` 权限。	—

机群

控制哪些机器运行哪些策略。仅限会话，原因同上。

命令	用途	选项
`fp fleet list`	列出已注册的机器及其部署代次。	—
`fp fleet show MACHINE_ID`	显示机器当前运行的策略集。	—
`fp fleet deploy MACHINE_ID`	替换机器的整个策略集。打印变更计划，在无 `--json` 的交互式终端中会进行确认提示。	`--add`；`--remove`；`--set`；`--create`；`--yes`, `-y`
`fp fleet diff MACHINE_ID`	将机器与另一个部署进行比较。	—
`fp fleet history MACHINE_ID`	查看机器的历史部署记录。	—
`fp fleet rollback MACHINE_ID GENERATION`	以新代次的形式恢复历史代次的策略集。	`--yes`, `-y`
`fp fleet rename MACHINE_ID`	为机器设置可读名称。	必需：`--name`

护栏

记录执行的实际情况。仅限会话，原因同上。

命令	用途	选项
`fp guardrails summary`	显示覆盖范围、拦截/评估总计、拒绝趋势图以及每条策略的汇总表。	`--since`（`1h`、`6h`、`24h`、`7d`）；`--machine`
`fp guardrails timeline`	显示时间窗口内各决策桶的汇总，跨所有策略来源求和。	`--since`（`1h`、`6h`、`24h`、`7d`）；`--machine`

全局标志

标志	说明
`--json`	输出机器可读的 JSON。
`--base-url <url>`	使用自托管或开发环境的 Dashboard。
`--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 面向自动化场景设计。登录、组织切换和助手命令需要用户会话。

环境变量

变量	对应选项或用途
`FP_DASHBOARD_URL`	`--base-url`
`FP_ORG`	`--org`
`FP_TOKEN`	`--token`
`FP_API_KEY`	`--api-key`
`FP_JSON`	`--json`
`FP_INSECURE`	`--insecure`
`FP_HOME`	重新指定 CLI 配置目录（默认为 `~/.failproofai/fpcli`）。
`FP_ANALYTICS_DISABLED` 或 `DO_NOT_TRACK`	禁用匿名 CLI 分析数据收集。
`NO_COLOR`	禁用彩色输出。

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

这些变量的 AGENTEYE_* 命名形式不会被 fp 读取，从来如此 — CLI 声明的是 FP_*（fp_cli/app.py），未知变量不会报错。设置 AGENTEYE_DASHBOARD_URL 不会改变 CLI 的目标地址；该变量会被忽略，命令会静默地继续使用已保存的 Dashboard 地址运行。AGENTEYE_HOME 和 AGENTEYE_ENVIRONMENT 仍然存在，但它们属于采集器和遥测 SDK，而非本 CLI。

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

Connect your agents

Reference

登录

语法

CLI 命令

身份验证

事件

会话

评估

错误

用量与筛选器值

组织

API 密钥

查询

用户

设置

告警

审计

审计创建选项

问题

云端助手

策略

机群

护栏

全局标志

环境变量

​登录

​语法

​CLI 命令

​身份验证

​事件

​会话

​评估

​错误

​用量与筛选器值

​组织

​API 密钥

​查询

​用户

​设置

​告警

​审计

​审计创建选项

​问题

​云端助手

​策略

​机群

​护栏

​全局标志

​环境变量

登录

语法

CLI 命令

身份验证

事件

会话

评估

错误

用量与筛选器值

组织

API 密钥

查询

用户

设置

告警

审计

审计创建选项

问题

云端助手

策略

机群

护栏

全局标志

环境变量