概述
Flashduty CLI(flashduty)是一款命令行工具,可在终端中完成故障生命周期管理、值班查询、状态页发布、通知模板调试等操作,适用于运维脚本、本地排障以及与 AI 编程代理协同工作。
工具开源在 flashcatcloud/flashduty-cli,支持 macOS、Linux 和 Windows。版本发布与更新说明见 GitHub Releases。
安装
- macOS / Linux
- Windows (PowerShell)
- 手动下载
PATH 上已有的那份 flashduty 所在目录,便于就地升级替换掉旧副本;PATH 上没有 flashduty 时才安装到 /usr/local/bin。可通过环境变量 FLASHDUTY_INSTALL_DIR 自定义安装目录。安装选项
以自定义命令名安装的副本,在帮助、错误信息与 Shell 自动补全中都使用该名称;
flashduty update 按正在运行的可执行文件名与所在目录就地替换自身,而不是另装一份默认命名的副本。
安装脚本结束时会再核对一次 PATH:若当前 Shell 实际运行的 flashduty 不是刚装的那份(被更靠前的旧副本抢占),会在输出里提示删掉旧副本或把新目录提前。若当前进程由 flashduty-runner 托管(FLASHDUTY_MANAGED_BY_RUNNER=1),脚本会拒绝执行并提示改为升级 runner——runner 自带一份与它一同验证过的 CLI,就地替换会让两者失配。
认证
登录
凭证解析顺序
CLI 按以下优先级查找 APP Key(高优先级在前):--app-key命令行参数(脚本场景使用)FLASHDUTY_APP_KEY环境变量- 配置文件
~/.flashduty/config.yaml(由flashduty login写入)
环境变量
CLI 运行时读取以下环境变量(安装脚本识别的变量见上文「安装选项」):配置文件
存储在~/.flashduty/config.yaml,权限为 0600:
配置命令
全局参数
以下参数注册在根命令上;除--version 外,其余所有子命令均可使用:
命令清单
incident — 故障生命周期
incident list 常用过滤参数:
时间格式示例:
5m、1h、24h、168h、2026-04-01、2026-04-01 10:00:00、1712000000。
incident feed <id> 按页读取故障的动态流(时间线条目):--asc 让最旧的条目在前(默认最新在前),--types 按逗号分隔的条目类型过滤(如 i_comm,i_assign,条目的 type 字段给出实际类型),另有 --limit(最大 100)与 --page。
incident alerts <id> 列出该故障关联的告警,支持 --limit(默认 10)与 --page(默认 1)。
创建、更新与合并
incident create 的 --title(3–200 字符)与 --severity 必填,在终端中缺少时会交互提示。指派方式有三种,可组合使用:--assign(成员 ID 列表)、--assign-emails(成员邮箱,逗号分隔;不匹配任何成员的邮箱会被忽略)、--escalate-rule-id 加 --escalate-layer(从该分派策略的指定环节(从 0 开始)起,指派该环节的人员;--escalate-layer 必须与 --escalate-rule-id 一起使用)。
incident create 与 incident update 都支持可重复的 --field key=value 设置自定义字段,值按字段类型转换:复选框取 true / false;多选取逗号分隔的选项或 JSON 数组(如 a,b 或 ["a","b"]);单选和文本取字符串。
incident merge <target-id> 把 --source(逗号分隔的源故障 ID,最多 100 个)合并到目标故障。默认源故障被关闭并保留,目标故障时间线上记录合并事件;加 --remove-source-incidents 则删除源故障,故障列表中不再显示。可选 --title 同时重命名目标故障,--comment-file 从文件读取合并备注(- 表示 stdin)。
工作项与跟进项(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(乐观锁,必须与当前存储版本一致)。
工作项状态只接受 open / in_progress / done / cancelled 四个取值:work-item-create --status 省略或留空时默认 open,work-item-update --status 只能改成这四个值之一,work-item-complete --target-status 只接受 done(其它取值会被拒绝),work-item-convert --target-status 可传这四个值之一。
工作项的负责人可以是成员,也可以是本账户的 AI SRE:
work-item-create与work-item-assignees-reset接受assignees字段(每项形如{type, id?},type取person或ai_sre;ai_sre项不带id,最多 20 项),该字段只能通过--data传 JSON。--assignee-ids是等价的旧别名(相当于全部为person),两者互斥,同时传会报错。work-item-list新增--assignee-type person|ai_sre:ai_sre返回指派给 AI SRE 的事项(AI 调用方用它列出自己的任务),此时不需要--assignee-id,--assignee-id也会被忽略;person搭配--assignee-id只返回该成员负责的事项。省略本字段且--assignee-id为正数时按person过滤。- 工作项响应里的
assignee_ids现在只包含人员负责人(不含 AI SRE),完整负责人列表在assignees;由 AI SRE 执行的事项还会返回agent_session_id与agent_session_venue(web或im),没有关联会话时这两个字段省略。
复盘报告(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-*)
--comment-type-id 附上账户级评论类型:flashduty incident comment <id> [<id2>...] --comment-file <path> --comment-type-id <comment-type-id>;评论类型 ID 来自 flashduty incident comment-type-list,省略该参数则写入不带类型的评论。
change — 变更记录
--channel、--integration(上报变更的集成 ID)、--query(关键字/正则搜索)、--filters(JSON 数组形式的结构化过滤)、--include-events(附带底层变更事件)、--since、--until(窗口须小于 31 天)、--orderby(start_time 或 last_time)、--asc、--limit、--page。
member — 成员查询
member list 支持 --query(姓名/邮箱关键字搜索)、--role-id、--member-id(按成员 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 支持 --name(团队名称子串匹配)、--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)--reset-if-name-exist(--team-id为空且存在同名团队时,原地更新该团队而不是报名称冲突)
team upsert 的 --emails / --phones 只匹配并附加现有成员,不会发送任何邀请。需要邀请新成员加入组织时,请使用 flashduty member invite。team delete 支持通过 --id、--name 或 --ref-id 指定团队,交互终端会二次确认(--force 跳过),操作不可逆。
channel — 协作空间查询
--name 在服务端对协作空间名称和描述做不区分大小写的子串匹配;精确匹配名称用 --channel-name。其他过滤:--channel-ids、--team-ids、--is-my-managed、--is-my-starred、--is-my-team、--is-brief(只返回 ID、名称、描述和状态,不分页)、--orderby、--asc、--limit、--page。
channel escalate-rule-list — 分派策略查询
分派策略查询属于channel 命令组,通过位置参数传入协作空间 ID:
escalate-rule-create、escalate-rule-update、escalate-rule-delete、escalate-rule-reorder(均在 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 为规则 ID 字符串。
field — 自定义字段查询
--name(按字段名过滤)、--query(对字段名做不区分大小写的正则匹配)、--creator-id、--orderby、--asc。
status-page — 状态页管理
事件草稿(draft-create)
draft-create 保存一份状态页事件草稿(故障事件或维护窗口),供人工在控制台审阅后发布——草稿本身不会对外发布:
--source:起草来源标记(如my-script),最多 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 的核心字段:
--data 里的 repositories 把应用关联到构建它的代码仓库:有序数组,第一项为主仓库,最多 10 项,每项为 repo(owner/name 形式的 GitHub 仓库,必填)加可选的 subdir(应用在仓库内所在的目录,相对仓库根目录,. 表示仓库根目录,传空值会保存为 .)。创建时传入即建立关联;更新时按 presence 处理——传入即整体替换、传空数组清空全部关联、省略则保持不变;application-info、application-infos、application-list 都会回显该字段。关联本身不授予任何访问权限:AI 会话只能读取账户 GitHub App 安装已授权的仓库(见 应用与集成)。该字段目前仅通过 API 与 CLI 提供,控制台的应用管理页不暴露仓库关联设置。
application-webhook-test 会返回 ok、status_code 和 message,可用于验证 RUM 告警 Webhook 是否真正收到了平台发出的测试事件。远程配置(application-remote-config-*)
远程配置按应用维护一份采集与隐私参数,发布后由 SDK 在下一个新会话生效。控制台侧的配置项含义、发布与生效方式见 应用管理 · 远程配置:config 对象:enabled、activation、default、rules、custom、refresh_on_foreground)经 --data 传入;--data 也可携带整个请求体,位置参数与具名标志会覆盖其中的同名字段。
发布与回滚都会分配一个新版本号(回滚不会复现旧版本号)。配置变更对新会话生效:
activation 为 next_session(默认)时运行中的会话不受影响,为 immediate 时客户端收到配置后结束当前会话、由新会话按新配置运行;发布 enabled: false 可关闭配置下发,各端回落到 SDK 初始化设置。
会话回放
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 表示当前临时许可证窗口内生效。
calendar — 服务日历
服务日历是分派策略与静默规则判断工作日/休息日的依据,控制台侧的配置与层级优先级见服务日历。该命令组由 OpenAPI 生成(见下文「全量命令覆盖」):<cal-id>(形如 cal.<uuid>)为位置参数,取自 calendar list 响应 items[] 里的 cal_id;list 默认只列账户自有日历,列公共节假日日历要加 --kind region.official.holiday(默认按调用者所在地区过滤,加 --no-locale 取消过滤)。
--help 和响应本身看出来:
event-delete兼具删除单条事件与清空日期区间两种用法。传--event-id删除一条事件;或传--start-at与--end-at(均为YYYY-MM-DD,end_at为开区间、必须晚于start_at)清空该日历自身在[start_at, end_at)内的全部事件。被清空的日期回落到关联的节假日日历与每周工作日,效果相当于在控制台里对这些日期点击恢复默认。event-upsert会裁剪同区间内该日历自身的其他事件:完全落在区间内的被删除、部分重叠的被缩短、跨越区间的被拆成两条,因此这些天以最后一次写入为准(--summary可选)。event-list的响应除行数组items外还有days:按YYYY-MM-DD给出请求范围内每一天的解析结果,含is_off、决定该天的event_id与层级layer——custom(日历自有事件)优先于holiday(关联的节假日日历),再优先于weekly(每周工作日);同一层级内工作日事件优先于休息日;layer缺失表示没有任何事件覆盖该天,按工作日计。判断某天是否休息请读days,不要从items反推:同一天可能同时存在多层事件。
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)。导出内容可能很大,建议重定向到文件而非直接打印到终端:
safari send / safari watch — 从终端与 AI SRE 对话
flashduty safari send 把一条消息送进 AI SRE 会话,flashduty safari watch 把 Agent 的答复逐行读回来。两者配合可以在终端或脚本里跑完一次排查对话;会话与控制台共用,见控制台对话。
send 的正文有三个来源,只能用其中一个:位置参数、--message-file <path>(- 表示标准输入)、或标准输入(既没有位置参数也没有 --message-file、且标准输入不是终端时读取)。位置参数与 --message-file 同时给出会直接报错。正文最多 32000 个字符(按 Unicode 字符计),超出时报错并提示较长的内容改用 --file 附带;正文与附件都不给同样报错。
成功时标准输出是一行 JSON 回执,字段为
session_id、invocation_id、root_invocation_id 与 delivery_mode;其中 root_invocation_id 就是 safari watch --root-invocation-id 要传的值。消息走命令行通道,delivery_mode 为 reply_only:Agent 只通过它的回复工具作答,答复要用 safari watch 读取。服务端没有授予这个通道时命令直接失败,错误信息里带上 session_id 与 invocation_id——此时消息已经入队,但它的答复不会出现在 safari watch 的输出里,命令不会退回成别的投递方式。
带 --session-id 发消息时,命令先读一次会话状态:如果该会话还有回合在跑,这条消息会被那个回合在下一个步骤并入并由它作答,不再等这一轮结束;会话空闲时它照常走自己的一轮。
用 --file 而不带 --session-id 时,命令先创建会话再上传附件。
safari watch 把事件逐行写到标准输出:每行一个紧凑 JSON 对象,诊断信息只写标准错误,其他内容一概不写进标准输出。
打印 Agent 的答复本身,包括它通过回复工具发出的消息,以及不使用回复工具作答的那一轮的最终回答。工具调用、思考过程和其他助手文本属于它的内部工作内容,不会输出。跟随的是整条会话:同一会话里别人的消息、以及把这条消息并入运行中回合的那一轮,它们的答复同样会打印出来。
连接断开后从最后一条已收到的事件继续回放,同一条消息不会重复打印。只用
--since 重新起一个 watch 时,正好落在该毫秒的事件会再出现一次;要接着上次的输出往下跟,把上一行的 created_at 传给 --since、event_id 传给 --since-event-id。
重试 8 次仍没有收到任何事件即放弃,以非零退出码结束并带上最后一次的错误。
跟随的那次请求已结算(自己开了一轮,或被运行中的回合并入),之后有一个不是 steered 的回合结算、没有仍在运行的后台任务,并且会话已无运行中的回合时,命令退出 0;请求还有后台任务时会继续等待它们把后续回合跑完。不可恢复的错误(限流与 408 之外的 4xx、运行环境准备失败)以非零退出码结束,同时在标准输出上留一行 {"type":"error",…},运行环境准备失败时这一行就是该事件本身。
monit-query — 监控数据源统一工具调用
monit-query 对已配置的数据源执行单个命名工具,是查询与诊断的统一入口:查询工具(<type>.query,覆盖 prometheus、mysql、postgres、oracle、clickhouse、elasticsearch、loki、victorialogs、sls、tencent_cls)与诊断工具(如 mysql.overview、redis_node.slowlog)都走它,无需经过告警规则层。数据源 ID 从 monit datasource-list 的 id 字段获取:
查询工具要求集群内所有在线 Edge 版本不低于 v0.68.0,诊断工具要求不低于 v0.71.0。版本不满足时命令直接失败并返回错误码:
edge_upgrade_required(Edge 版本过低)、mixed_edge_versions(集群内 Edge 版本混合)、edge_version_unknown(集群内存在版本无法识别的 Edge)、no_active_edge(没有可用的在线 Edge)。请先升级 Edge,不要轮换 Edge 重试。
查询工具返回完整的 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 命令等价,推荐使用 monit-query。数据源 ID 从 monit datasource-list 的 id 字段获取:
语义与限制:
- 无工具目录、无自动重试、无回退:一次调用只执行一个命名工具,参数需按各数据源工具约定填写,不要从命令行列表猜测。除诊断工具外,入口还支持
<type>.query查询工具(prometheus、mysql、postgres、oracle、clickhouse、elasticsearch、loki、victorialogs、sls、tencent_cls)。 - 请求体 ≤128 KiB;完整成功响应 ≤10 MiB;工具超时 ≤25 秒。
- 需要数据源
enabled=true;alerting_enabled=false不阻塞诊断。 - 返回值:
data(工具特定的 JSON 证据,原样保留、永不为 null)、tool、datasource_id、可选summary,以及truncated对象(含reason,存在即表示结果被截断)。
tool_not_supported(工具不支持)时按上文处理;出现 invalid_request 时修正参数,出现 source_too_large / result_too_large 时收窄请求范围。
monit — 数据源、仪表盘与规则分组
在保存规则前验证数据源表达式,用上文的monit-query <datasource-id> --tool '<type>.query' 直接执行查询。
数据源管理(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:...}引用会回显。更新时省略这些字段以保留已存密钥,显式传空字符串表示清除。
仪表盘与规则分组(dashboard-* / folder-*)
monit dashboard-* 命令族管理监控仪表盘(由 OpenAPI 生成命令提供)。仪表盘本身是一份 dashboard.v1 文档,创建与更新时通过 --data 传入 definition;update / delete / move / restore 都要求 --expected-revision——传入的版本不是当前版本时以 DashboardRevisionConflict 拒绝,需要重新读取后再提交。
monit folder-* 是分组本身的增删改查:folder-health 返回 {items:[...]} 分页信封(每项只有 folder_id 与 has_issue,has_issue 表示该分组或其可见后代存在活跃告警或规则运行问题),folder-list 返回顶层数组,用法都是 --json | jq;folder-create 与 folder-update 返回更新后的单个分组对象;folder-move 与 folder-delete 不返回分组对象。分组名不能含 .、/、,;folder-move 的 dest-parent-id 即使移到根(0)也必须显式给出;folder-delete 只接受空分组——内部还有子分组、规则或仪表盘时会被拒绝,需要先自行清空。
面板运行时与变量解析的时间窗口、变量选择都以 JSON 对象放在 --data 里(时间用 from_ms / to_ms 的毫秒时间戳)。dashboard-panel-preview 与 dashboard-runtime-variables-preview 需要一个 context:kind: existing 配 dashboard_id 指向已存仪表盘,kind: new 配 folder_id 指向尚未落库的分组。
dashboard-runtime-queries-resolve 另有两个影响解析结果的参数:--max-data-points(整数,取值 2–5000;既作降采样目标,也决定解析出的表达式里内置时间变量渲染出的步长,省略或传 null 时取服务端默认值 100)与 --preserve-builtin-variables(布尔,默认关):开启后内置时间变量在解析结果里原样保留,交由自带执行窗口的调用方自行渲染,用户变量仍会被解析。兄弟命令 dashboard-panel-run 与 dashboard-panel-preview 早已带 --max-data-points,同为 2–5000 的降采样目标。
prometheus-api-v1-label-{label_name}-values — 查询 Prometheus 标签值
查询 Prometheus 兼容数据源上某个标签的全部取值,命令名为 monit prometheus-api-v1-label-{label_name}-values(在 flashduty monit --help 下可见),按下面的写法使用:
返回体是数据源原生的 Prometheus 载荷,不带 Flashduty 的
{request_id, error, data} 信封:成功时为 {"status":"success","data":["api","db","worker"]}。数据源自身拒绝查询时(如标签名不存在),命令以非零退出码失败,错误文本是数据源(或 Monitors 代理)返回的原始内容——Prometheus 的原生错误形如 {"status":"error","errorType":"bad_data","error":"unknown label name"},与 Flashduty 的错误码体系无关。
本命令只取某个标签的取值集合;要按表达式取时序数据或做更复杂的 PromQL 查询,请用上文的
monit-query <datasource-id> --tool 'prometheus.query'。alert — 告警与告警事件查询
list 命令常用过滤参数:--severity(Critical,Warning,Info)、--channel(逗号分隔协作空间 ID)、--integration(逗号分隔的集成 ID)、--since/--until、--limit(最大 100)、--page。--since 与 --until 之间的窗口须小于 31 天(与 incident list、change list 相同)。alert-event list 另有 --integration-type,按逗号分隔的插件键过滤(如 AliCloud,Prometheus)——注意它取插件键而非集成 ID,按集成 ID 过滤请使用 --integration。
alert list 另有 --alert-ids(逗号分隔的告警 ID)、--alert-keys(逗号分隔的告警去重键)、--asc(按开始时间升序,默认最新在前)、--by-updated-at(把 --since/--until 应用到最近更新时间,而不是开始时间);alert-event list 也支持 --asc(升序,默认最新在前),但没有 --by-updated-at。
alert list 还用 --active(只看活跃告警)与 --recovered(只看已恢复告警)筛选状态:二者互斥,同时传入会报错;只传其中一个时,--active 对应活跃、--recovered 对应已恢复,都不传则不加状态过滤。活跃告警可能早于一天,因此 --active 且未指定 --since 时默认窗口放宽到 30 天(实际生效的窗口见 stderr 的窗口提示)。
alert events <alert_id> 列出组成该告警的原始事件:--limit 默认取服务端默认的 20 条(上限 100),--page 从 1 开始。它按单个告警取事件,跨告警的时间窗查询用 alert-event list。
automation — AI SRE 自动化规则
automation 命令组管理 AI SRE 的自动化规则——创建、查询、更新、删除、运行历史与触发,页面操作见自动化。
create 常用参数:
从 IM 会话里创建规则时,省略
--run-in 即让服务端把规则绑定到当前会话,同时继承该会话的作用域;不需要(也不应该)自己传 chat、平台、集成或会话 ID——服务端负责解析并鉴权当前会话。绑定当前会话之后,每次普通运行都会新建一个执行会话,IM 集成建线程时也会新建线程,并始终留在创建时捕获的那个会话与不可变作用域上,而不是复用旧会话或旧线程;同一次运行的重试复用该次运行的执行身份。若运行发生时绑定会话的作用域已与规则不符,本次运行会被跳过,规则不会被搬到别的会话里执行。作战室触发的规则行为不变。由于每次运行都是全新上下文,提示词必须自带所需的聊天上下文(服务对象、团队、投递目标等),不要写「上文/上述」这类指代。执行位置与作用域一样创建后不可变更。
作战室创建触发器在匹配的协作空间里创建作战室(IM 群聊)时拉起一次运行,这次运行的会话建在该作战室的群聊里、不在控制台——--run-in 对它不生效,执行环境也取群里已经选好的那个,规则上的执行环境不影响它。字段语义与运行表现见自动化 · 作战室创建触发。
update 可改字段:--name、--prompt/--prompt-file、--schedule/--at/--weekday/--cron-expr/--timezone、--enable/--disable、--enable-schedule/--disable-schedule、--enable-http-post-trigger/--disable-http-post-trigger、--rotate-http-post-token、--enable-war-room-trigger/--disable-war-room-trigger、--war-room-channel-ids/--war-room-severities、--environment-kind/--environment-id。--enable-war-room-trigger 与 --disable-war-room-trigger 互斥,同时传入会报错;--war-room-channel-ids/--war-room-severities 一旦传入就整体替换该触发器的过滤器,通过 update 首次创建作战室触发器时服务端要求两个列表都给出。个人 / 团队作用域与执行位置(--run-in)创建后不可变更,update 不提供这两类参数。update 的 --cron-expr 与 create 同一约束:分钟位必须是 0–59 的单一整数,最快每小时一次,不支持分钟位的通配符、范围、列表与步长。
runs 支持 --status(queued/running/retrying/succeeded/partial/failed/skipped/abandoned)、--trigger-kind(服务端取值 schedule/debug/manual/http_post/oncall_incident/war_room_created,其中 war_room_created 表示由作战室创建触发的运行)、--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 Open API,按资源组织为顶层命令组,可用flashduty <命令组> --help 查看。其中 session export、safari send、safari watch、enrichment mapping-data-upload、safari skill-upload 和 monit prometheus-api-v1-label-{label_name}-values(见下文「查询 Prometheus 标签值」)为手工实现。除 On-call 域(incident、incident-trigger-subscription、change、channel、field、status-page、template 等)外,还覆盖了:
- AI SRE(
safari):a2a-agents、artifacts、automations、knowledge、mcp-servers、sessions、skills 等,另有手工实现的send与watch(见上文「safari send / safari watch — 从终端与 AI SRE 对话」) - 告警与降噪: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 集成)、integration(告警源 / 变更源集成的增删改查与密钥轮换,密钥掩码与更新规则见下文「integration — 集成与密钥」)、
channel integration-*(协作空间专属集成的增删改查与密钥轮换,见下文「channel integration — 专属集成」)、webhook(integrations)
flashduty safari a2a-agent-get、flashduty safari session-list),每个公开 API 操作都对应一条 flashduty <分组> <动作> 命令,命令名由 API 路径推导,请求字段生成带类型的命令行参数,--data 可传完整 JSON 请求体(具名参数覆盖其中的同名字段)。完整清单不在本页展开,用 flashduty <资源> --help 逐层探索:
--data 里的字段若在当前 CLI 版本的 SDK 中没有对应字段,这些字段不会被发出去:绑定请求体后 CLI 会在 stderr 打印一行 warning: --data fields not sent, unknown to this CLI version: <字段路径>(路径以点号分隔、数组元素以 [] 结尾,如 labels.k.note、targets[].purpose,多个字段用逗号分隔)。调用本身照常成功,stdout 不受影响——出现这行警告说明所传字段比本机 CLI 版本更新,依赖这些字段生效的脚本应先升级 CLI。
生成命令的时间窗口参数(--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 的知识——账户或团队作用域下的版本化文件树(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决定调用者能否重命名/转移/删除/分享(创建者、所属团队成员或源会话管理者)。
integration — 集成与密钥
integration 命令族管理账户级的公开集成——告警源、变更源、IM 机器人与自定义 Webhook,共 9 个子命令:list、info <integration-id>、type-list、create、update <integration-id>、delete <integration-id>、enable <integration-id>、disable <integration-id>、key-rotate <integration-id>。渠道专属的集成(ref_id 以 c_ 开头)不在这 9 个命令里,用下文的 flashduty channel integration-* 管理。
settings 的读回与密钥语义:
list与info返回的settings中,每个已保存的密钥类值——密码、App Secret、Token、加密密钥、HTTP 拉取的 URL 与 Body、Headers 的值——一律显示为******;Webhook 与自定义操作的地址和自定义 Body 按原值返回;未设置的值保持为空。integration_key是例外,按原值返回(它用于接入推送,与账户级app_key不是一回事)。依赖integration info --json读取凭据的脚本拿到的是掩码;需要新密钥时用key-rotate轮换,旧密钥会立即失效。update提交的settings是整体替换:已知敏感字段被省略或传******时保留已存密钥,显式传空headers: {}会清空 Headers。但改密钥的发送目标时不能沿用已存密钥——例如改endpoint、url,或改数据库的主机/端口——必须同时传入真实密钥,否则请求被拒。editable只表示对象权限(no_editable: true表示该集成只读);写操作除此之外还需要集成中心管理权限。
channel integration — 专属集成
属于某个协作空间(而不是集成中心)的告警集成由channel 组下的 8 个命令管理,产品侧的功能模型见集成数据:
integration-list 与 integration-create 的协作空间 ID 是位置参数(也可写作 --channel-id),新建时该协作空间必须已启用;其余 6 个命令的位置参数是响应里的 integration_id(整数),不能传公共集成的 ID。
integration-list 的参数:
返回
items、limit、p 与 total;每行含 integration_id、channel_id、name、description、plugin_type、plugin_type_name、status、settings(已保存的密钥显示为 ******)、integration_key(按原值返回,用于接入推送,与账户级 app_key 不是一回事)、created_at、updated_at、last_time 与 last_source_time。
integration-create 的可用字段:
返回新集成的
integration_id 与 integration_key。
integration-update 只改 --name、--description 与 settings:名称 2–49 字符,备注传空即清空、省略即保留;settings 整体替换,其中被省略或回传为 ****** 的敏感字段保留已存值。它不能把集成搬到另一个协作空间,也不能改集成类型——要换归属或类型请在控制台重建。integration-key-rotate 返回新密钥,旧密钥立即失效,依赖它的推送要同步更新。
读取(integration-list、integration-info)需要协作空间查看、协作空间管理或集成中心查看权限,并且目标协作空间对您可见;写入(integration-create、integration-update、integration-delete、integration-enable、integration-disable、integration-key-rotate)需要协作空间管理权限,且您对该协作空间有管理资格。integration type-list 的类型目录由两族命令共用,integration.api:read:typeList 在协作空间查看、协作空间管理与集成中心查看三项权限里都有;限制了接口范围的 App Key 须允许它。
工具命令
flashduty update 会下载并执行平台安装脚本,将当前二进制替换为最新版本。--check 仅打印可用版本号,不修改本地文件。在终端中执行其他命令后,若检测到有新版本可用,CLI 会在 stderr 自动输出更新提示横幅。输出格式
通过--output-format 选择输出形态(--json 是 --output-format json 的别名),便于在不同场景下消费:
- 表格(默认)
- JSON(--json / --output-format json)
- TOON(--output-format toon)
- 完整表格(--no-trunc)
人类可读,列对齐,长字段截断显示。生成命令的列表响应若在行数组(
items / docs / list)之外还带其它字段(如 calendar event-list 的 days),表格会在行表格之后额外打印一行 Also in the response: <字段> (use --json to see it).,提示这些字段不在表格里,要看它们请用 --json 或 --output-format toon。时间窗口提示
查询时间范围的命令会把本次实际发送的窗口按本地时区写到 stderr,例如note: window 2026-10-08T14:00:00+08:00..2026-10-09T14:00:00+08:00 (1d, ended now)。括号里是窗口跨度与结束时间相对当前的位置(ended 3m ago / ends in 2h);若窗口来自某个默认值而非您显式传入的 --since/--until,还会说明是哪个默认值(如 --progress 只含开放状态、--active)。
覆盖范围包括 incident list、alert list、alert-event list、change list、audit search、insight、oncall、monit-query(工具参数带执行窗口时),以及所有解析出 --start-time/--end-time 的生成命令(只给出一侧、另一侧交给 --data 或服务端默认的命令不输出该提示,因为窗口没有被完整确定)。只有一个时间点的查询写成 note: instant <时刻> (…)。
它用来核对窗口是否就是您要的那个:默认值可能比您预期的宽(例如 --active 会把默认窗口放宽到 30 天),把时间戳按错误时区解读会让窗口落到未来,此时提示形如 ends in 7h。提示只写 stderr,stdout 保持原样,jq 与 toon 消费方不受影响。
生成命令的输出上限
由 OpenAPI 代码生成提供覆盖的生成命令(如safari session-list、monit datasource-list、safari a2a-agent-list 等),其 json / toon 输出对列表形态的响应按 16 KiB 上限处理。缩减分三级,另外会有一个机读标记:
- 整页超限:只输出能完整放下的前几行,每个值保持原样,stderr 提示实际输出了 N/M 行、其余行未输出。
- 单行本身超限:该行的字符串值以
...截短,stderr 点名被截字段;标识符字段(以_id/_key结尾)不会被截短。 - 行无法缩减到上限以内:命令报错并点名字节数最大的字段(最多 3 个),请调低
--limit或减少输出字段后重试。
items / docs / list、同级只有 total、has_next_page、search_after_ctx 等标量字段的响应(如 monit datasource-list、safari session-list);一旦发生缩减,CLI 会重建该信封并在 payload 中补写字段,脚本无需解析 stderr 也能发现缩减:
- 整行被丢弃:写入
truncated: true与emitted_rows: N(N 为实际输出的行数)。此时信封中的total、has_next_page、search_after_ctx仍是服务端原始分页的原样回显,不能用来判断是否已取全——被截成「100 行中前 7 行」的一页照样带着原来的分页字段。要取全请按实际收到的行数收窄--limit重新请求,再沿返回的游标继续翻页。 - 只有长值被截短(没有丢行):只写
truncated: true,stderr 会点名被截字段。重新请求无法找回这些值,请收窄筛选条件、减少每页行数,或用全局--fields只保留需要的字段。
items / docs / list、但同级还有对象或数组字段的响应(如 calendar event-list 的 days 地图),无法在不丢字段的前提下压进 16 KiB,因此整包原样输出、处理方式同本节末段的明细形态的单个对象:既不写 truncated / emitted_rows,也不截短任何值。
顶层数组形态的响应(如精选命令 incident list、insight incidents)没有信封可承载标记,缩减仍只写 stderr。
明细形态的单个对象(如 safari session-get 的详情)不做截断、原样输出——截短后的值无法与真实短值区分,因此这类响应不受上限约束。生成命令可以用全局 --fields 收窄输出的字段(见「全局参数」与下文「结构化输出的字段投影」;个别命令的 --fields 是请求体的字段选择器,如 monit rule-update-fields,不作用于输出);需要完整 JSON 时请通过 --limit 调小每页数量、配合 --page 分页逐页拉取(如 flashduty safari session-list --limit 20 --page 2),或按需收窄筛选条件。
结构化输出的字段投影
--fields 是全局参数(见「全局参数」):任意命令在 json 或 toon 输出时都能用它,逗号分隔要保留的顶层字段,作用于列表的每一行或单个记录。投影在返回结果上执行:列表信封(行数组为 items、docs 或 list,同级只有标量分页字段)只收窄其中的行数组,分页字段原样保留;某个字段在整个响应里都不存在时不会被写入输出,stderr 会提示该字段未匹配到任何键、并列出实际存在的键;输出既不是对象也不是对象列表时,命令报错并要求去掉 --fields。表格输出忽略 --fields,此时 stderr 会提示它未生效。
下表列出的精选命令在省略 --fields 时按默认紧凑投影输出,并受大小上限约束;它们各自定义了自己的 --fields(含义与全局一致),字段名写错会直接报错并列出具名可用的字段。其它命令——包括全部生成命令——不带默认投影,--fields 直接作用在接口返回的原始字段上,字段名未命中只会得到上面那条 stderr 提示。
例如,只导出故障编号、标题和处理进度:
incident list、incident similar、alert-event list、channel escalate-rule-list、insight incidents)超过 16 KiB 上限时,缩减的三级行为与上文「生成命令的输出上限」相同,提示只写 stderr、不改写 stdout;区别是请用 --fields 或 --limit 收窄输出,让每页容纳更多行或取回完整值。被截短的字段上匹配或过滤会漏数据;标识符字段(以 _id 或 _key 结尾)在任何一级都不会被截短。
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 工具
--page 逐页拉取;然后通过 jq 处理或导入数据仓库。在 CI/CD 中验证通知模板
在 CI/CD 中验证通知模板