跳转到主要内容

概述

Flashduty CLI(flashduty)是一款命令行工具,可在终端中完成故障生命周期管理、值班查询、状态页发布、通知模板调试等操作,适用于运维脚本、本地排障以及与 AI 编程代理协同工作。 工具开源在 flashcatcloud/flashduty-cli,支持 macOS、Linux 和 Windows。版本发布与更新说明见 GitHub Releases。

安装

默认安装到 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,就地替换会让两者失配。

认证

登录

按提示输入 APP Key。获取方式:登录 Flashduty 控制台,进入 个人中心 → APP Key 创建并复制,详见个人设置。

凭证解析顺序

CLI 按以下优先级查找 APP Key(高优先级在前):
  1. --app-key 命令行参数(脚本场景使用)
  2. FLASHDUTY_APP_KEY 环境变量
  3. 配置文件 ~/.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 许可证

该命令只读,返回成员 ID、名称及许可证类型: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,存在即表示结果被截断)。
出现上述 Edge 版本类错误码或 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)。
时区语义:--at 与 --cron-expr 均按规则时区的本地挂钟时间理解。create 省略 --timezone 时由服务端决定规则时区——依次取调用者的成员时区、账户时区,最后回退 Asia/Shanghai;需要固定其它时区时传入 IANA 名称(如 --timezone Asia/Shanghai),服务端无法加载的时区会被拒绝。update 省略 --timezone 时保留已存储的时区(包括历史遗留的空字符串),显式传空值 --timezone "" 会按 UTC 发送并存储,而不是账户默认时区。请直接传用户的本地时间,不要预先换算成 UTC。update 会立即重算下次触发时间,请以响应中的 schedule_next_fire_at_ms 为准。

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 自动输出更新提示横幅。
启用 Shell 自动补全示例(zsh):

输出格式

通过 --output-format 选择输出形态(--json 是 --output-format json 的别名),便于在不同场景下消费:
人类可读,列对齐,长字段截断显示。
生成命令的列表响应若在行数组(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 上限处理。缩减分三级,另外会有一个机读标记:
  1. 整页超限:只输出能完整放下的前几行,每个值保持原样,stderr 提示实际输出了 N/M 行、其余行未输出。
  2. 单行本身超限:该行的字符串值以 ... 截短,stderr 点名被截字段;标识符字段(以 _id / _key 结尾)不会被截短。
  3. 行无法缩减到上限以内:命令报错并点名字节数最大的字段(最多 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 试探。

常见用法

通过 flashduty incident get <id> 在终端中快速查看故障详情,可将命令片段嵌入到通知模板里供值班同学一键复制。
单页最多 100 条,用 --page 逐页拉取;然后通过 jq 处理或导入数据仓库。
将上述命令加入 CI,可在模板提交时立即捕获语法或字段错误。
完整源码和问题反馈请访问 GitHub 仓库,版本发布见 GitHub Releases。