Failproof Cloud CLI

使用 fp 查看云端遥测数据、管理云端托管的执行策略（策略、机器群部署、护栏决策），以及管理审计、发现项、问题、告警、密钥、用户、查询和设置。本地钩子、策略、数据采集和机器注册请使用 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`	启用或禁用 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。

云端助手

命令	用途	选项
`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 中排除的仅限 root 的写入路由。

命令	用途	选项
`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-path`; `--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`	还原到之前的部署。	`--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 密钥

查询

用户

设置

告警

审计

审计创建选项

问题

云端助手

策略

机器群

护栏

全局标志

环境变量