概述
Flashduty CLI（flashduty）是一款命令行工具，可在终端中完成故障生命周期管理、值班查询、状态页发布、通知模板调试等操作，适用于运维脚本、本地排障以及与 AI 编程代理协同工作。
工具开源在 flashcatcloud/flashduty-cli，支持 macOS、Linux 和 Windows。
安装
- macOS / Linux
- Windows (PowerShell)
- 手动下载
/usr/local/bin，可通过环境变量 FLASHDUTY_INSTALL_DIR 自定义。安装选项
认证
登录
凭证解析顺序
CLI 按以下优先级查找 APP Key（高优先级在前）：--app-key命令行参数（脚本场景使用）FLASHDUTY_APP_KEY环境变量- 配置文件
~/.flashduty/config.yaml（由flashduty login写入）
配置文件
存储在~/.flashduty/config.yaml，权限为 0600：
配置命令
全局参数
所有子命令均支持以下参数：命令清单
incident — 故障生命周期
incident list 常用过滤参数：
时间格式示例：
5m、1h、24h、168h、2026-04-01、2026-04-01 10:00:00、1712000000。
工作项与跟进项（work-item-*）
incident work-item-* 管理挂靠在故障或复盘上的工作项，--item-type 区分两种类型：action（故障行动项，挂靠进行中的故障）与 follow_up（复盘跟进项，必须绑定复盘 ID）。
work-item-create 关键参数：--item-type（必填，action 或 follow_up）、--title（必填，最多 512 字符）、--idempotency-key（必填幂等键，最多 128 字符）、--post-mortem-id（follow_up 必填，action 禁止）、--assignee-ids（初始负责人）。更新类操作（update/complete/convert/delete/assignees-reset）均需传 --version（乐观锁，必须与当前存储版本一致）。
复盘报告（post-mortem-*）
复盘命令位于incident 命令组下（没有独立的 post-mortem 顶层命令组）：
post-mortem-template-list、post-mortem-template-info <template-id>、post-mortem-template-upsert（缺省 --template-id 时为创建，创建时 --team-id 必填）、post-mortem-template-delete <template-id>（不可逆）。
评论类型（comment-type-*）
change — 变更记录
--channel、--since、--until、--type、--limit、--page。
member — 成员查询
member list 支持 --query（姓名/邮箱关键字搜索）、--role-id、--page、--limit、--orderby、--asc。
member info-reset 通过 --member-id、--member-name、--email、--phone 或 --ref-id 之一定位成员，要修改的字段经 --data '{"updates":{...}}' 传入（必填）；--from api 在账户关闭成员邀请时，可将更新后的邮箱/手机号直接标记为已验证。
member invite 的成员列表经 --data '{"members":[...]}' 传入；当账户关闭成员邀请且指定 --from api 时，成员会直接以启用状态创建（邮箱/手机号标记为已验证），不再发送邀请邮件。
team — 团队管理
team list 支持 --query（团队名称子串匹配）、--page、--limit、--orderby（created_at/updated_at/team_name）、--asc、--person-id（按成员 ID 过滤所属团队）。
team info 支持通过 --ref-id、--team-name 或 --team-id 指定团队（三选一）；同时提供多个字段时，按 --ref-id > --team-name > --team-id 的优先级取用。
team upsert 创建或更新团队：
--team-name（必填，1–39 字符）--team-id（填写则为更新，否则创建）--description（最多 500 字符）--person-ids（成员 ID 列表；会完整替换现有成员名单，更新前请先用team info确认当前成员）--emails（按邮箱匹配并加入已存在的成员；不匹配任何现有成员的邮箱会被静默忽略，不会发送邀请）--phones（按手机号匹配并加入已存在的成员；不匹配的号码会被静默忽略，非 E.164 格式的号码按--country-code解析）--country-code（对非 E.164 格式的--phones号码应用默认国家码）--ref-id（外部系统引用 ID）
team upsert 的 --emails / --phones 只匹配并附加现有成员，不会发送任何邀请。需要邀请新成员加入组织时，请使用 flashduty member invite。team delete 支持通过 --team-id、--team-name 或 --ref-id 指定团队，操作不可逆。
channel — 协作空间查询
--name。
channel escalate-rule-list — 分派策略查询
分派策略现已并入channel 命令组，通过位置参数传入协作空间 ID：
escalate-rule-create、escalate-rule-update、escalate-rule-delete（均在 channel 命令组下，--channel-id 为必填）。
channel 静默/抑制/丢弃规则 — 降噪规则管理
协作空间级降噪规则通过channel 命令组管理，规则语义与配置项参见降噪管理。三组命令（silence-rule-* 静默、inhibit-rule-* 抑制、unsubscribe-rule-* 丢弃）形态相同，各含 list/create/update/enable/disable/delete 六个动作：
inhibit-rule-* 与 unsubscribe-rule-* 用法相同；inhibit-rule-create 需 --equals（源与目标告警的配对标签键）。silence / inhibit 均可加 --is-directly-discard 让被抑制的告警直接丢弃而非合并。注意 *-rule-create 与 *-rule-list 的 channel-id 是位置参数，*-rule-update/delete/enable/disable 使用 --channel-id 标志；--rule-id 为 MongoDB ObjectID 字符串。
field — 自定义字段查询
--name。
status-page — 状态页管理
事件草稿（draft-create）
draft-create 保存一份状态页事件草稿（故障事件或维护窗口），供人工在控制台审阅后发布——草稿本身不会对外发布：
--source：起草来源的不透明标记（如ai_sre:sess_xxx），最多 64 字符。--data中的draft对象（必填，序列化后最多 64 KB，原样存储）。必填字段：page_id、type（incident或maintenance）、name、message；可选change_id（大于 0 时表示向已有事件追加更新）、status、affected_components、start_time/end_time（Unix 秒，仅新建维护窗口使用）。- 响应返回
draft_id（形如draft_[A-Za-z0-9]{22}）与created_at，控制台审阅链接携带draft_id。
从 Atlassian Statuspage 迁移
迁移任务为异步执行，需通过migration-status 轮询进度：
draft-create、change-delete、change-info、change-list、change-timeline-delete、change-timeline-update、change-update、component-upsert、component-delete、section-upsert、section-delete、info、subscriber-list、subscriber-import、subscriber-export、template-list、template-upsert、template-delete。
rum — RUM 应用与会话回放
用于管理 RUM 应用和导出会话回放数据。应用命令覆盖详情、批量读取、列表、Webhook 测试，以及创建、更新、删除。application-list 常用参数：
application-create / application-update 的核心字段：
application-webhook-test 会返回 ok、status_code 和 message，可用于验证 RUM 告警 Webhook 是否真正收到了平台发出的测试事件。会话回放
session-replay-metadata 的 --ts 可填写会话开始时间的 Unix 毫秒时间戳，用于区分不同时间窗口中复用的会话 ID。
session-replay-segments 常用参数：
错误摄入规则（error-ingestion-rules-*）
错误摄入规则按过滤条件筛除或改写应用上报的错误事件：--description 最长 512 字符；create/list/history-list/history-revert 以位置参数接收 application-id，update/enable/disable/delete 通过 --application-id 与 --rule-id 标志指定目标。
预设严重级别规则（issue-preset-severity-rules-*）
预设严重级别规则为匹配条件的错误预设等级，用于 issue 分级：资源信息（resource-info）
oncall — On-call 许可证
fixed 表示固定分配，temporary 表示当前临时许可证窗口内生效。
template — 通知模板
dingtalk、dingtalk_app、feishu、feishu_app、wecom、wecom_app、slack、slack_app、telegram、teams_app、email、sms、zoom。
session — AI SRE 会话
用于巡查 AI SRE（以及其他 Flashduty 智能体）的会话：session list 列出调用者可见的会话，session export 将单个会话的完整事件流式导出，便于离线分析。
session list 常用参数：
服务端
/safari/session/list 单页上限为 100 条，超出 --limit 时 CLI 会自动向服务端翻页拉取，无需手动分页。API 本身没有时间窗口过滤，--since 是在拉取后于客户端按会话的 updated_at 进行过滤的。session export 将会话事件以换行分隔 JSON（NDJSON）流式写入标准输出：第一行始终是 session_meta 信封，其后每行是一个事件（user_message、llm_call、tool_call、subagent_dispatch、final_answer、agent_text、error）。导出内容可能很大，建议重定向到文件而非直接打印到终端：
monit-query — 监控数据源统一工具调用
monit-query 对已配置的数据源执行单个命名工具，是查询与诊断的统一入口：查询工具（<type>.query，覆盖 prometheus、mysql、postgres、oracle、clickhouse、elasticsearch、loki、victorialogs、sls、tencent_cls）与诊断工具（如 mysql.overview、redis_node.slowlog）都走它，无需经过告警规则层。旧 monit-query data 子命令已退役。数据源 ID 从 monit datasource-list 的 id 字段获取：
查询工具返回完整的
explore_result.v1 结构化结果：format 固定为 explore_result.v1，result.kind 为 samples（带完整标签集的即时样本）、frames（类型化表格/时序帧）或 logs（原始日志，含 applied_limit 与 has_more）三者之一。诊断工具的返回结构见下文 monit datasource-tools-invoke。
monit datasource-tools-invoke — 数据源诊断工具
monit datasource-tools-invoke 对已配置的数据源执行一次确定性的只读工具调用，是结构化数据源诊断的现行路径（取代 monit-query diagnose），与上文 monit-query 命令等价，monit-query 为推荐路径。数据源 ID 从 monit datasource-list 的 id 字段获取：
语义与限制：
- 无工具目录、无自动重试、无回退：一次调用只执行一个命名工具，参数需按各数据源工具约定填写，不要从命令行列表猜测。除诊断工具外，入口还支持
<type>.query查询工具（prometheus、mysql、postgres、oracle、clickhouse、elasticsearch、loki、victorialogs、sls、tencent_cls）。 - 要求所选集群内全部当前在线可路由的 Edge 会话支持 v0.71.0 基础调用协议（个别工具可能要求更新的实现）；普通数据源查询不受此版本限制。
- 请求体 ≤128 KiB；完整成功响应 ≤10 MiB；工具超时 ≤25 秒。
- 需要数据源
enabled=true；alerting_enabled=false不阻塞诊断。 - 返回值：
data（工具特定的 JSON 证据，原样保留、永不为 null，不含旧 diagnose 信封）、tool、datasource_id、可选summary，以及truncated对象（含reason，存在即表示结果被截断）。
edge_upgrade_required（Edge 版本过低）、mixed_edge_versions（集群内 Edge 版本混合）、no_active_edge（无可用在线 Edge）、tool_not_supported（工具不支持）、invalid_request（修正参数）、source_too_large / result_too_large（收窄请求范围）。出现 Edge 版本问题时不要轮换 Edge 或回退到旧版 diagnose。
monit — 监控数据源与规则表达式预览
如果你想在保存规则前直接验证某条数据源表达式，可以使用preview-sync 走一条同步预览请求，拿到原始结果。
数据源管理（datasource-*）
monit datasource-* 命令族管理监控数据源（由 OpenAPI 生成命令提供）：
datasource-create / datasource-update 核心字段：
enabled 与 alerting_enabled 相互独立：告警评估同时要求 enabled=true 与类型支持告警；alerting_enabled=false 不阻塞非告警查询与诊断工具，monit datasource-list 返回的 alerting_enabled 对仅诊断类型恒为 false。
诊断类型 payload 与密钥处理：
redis_node：database（Redis 库号，默认 0）、username/password、timeout_ms（默认 3000，范围 1000–10000）。redis_sentinel：username/password、timeout_ms（默认 3000）。mongodb_mongod/mongodb_mongos：auth_source（认证库，默认admin；用户名与密码须成对配置）、username/password、timeout_ms（默认 3000）、TLS 字段；不支持客户端证书。kafka：sasl_mechanism（none默认 /plain/scram-sha-256/scram-sha-512，后三者需用户名与密码）、username/password、timeout_ms（默认 5000）、TLS 字段（tls_min_version默认 1.2，最高 1.3）。- 密码与
kafka.tls_key支持${env:NAME}引用（在 Edge 上解析）；字面值不会出现在响应中，仅${env:...}引用会回显。更新时省略这些字段以保留已存密钥，显式传空字符串表示清除。
alert — 告警与告警事件查询
list 命令常用过滤参数：--severity（Critical,Warning,Info）、--channel（逗号分隔协作空间 ID）、--integration（逗号分隔的集成 ID）、--since/--until、--limit（最大 100）、--page。alert-event list 另有 --integration-type，按逗号分隔的插件键过滤（如 AliCloud,Prometheus）——注意它取插件键而非集成 ID，按集成 ID 过滤请使用 --integration。
automation — AI SRE 自动化规则
automation 命令组管理 AI SRE 的自动化规则——创建、查询、更新、删除、运行历史与触发，页面操作见自动化。
create 常用参数：
update 可改字段：--name、--prompt/--prompt-file、--schedule/--at/--weekday/--cron-expr、--enable/--disable、--enable-schedule/--disable-schedule、--enable-http-post-trigger/--disable-http-post-trigger、--rotate-http-post-token、--environment-kind/--environment-id。个人 / 团队作用域创建后不可变更，update 不提供改作用域的参数。
runs 支持 --status（queued/running/retrying/succeeded/partial/failed/skipped/abandoned）、--trigger-kind（schedule/debug/http_post）、--since/--until、--page、--limit。fire 用触发器的 Token 鉴权（--token，或环境变量 FLASHDUTY_AUTOMATION_TRIGGER_TOKEN），--text 传本次运行的上下文，--data 传完整 JSON 请求体（内联 JSON 或 - 读 stdin）。
insight — 洞察查询
insight 命令族按时间窗口查询聚合的故障指标（响应时间、通知数等）：
insight incidents 常用参数：
json/toon 模式默认按紧凑字段投影：incident_id、title、severity、channel_name、seconds_to_ack、seconds_to_close、notifications（默认投影时 stderr 会提示可用 --fields 更换），输出受 16 KiB 上限约束，超出时行会被丢弃或单行截短，提示只写 stderr（详见下文「输出格式」的「结构化输出的字段投影」）。
insight top-alerts：--label 必填（check 或 resource），--since/--until 同前，--limit 默认 10（Top-K），返回每个标签值的告警数与事件数。
insight incident-export：按当前筛选条件输出一行 CSV（重定向到文件；--start-time/--end-time 为 Unix 秒）。导出端点单次返回且服务端会静默截断行数，因此命令写完后会核对 CSV 数据行数与同筛选条件 incident-list 的总数：不足时 CSV 仍会写出（stderr 打印 rows=N），并以非零退出码提示实际写出 vs 总数——请收窄时间窗口后重试。
全量命令覆盖
除上述精选命令外，CLI 现已通过 spec 驱动的代码生成实现对 Flashduty OpenAPI 的全量覆盖。当前 OpenAPI 含 340 个 API 操作，CLI 为其中 337 个 生成对应命令，其余操作（如session-read-export）以手工实现命令提供（session export / safari session-export），并按资源组织为顶层命令组。除 On-call 域（incident、incident-trigger-subscription、change、channel、field、status-page、template 等）外，还覆盖了：
- AI SRE（
safari）：a2a-agents、artifacts、automations、knowledge、mcp-servers、sessions、skills 等 - 告警与降噪：alert、alert-event、enrichment（alert-rules、rule-sets）、route
- On-call 与日程：calendar、schedule
- 平台管理：account、member、person、team、role（roles-permissions）、audit（audit-logs）
- 监控与 RUM：monit、rum、sourcemap
- 集成与 Webhook：datasource（IM 集成）、webhook（integrations）
flashduty safari a2a-agent-get、flashduty safari session-list），其入参与返回字段直接映射到对应 API。鼓励用 flashduty <资源> --help 逐层探索：
--start-time / --end-time）与精选命令一样支持人性化的时间格式：相对时长（7d、24h，表示从当前往前推）、+7d（从当前往后推，即未来时间）、now、日期或日期时间（如 2026-05-01、2026-05-01 10:00:00）、Unix 秒级时间戳。此外，--since 和 --until 分别是 --start-time 和 --end-time 的别名，可互换使用；若两种写法同时传入且取值不同，CLI 会报冲突错误。
knowledge — AI SRE 知识库
safari knowledge-* 命令族管理 AI SRE 的知识包（Knowledge Pack）——账户或团队作用域下的版本化文件树（DUTY.md 加运行手册、FAQ、服务清单等），会话开始时会被加载进每个 AI SRE 沙箱。知识包的完整功能模型（DUTY.md 结构、@引用、账户/团队作用域、文件约束）参见 管理知识。
knowledge-file-put 的 --content-b64 必须是合法 UTF-8 文本的 Base64 编码，--content-type 省略时按文件扩展名推断。knowledge-file-delete 默认在文件仍被其他知识文件引用时阻止删除；加 --force 可强制执行，此时引用方会以警告形式返回。
artifacts — AI SRE 产物库
safari artifact-* 命令族管理 AI SRE 会话产出的产物（Artifact）——发布到产物库、共享与签名下载，产品功能见产物：
public_url是控制台/share/artifact/<artifact-id>页面，完全由 CDN 提供；仅在分享期间存在，任何拿到链接的人无需登录即可查看。- 公开快照按产物当前的
file_id物化：当share_enabled=true且响应中share_file_id与file_id不一致时，公开快照已过期——调用artifact-gallery-share-sync刷新后再对外引用。 artifact-sign的签名 token 绑定调用账户与成员，有效期 5 分钟（响应expires_in）；download_url/preview_url是相对路径（/safari/artifact/stream?...），使用时需拼接 API base（https://api.flashcat.cloud）。- 产物初始作用域继承来源会话（个人会话的产物归创建者个人，绑定团队的会话的产物归团队）；
can_edit决定调用者能否重命名/转移/删除/分享（创建者、所属团队成员或源会话管理者）。
工具命令
flashduty update 会下载并执行平台安装脚本，将当前二进制替换为最新版本。--check 仅打印可用版本号，不修改本地文件。在终端中执行其他命令后，若检测到有新版本可用，CLI 会在 stderr 自动输出更新提示横幅。输出格式
通过--output-format 选择输出形态（--json 是 --output-format json 的别名），便于在不同场景下消费：
- 表格（默认）
- JSON（--json / --output-format json）
- TOON（--output-format toon）
- 完整表格（--no-trunc）
人类可读，列对齐，长字段截断显示。
生成命令的输出上限
由 OpenAPI 代码生成提供覆盖的生成命令（如safari session-list、monit datasource-list、safari a2a-agent-list 等），其 json / toon 输出对列表形态的响应同样按 16 KiB 上限处理（与精选命令的两级行为一致，提示只写 stderr、不改写 stdout）：
- 整页超限：只输出能完整放下的前几行，每个值保持原样，stderr 提示实际输出了 N/M 行、其余行未输出。
- 单行本身超限：该行的字符串值以
...截短，stderr 点名被截字段；标识符字段（以_id/_key结尾）不会被截短。 - 行无法缩减到上限以内：命令报错并点名字节数最大的字段（最多 3 个），请调低
--limit或减少输出字段后重试。
safari session-get 的详情）不做截断、原样输出——截短后的值无法与真实短值区分，因此这类响应不受上限约束。生成命令大多没有 --fields，需要完整 JSON 时请通过 --limit 调小每页数量、配合 --page 分页逐页拉取（如 flashduty safari session-list --limit 20 --page 2），或按需收窄筛选条件。
结构化输出的字段投影
以下命令在json 或 toon 输出时支持 --fields。用逗号分隔顶层响应字段；未知字段会直接报错，表格输出会忽略此参数。
例如，只导出故障编号、标题和处理进度：
incident list、incident similar、alert-event list、channel escalate-rule-list、insight incidents）超过 16 KiB 上限时，CLI 按三级行为处理，所有提示只写 stderr、不改写 stdout：
- 整页超限：只输出能完整放下的前 N 行，每个值保持原样、不再截短，stderr 提示实际输出了 N/M 行、其余行未输出；收窄
--fields或调低--limit可让每页容纳更多行。 - 单行本身超预算：截短该行的字符串值并以
...标记，stderr 点名被截短的字段；在被截短过的字段上匹配或过滤会漏数据，需要原始值时请收窄--fields或--limit。标识符字段（以_id或_key结尾）在任何一级都不会被截短。 - 行无法缩减到上限以内：命令报错并点名字节数最大的字段（最多 3 个，含各自字节数），请减少
--fields字段或调低--limit后重试。
incident detail 的投影超限行为不同：详情是单个对象，截断后的值与本身就很短的真实值无法区分，静默截短会返回错误数据，因此投影超过 8 KiB 时命令直接失败，错误信息会点名最大的字段（最多 3 个，含各自字节数）。此时请减少 --fields 中的字段，或直接省略 --fields 获取不受投影上限约束的完整详情。
未指定 --fields 而使用默认紧凑投影时，CLI 会在 stderr 打印一行提示，说明当前投影使用的字段、以及可通过 --fields 选择其他字段。该提示只写 stderr、不改写 stdout，管道给 jq 等工具时输出保持不变。
Agent Skills
Flashduty CLI 内置一个名为flashduty 的 Agent Skill，可让 Claude Code、Cursor、Codex、Gemini CLI、Windsurf 等 AI 编程代理通过 CLI 操作 Flashduty。
一键安装到当前机器上检测到的所有代理：
SKILL.md 承载认证、全局参数、安全规则等共享约定，并按领域索引参考卡——故障、告警、变更、值班与排班、协作空间与分派、状态页、洞察、监控、RUM 与 sourcemap、自动化、通知模板、成员与团队等。代理执行任务前先读取对应领域的参考卡，即可获得该领域的全部命令、参数与工作流，无需 --help 试探。
常见用法
在告警通知中追加 CLI 链接
在告警通知中追加 CLI 链接
通过
flashduty incident get <id> 在终端中快速查看故障详情，可将命令片段嵌入到通知模板里供值班同学一键复制。批量认领或关闭故障
批量认领或关闭故障
将故障数据导出到 BI 工具
将故障数据导出到 BI 工具
jq 处理或导入数据仓库。在 CI/CD 中验证通知模板
在 CI/CD 中验证通知模板