命令行工具 - Flashduty Docs

概述

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

安装

macOS / Linux
Windows (PowerShell)
手动下载

curl -sSL https://static.flashcat.cloud/flashduty-cli/install.sh | sh

默认安装到 /usr/local/bin，可通过环境变量 FLASHDUTY_INSTALL_DIR 自定义。

irm https://static.flashcat.cloud/flashduty-cli/install.ps1 | iex

默认安装到 ~\.flashduty\bin，可通过环境变量 FLASHDUTY_INSTALL_DIR 自定义。

访问 CDN 最新版本指针获取最新版本号，然后从 https://static.flashcat.cloud/flashduty-cli/releases/download/<version>/<asset> 下载对应平台的二进制包，解压后放入 PATH 即可。

安装选项

环境变量	说明	默认值
`FLASHDUTY_VERSION`	安装指定版本，如 `v0.6.0`	最新版本
`FLASHDUTY_INSTALL_DIR`	安装目录	`/usr/local/bin`（Shell）、`~\.flashduty\bin`（PowerShell）
`MIRROR_URL`	覆盖安装脚本的 Release 资产下载镜像前缀，需以 `https://` 开头	`https://static.flashcat.cloud/flashduty-cli`
`FLASHDUTY_UPDATE_BASE_URL`	覆盖 `flashduty update` 及自动更新检查的下载基础 URL	`https://static.flashcat.cloud/flashduty-cli`

认证

凭证解析顺序

CLI 按以下优先级查找 APP Key（高优先级在前）：

--app-key 命令行参数（脚本场景使用）
FLASHDUTY_APP_KEY 环境变量
配置文件 ~/.flashduty/config.yaml（由 flashduty login 写入）

配置文件

存储在 ~/.flashduty/config.yaml，权限为 0600：

app_key: your_app_key
base_url: https://api.flashcat.cloud

配置命令

flashduty config show              # 查看当前配置（APP Key 已脱敏）
flashduty config set app_key KEY   # 设置 APP Key
flashduty config set base_url URL  # 覆盖 API 地址

全局参数

所有子命令均支持以下参数：

参数	说明
`--output-format`	输出格式：`table`（默认）、`json` 或 `toon`（紧凑、更省 token）
`--json`	以 JSON 格式输出，是 `--output-format json` 的别名，便于通过 `jq` 等工具解析
`--no-trunc`	表格输出时不截断长字段
`--base-url`	覆盖 API 地址（私有部署场景）

命令清单

incident — 故障生命周期

flashduty incident list [flags]         # 列出故障（默认最近 24 小时）
flashduty incident get <id> [<id2>...]  # 查看故障详情（单个 ID 显示完整视图）
flashduty incident create [flags]       # 创建故障（参数缺失时进入交互模式）
flashduty incident update <id> [flags]  # 更新故障字段
flashduty incident ack <id> [<id2>...]  # 认领故障
flashduty incident close <id> [<id2>...] # 关闭（解决）故障
flashduty incident timeline <id>        # 查看故障时间线
flashduty incident alerts <id>          # 查看故障关联的告警
flashduty incident similar <id>         # 查找相似的历史故障

incident list 常用过滤参数：

参数	说明	默认值
`--progress`	进度过滤：`Triggered`、`Processing`、`Closed`	全部
`--severity`	等级过滤：`Critical`、`Warning`、`Info`	全部
`--channel`	按协作空间 ID 过滤	-
`--query`	按标题、标签或内容关键字自由搜索（也可直接输入 24 位故障 ID 或 6 位短编号进行精准查询）	-
`--since`	起始时间（时长、日期、日期时间或 Unix 时间戳）	`24h`
`--until`	截止时间	`now`
`--limit`	最大结果数	`20`
`--page`	页码	`1`

时间格式示例：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）。

flashduty incident work-item-create <incident-id> [flags]        # 创建行动项/跟进项
flashduty incident work-item-list [flags]                        # 列出工作项
flashduty incident work-item-update <work-item-id> [flags]       # 更新标题/描述/状态/优先级
flashduty incident work-item-complete <work-item-id> [flags]     # 标记完成
flashduty incident work-item-convert <work-item-id> [flags]      # 将行动项转为复盘跟进项
flashduty incident work-item-delete <work-item-id> [flags]       # 删除工作项
flashduty incident work-item-assignees-reset <work-item-id>      # 重置负责人列表
flashduty incident work-item-post-mortem-bind [flags]            # 将已转换的跟进项绑定到复盘

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 顶层命令组）：

flashduty incident post-mortem-init <incident-id> [<id2>...]        # 用 1–10 个故障初始化复盘（--template-id 必填）
flashduty incident post-mortem-list [flags]                         # 列出复盘报告（服务端默认只看 published，加 --status drafting 查看草稿）
flashduty incident post-mortem-info <post-mortem-id>                # 查看报告详情
flashduty incident post-mortem-title-reset <post-mortem-id>         # 设置标题
flashduty incident post-mortem-content-reset <post-mortem-id>       # 替换正文 Markdown（--markdown-file）
flashduty incident post-mortem-basics-reset <post-mortem-id>        # 更新起始/关闭时间、最高等级、响应人元数据
flashduty incident post-mortem-follow-ups-reset <post-mortem-id>    # 设置跟进项（--follow-ups）
flashduty incident post-mortem-status-reset <post-mortem-id>        # 发布或退回草稿（--status drafting|published）
flashduty incident post-mortem-delete <post-mortem-id>              # 删除报告（不可逆）

模板命令：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-*）

flashduty incident comment-type-create [flags]                # 创建（--name ≤40 字符且账户内唯一、--color #RRGGBB）
flashduty incident comment-type-list                          # 列出全部评论类型
flashduty incident comment-type-update <comment-type-id>      # 更新名称/颜色
flashduty incident comment-type-delete <comment-type-id>      # 删除
flashduty incident comment-type-reorder <id> [<id2>...]       # 按给定顺序重排（需给出账户内全部类型 ID）

change — 变更记录

flashduty change list [flags]    # 列出变更记录（部署、配置变更等）

支持 --channel、--since、--until、--type、--limit、--page。

member — 成员查询

flashduty member list [flags]       # 列出成员
flashduty member info-reset [flags] # 更新成员资料
flashduty member invite [flags]     # 邀请新成员（单次最多 20 人）

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 — 团队管理

flashduty team list [flags]                          # 列出团队及成员
flashduty team info --team-id <id>                   # 查看单个团队详情
flashduty team upsert --team-name <name> [flags]     # 创建或更新团队（含 --team-id 时为更新）
flashduty team delete --team-id <id>                 # 删除团队（不可逆）

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 — 协作空间查询

flashduty channel list [flags]   # 列出协作空间

支持 --name。

channel escalate-rule-list — 分派策略查询

分派策略现已并入 channel 命令组，通过位置参数传入协作空间 ID：

flashduty 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 六个动作：

flashduty channel silence-rule-list <channel-id>                    # 列出静默规则（channel-id 为位置参数）
flashduty channel silence-rule-create <channel-id> [flags]          # 创建（--rule-name 必填 1–39 字符，时间窗口与过滤条件经 --data 传入）
flashduty channel silence-rule-update --channel-id <id> --rule-id <id>   # 更新
flashduty channel silence-rule-enable --channel-id <id> --rule-id <id>   # 启用
flashduty channel silence-rule-disable --channel-id <id> --rule-id <id>  # 停用
flashduty channel silence-rule-delete --channel-id <id> --rule-id <id>   # 删除

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 — 自定义字段查询

flashduty field list [flags]     # 列出自定义字段定义

支持 --name。

status-page — 状态页管理

flashduty status-page list                                             # 列出状态页
flashduty status-page change-active-list <page-id>                    # 列出活跃的变更事件
flashduty status-page change-create <page-id> [flags]                 # 创建状态页事件
flashduty status-page change-timeline-create [flags]                  # 追加时间线更新

从 Atlassian Statuspage 迁移

迁移任务为异步执行，需通过 migration-status 轮询进度：

# 1. 迁移结构与历史记录
flashduty status-page migrate-structure <source-page-id> \
  --from atlassian \
  --api-key $ATLASSIAN_STATUSPAGE_API_KEY

# 2. 查询迁移进度
flashduty status-page migration-status <job-id>

# 3. 迁移邮件订阅者
flashduty status-page migrate-email-subscribers \
  --from atlassian \
  --source-page-id page_123 \
  --target-page-id <target_page_id> \
  --api-key $ATLASSIAN_STATUSPAGE_API_KEY

# 4. 取消运行中的任务
flashduty status-page migration-cancel <job-id>

其他可用子命令：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 测试，以及创建、更新、删除。

flashduty rum application-info <application-id>            # 查看单个应用详情
flashduty rum application-infos <id1> [<id2>...]          # 批量查看多个应用
flashduty rum application-list [flags]                    # 列出可访问的应用
flashduty rum application-webhook-test <application-id>   # 向指定 Webhook 发送一条测试告警
flashduty rum application-create <team-id> [flags]        # 创建应用
flashduty rum application-update <application-id> [flags] # 更新应用
flashduty rum application-delete <application-id>         # 删除应用

application-list 常用参数：

参数	说明
`--query`	按应用名称搜索
`--team-id`	只看指定团队下的应用
`--is-my-team`	仅返回当前用户所属团队的应用
`--orderby`	排序字段：`created_at`、`updated_at`
`--asc`	是否按升序排列

application-create / application-update 的核心字段：

参数	说明
`--application-name`	应用名称，创建时必填，长度 1–40 字符
`--type`	应用类型：`browser`、`ios`、`android`、`react-native`、`flutter`、`kotlin-multiplatform`、`roku`、`unity`、`miniprogram`、`harmony`、`electron`
`--team-id`	归属团队 ID（创建时必填）
`--is-private`	是否仅允许团队成员访问
`--no-geo`	是否禁用地理位置推断
`--no-ip`	是否禁用 IP 采集
`--data`	可补充 `alerting`（通知配置）和 `tracing`（链路追踪配置）对象

application-webhook-test 会返回 ok、status_code 和 message，可用于验证 RUM 告警 Webhook 是否真正收到了平台发出的测试事件。

会话回放

flashduty rum session-replay-metadata <session-id> # 查看可回放会话的应用、设备、会话边界与 View 元数据
flashduty rum session-replay-segments <session-id> # 读取会话回放分片

session-replay-metadata 的 --ts 可填写会话开始时间的 Unix 毫秒时间戳，用于区分不同时间窗口中复用的会话 ID。 session-replay-segments 常用参数：

参数	说明
`--limit`	单次返回分片数，范围 1–99，默认 20。
`--search-after-ctx`	上一页返回的分页游标；使用 URL 模式时从 `search_after_ctx` 字段取得，流式模式时从 `X-Search-After-Ctx` 响应头取得。
`--ts`	未提供 `--search-after-ctx` 时，从该时间点或之前最近的完整快照分片开始读取。
`--url-mode`	设为 `true` 时返回包含预签名下载 URL 的 JSON；默认 `false`，直接流式返回分片字节。URL 有效期为 1 小时。
`--view-id`	只读取指定 View 的分片；省略时遍历整个会话。

错误摄入规则（error-ingestion-rules-*）

错误摄入规则按过滤条件筛除或改写应用上报的错误事件：

flashduty rum error-ingestion-rules-create <application-id> [flags]       # 创建（--rule-name 必填 1–128 字符，filters 经 --data 传入）
flashduty rum error-ingestion-rules-list <application-id>                 # 列出规则
flashduty rum error-ingestion-rules-update [flags]                        # 更新（--application-id、--rule-id 必填）
flashduty rum error-ingestion-rules-enable [flags]                        # 启用
flashduty rum error-ingestion-rules-disable [flags]                       # 停用
flashduty rum error-ingestion-rules-delete [flags]                        # 删除
flashduty rum error-ingestion-rules-history-list <application-id>         # 查看修改历史（--orderby updated_at|version）
flashduty rum error-ingestion-rules-history-revert <application-id> --version <v>  # 回滚到历史版本

--description 最长 512 字符；create/list/history-list/history-revert 以位置参数接收 application-id，update/enable/disable/delete 通过 --application-id 与 --rule-id 标志指定目标。

预设严重级别规则（issue-preset-severity-rules-*）

预设严重级别规则为匹配条件的错误预设等级，用于 issue 分级：

flashduty rum issue-preset-severity-rules-create <application-id> [flags]  # 创建（--rule-name 必填、--severity Critical|Warning|Info 必填）
flashduty rum issue-preset-severity-rules-list <application-id>            # 列出规则
flashduty rum issue-preset-severity-rules-update [flags]                   # 更新
flashduty rum issue-preset-severity-rules-enable [flags]                   # 启用
flashduty rum issue-preset-severity-rules-disable [flags]                  # 停用
flashduty rum issue-preset-severity-rules-delete [flags]                   # 删除
flashduty rum issue-preset-severity-rules-reorder [flags]                  # 调整优先级（--drag-rule-id、--target-rule-id）
flashduty rum issue-preset-severity-rules-history-list <application-id>    # 修改历史
flashduty rum issue-preset-severity-rules-history-revert <application-id> --version <v>  # 回滚

资源信息（resource-info）

flashduty rum resource-info [--no-cache]   # 查看 RUM 套餐版本、配额与用量（--no-cache 跳过短缓存直接读源）

oncall — On-call 许可证

flashduty oncall license-list # 列出当前账户中持有有效 On-call 许可证的成员

该命令只读，返回成员 ID、名称及许可证类型：fixed 表示固定分配，temporary 表示当前临时许可证窗口内生效。

template — 通知模板

flashduty template get-preset --channel <channel>             # 获取预设模板代码
flashduty template validate --channel <channel> --file <path> # 验证并预览模板渲染结果
flashduty template variables [--category <category>]          # 列出可用模板变量
flashduty template functions [--type custom|sprig|all]        # 列出可用模板函数

支持的通知渠道：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 将单个会话的完整事件流式导出，便于离线分析。

flashduty session list [flags]            # 列出智能体会话（默认按 updated_at 倒序，最新在前）
flashduty session export <session_id>     # 以 NDJSON 流式导出单个会话的完整事件

session list 常用参数：

参数	说明	默认值
`--app`	列出哪个智能体应用的会话	`ai-sre`
`--scope`	可见范围：`all`（自己 + 所属团队，默认）、`personal`、`team`	`all`
`--status`	归档状态：`active`（默认）、`archived`、`all`	`active`
`--team-id`	仅保留指定团队 ID 的会话	-
`--since`	仅保留在该时间窗口内有更新的会话（客户端过滤），如 `30d`、`24h`、`2026-05-01`	-
`--limit`	最多拉取的会话数	`200`
`--page`	起始页码（1 开始）	`1`
`--output-format`	输出格式：`jsonl`（默认，每行一个会话对象，可直接管道给 `jq`）、`json`（完整信封）、`toon`（紧凑编码）	`jsonl`

服务端 /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）。导出内容可能很大，建议重定向到文件而非直接打印到终端：

flashduty session export <session_id> > session.ndjson
flashduty session export <session_id> --include-subagents > session.ndjson

参数	说明
`--include-subagents`	在每条 `subagent_dispatch` 之后递归内联该子智能体自身的完整事件流

monit-agent — 主机/数据库在线诊断

通过 flashmonit 代理对目标主机或数据源执行在线诊断，无需登录目标机器。

flashduty monit-agent catalog --target-locator <host>    # 列出该目标可用的诊断工具
flashduty monit-agent invoke  --target-locator <host> --data '<json>'  # 并发执行最多 8 个诊断工具

catalog 和 invoke 均需要 --target-locator（内网 IP、主机名或数据源名称）。--target-kind 可选（host、mysql、redis 等），不填时由代理自动推断。 invoke 通过 --data 指定要运行的工具列表，最多 8 个并发：

flashduty monit-agent invoke --target-locator '10.0.0.1' \
  --data '{"tools":[{"tool":"os.overview"},{"tool":"os.top_processes","params":{"top_n":10}}]}'

对于包含引号或逗号的 SQL 参数，推荐用 heredoc 通过 stdin 传入（--data -）：

flashduty monit-agent invoke --target-locator 'db-host' --data - <<'FDUTY'
{"tools":[{"tool":"mysql.query","params":{"sql":"SELECT a, b FROM t WHERE s='RUNNING'","max_rows":50}}]}
FDUTY

monit-query — 监控数据源查询

直接探测监控后端数据源，无需经过告警规则层。data 子命令支持 9 种数据源类型（Prometheus、VictoriaLogs、Loki、MySQL、SLS、Elasticsearch、PostgreSQL、Oracle、ClickHouse）；diagnose 支持 prometheus（指标趋势）、victorialogs、loki（日志模式）；已弃用的 rows 支持 prometheus、victorialogs、loki、mysql。

flashduty monit-query diagnose [flags]   # 预聚合 RCA 分析（日志模式或指标趋势）
flashduty monit-query data [flags]       # 结构化数据源查询（推荐）
flashduty monit-query rows [flags]       # 原始数据直通查询（已弃用，请改用 data）

diagnose 常用参数：

参数	说明
`--ds-type`	诊断接口支持的数据源类型（必填）：`prometheus`、`victorialogs`、`loki`
`--ds-name`	数据源名称（必填，与控制台配置一致）
`--input-query`	过滤查询语句或 PromQL（必填）
`--time-start`	窗口起始时间（默认 `15m`）。支持相对时长（`15m`、`1h`）、`now`、日期/RFC3339 时间戳，或 Unix 秒/毫秒时间戳
`--time-end`	窗口截止时间（默认 `now`），格式与 `--time-start` 相同；时间窗口最长 6 小时
`--operation`	`log_patterns`（`loki` / `victorialogs`）或 `metric_trends`（`prometheus`）；省略时根据 `--ds-type` 自动推断

data 常用参数：

参数	说明
`--ds-type`	数据源类型（必填）：`prometheus`、`victorialogs`、`loki`、`mysql`、`sls`、`elasticsearch`、`postgres`、`oracle`、`clickhouse`
`--ds-name`	数据源名称（必填，与控制台配置一致）
`--expr`	查询表达式（必填）
`--delay-seconds`	查询时间点的回溯偏移秒数，用于点对点查询（默认 `0`）
`--args KEY=VALUE`	附加参数，可重复（值须为字符串）。`loki` / `victorialogs` 原始模式下，`<ds-type>.start` 与 `<ds-type>.end` 接受相对时长（`15m`）、`now`、日期/RFC3339 时间戳或 Unix 秒/毫秒，CLI 会统一归一化为数据源要求的 Unix 秒

data 返回稳定的 query_result.v1 结构化结果：format 固定为 query_result.v1，result.kind 为 frames（类型化表格/时序帧）、records（字段灵活的记录，可含嵌套 JSON 或 null）或 samples（带完整标签集的即时样本）三者之一，不再把结果强制压平为旧版行结构。 rows 常用参数：--ds-type、--ds-name（均必填）、--expr（查询表达式，必填）、--args KEY=VALUE（可重复）。rows 已弃用，请改用 monit-query data。rows 原始模式（loki / victorialogs）可通过 --args <ds-type>.start=<t> 与 --args <ds-type>.end=<t> 指定时间窗口，取值格式与 diagnose 的 --time-start/--time-end 相同（相对时长、now、日期/RFC3339、Unix 秒或毫秒），CLI 会统一归一化为数据源要求的 Unix 秒。

monit — 监控规则表达式预览

如果你想在保存规则前直接验证某条数据源表达式，可以使用 preview-sync 走一条同步预览请求，拿到原始结果。

flashduty monit preview-sync [flags]

常用参数：

参数	说明
`--ds-name`	数据源显示名（必填，需与控制台配置一致）
`--ds-type`	数据源类型（必填），如 `prometheus`、`loki`、`elasticsearch`
`--expr`	预览查询表达式（必填）
`--delay-seconds`	将查询窗口整体向前平移若干秒，用于补偿采集延迟
`--data`	可补充 `args` 等数据源特定参数

monit servicemap — 服务拓扑（Beta）

monit servicemap-* 命令族访问服务拓扑（ServiceMap）能力，页面操作见服务拓扑。

flashduty monit servicemap-fleet [flags]             # 浏览采集主机清单（--statuses/--agent-versions/--capture-modes/--edge-clusters 过滤）
flashduty monit servicemap-fleet-summary [flags]     # 主机清单汇总
flashduty monit servicemap-status [flags]            # 查询主机采集状态（--host-id/--host-ids，或 --fleet 抽样）
flashduty monit servicemap-summary --data '<json>'   # 指定锚点主机查看拓扑摘要
flashduty monit servicemap-topology --data '<json>' [flags]  # 查询拓扑（--depth 1–3，默认 1）

summary 与 topology 的锚点主机经 --data '{"anchor":{...}}' 传入；topology 常用 --depth（遍历深度，1–3，默认 1）、--max-nodes（默认 100，上限 500）、--max-edges（默认 200，上限 1000）。

alert — 告警与告警事件查询

flashduty alert list [flags]        # 列出告警（默认最近 24 小时）
flashduty alert get <alert_id>      # 查看单条告警详情；detail 是同一命令的别名
flashduty alert-event list [flags]  # 列出告警事件（默认最近 1 小时）

两个 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 的自动化规则——创建、查询、更新、删除、运行历史与触发，页面操作见自动化。

flashduty automation create [flags]               # 创建规则
flashduty automation list [flags]                 # 列出调用者可见的规则
flashduty automation get <rule_id>                # 查看单条规则
flashduty automation update <rule_id> [flags]     # 更新规则的可变字段
flashduty automation delete <rule_id> [flags]     # 删除规则（交互终端二次确认，--force 跳过）
flashduty automation runs <rule_id> [flags]       # 列出规则的运行历史
flashduty automation templates [--locale zh-CN]   # 列出预设模板
flashduty automation fire <trigger_id>            # 经 HTTP POST 触发器触发一次运行

create 常用参数：

参数	说明
`--name`	规则名称（必填）
`--team-id`	归属团队 ID；`0` 表示个人范围（默认）。作用域创建后不可变更
`--schedule`	节奏辅助：`hourly`、`daily`、`weekly` 或 `cron`；省略时默认 `daily`
`--at`	`HH:MM` 本地时间（按规则时区）；`hourly` 只取分钟（默认 0 分），`daily`/`weekly` 取小时与分钟（默认 09:00）
`--weekday`	`weekly` 的星期：`sun`–`sat` 或 `0`–`7`（`0` 与 `7` 均表示周日，默认周一）
`--cron-expr`	精确的 5 段 cron 表达式（按规则时区解释），优先级高于 `--schedule` 辅助参数
`--disabled`	以停用状态创建（默认启用）
`--schedule-enabled`	是否启用周期触发器（默认 `true`）
`--http-post-trigger`	创建并启用 HTTP POST 触发器；只传它且不带任何周期参数时，CLI 会写入占位 cron 并自动停用周期触发器
`--prompt` / `--prompt-file`	任务提示词，二选一必填；`--prompt-file` 从文件读取（`-` 表示 stdin）
`--environment-kind` / `--environment-id`	运行环境：`cloud` 或 `byoc`（`byoc` 需配合 `--environment-id`）；留空表示自动

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）。

时区语义：--at 与 --cron-expr 均按规则时区的本地挂钟时间理解——规则时区在创建时默认为调用者的成员时区，成员未设置时回退到账户时区。请直接传用户的本地时间，不要预先换算成 UTC。CLI 的 create / update 都没有 --timezone 参数：创建时如需固定其它时区，请改用生成命令 flashduty safari automation-rule-create --timezone；已创建规则的时区在 update 中不可更改。

全量命令覆盖

除上述精选命令外，CLI 现已通过 spec 驱动的代码生成实现对 Flashduty OpenAPI 的全量覆盖。当前 OpenAPI 含 337 个 API 操作，CLI 为其中 336 个操作生成对应命令（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、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 逐层探索：

flashduty --help                 # 查看全部顶层命令组
flashduty safari --help          # 查看 AI SRE 相关的生成命令
flashduty alert --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 结构、@引用、账户/团队作用域、文件约束）参见管理知识。

flashduty safari knowledge-get                                  # 获取当前账户知识包（含文件列表）
flashduty safari knowledge-pack-list [flags]                    # 列出知识包
flashduty safari knowledge-pack-ensure --scope <account|team> [--scope-id <team-id>]  # 确保知识包存在（不存在则创建）
flashduty safari knowledge-pack-update <pack-id> [--scope ...]  # 变更知识包作用域
flashduty safari knowledge-pack-delete <pack-id>                # 删除知识包（不可逆）
flashduty safari knowledge-file-list [--pack-id <id>]           # 列出知识包内的文件
flashduty safari knowledge-file-get --rel-path <path>           # 读取单个知识文件（内容为 Base64 编码）
flashduty safari knowledge-file-put --rel-path <path> --content-b64 <base64>  # 上传或覆盖知识文件
flashduty safari knowledge-file-delete --rel-path <path> [--force]  # 删除知识文件

常用参数：

参数	说明
`--pack-id`	知识包 ID；省略时默认使用调用者账户作用域的知识包
`--rel-path`	文件相对知识包根目录的路径（必填，支持子目录，如 `runbooks/api-5xx.md`）
`--scope`	知识包作用域：`account` 或 `team`（`knowledge-pack-ensure` 必填）
`--scope-id`	团队 ID；`team` 作用域必填，`account` 作用域忽略
`--force`	删除文件时跳过「仍被其他文件引用」检查，引用方改为以警告形式返回

knowledge-file-put 的 --content-b64 必须是合法 UTF-8 文本的 Base64 编码，--content-type 省略时按文件扩展名推断。knowledge-file-delete 默认在文件仍被其他知识文件引用时阻止删除；加 --force 可强制执行，此时引用方会以警告形式返回。

工具命令

flashduty login          # 交互式登录
flashduty config show    # 查看当前配置
flashduty config set     # 设置配置项
flashduty version        # 打印版本信息
flashduty whoami         # 显示当前认证身份（账号 ID、邮箱、角色等）
flashduty update         # 更新到最新版本
flashduty update --check # 仅检查是否有新版本，不安装
flashduty completion     # 生成 Shell 自动补全（bash/zsh/fish/powershell）

flashduty update 会下载并执行平台安装脚本，将当前二进制替换为最新版本。--check 仅打印可用版本号，不修改本地文件。在终端中执行其他命令后，若检测到有新版本可用，CLI 会在 stderr 自动输出更新提示横幅。

启用 Shell 自动补全示例（zsh）：

flashduty completion zsh > "${fpath[1]}/_flashduty"

输出格式

通过 --output-format 选择输出形态（--json 是 --output-format json 的别名），便于在不同场景下消费：

表格（默认）
JSON（--json / --output-format json）
TOON（--output-format toon）
完整表格（--no-trunc）

人类可读，列对齐，长字段截断显示。

ID           TITLE                    SEVERITY   PROGRESS     CHANNEL       CREATED
inc_abc123   DB connection timeout    Critical   Triggered    Production    2026-04-10 10:23
inc_def456   High memory usage        Warning    Processing   Staging       2026-04-10 09:15
Showing 2 results (page 1, total 2).

机器可解析。除下方列出的默认紧凑字段命令外，返回命令的完整响应数据；表格列截断不适用于 JSON。适合脚本、CI/CD 流水线消费。

flashduty incident list --json | jq '.[].title'

TOON（Token-Oriented Object Notation）对同构数组省去了 JSON 中每行重复的字段名，列表输出可显著减少 token 消耗，更适合喂给 AI / 智能体消费。下方列出的默认紧凑字段命令会按其字段投影输出，并受大小限制。

flashduty incident list --output-format toon

TOON 不能直接用 jq 解析；需要管道给 jq 时请改用 --json。

结构化输出的字段投影

以下命令在 json 或 toon 输出时支持 --fields。用逗号分隔顶层响应字段；未知字段会直接报错，表格输出会忽略此参数。

命令	未指定 `--fields` 时的结构化输出	上限
`flashduty incident list`	`incident_id`、`title`、`incident_severity`、`progress`、`start_time`、`channel_id`	16 KiB
`flashduty incident similar <id>`	`incident_id`、`title`、`incident_severity`、`progress`、`start_time`、`close_time`、`ack_time`、`alert_cnt`、`root_cause`、`score`	16 KiB
`flashduty incident detail <id>`	不指定 `--fields` 时返回完整详情；指定后只返回所选字段	仅投影输出为 8 KiB
`flashduty alert-event list`	`event_id`、`alert_id`、`event_severity`、`event_status`、`event_time`、`title`	16 KiB

例如，只导出故障编号、标题和处理进度：

flashduty incident list --json --fields incident_id,title,progress

列表投影（incident list、incident similar、alert-event list）超过上限时，CLI 会在保留字段名的前提下截短过长的字符串，并以 ... 标记；若非字符串字段本身已超过上限，命令会提示减少字段或结果数。 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。一键安装到当前机器上检测到的所有代理：

npx skills add flashcatcloud/flashduty-cli -y -g

技能采用「路由 + 参考卡」结构：SKILL.md 承载认证、全局参数、安全规则等共享约定，并按领域索引参考卡——故障、告警、变更、值班与排班、协作空间与分派、状态页、洞察、监控、RUM 与 sourcemap、自动化、通知模板、成员与团队等。代理执行任务前先读取对应领域的参考卡，即可获得该领域的全部命令、参数与工作流，无需 --help 试探。

常见用法

在告警通知中追加 CLI 链接

通过 flashduty incident get <id> 在终端中快速查看故障详情，可将命令片段嵌入到通知模板里供值班同学一键复制。

批量认领或关闭故障

flashduty incident ack inc_001 inc_002 inc_003
flashduty incident close inc_001 inc_002 inc_003

将故障数据导出到 BI 工具

flashduty incident list --since 168h --limit 500 --json > incidents.json

然后通过 jq 处理或导入数据仓库。

在 CI/CD 中验证通知模板

flashduty template validate --channel feishu --file templates/feishu.yaml

将上述命令加入 CI，可在模板提交时立即捕获语法或字段错误。

完整源码和问题反馈请访问 GitHub 仓库。

​概述

​安装

​安装选项

​认证

​登录

​凭证解析顺序

​配置文件

​配置命令

​全局参数

​命令清单

​incident — 故障生命周期

​工作项与跟进项（work-item-*）

​复盘报告（post-mortem-*）

​评论类型（comment-type-*）

​change — 变更记录

​member — 成员查询

​team — 团队管理

​channel — 协作空间查询

​channel escalate-rule-list — 分派策略查询

​channel 静默/抑制/丢弃规则 — 降噪规则管理

​field — 自定义字段查询

​status-page — 状态页管理

​从 Atlassian Statuspage 迁移

​rum — RUM 应用与会话回放

​会话回放

​错误摄入规则（error-ingestion-rules-*）

​预设严重级别规则（issue-preset-severity-rules-*）

​资源信息（resource-info）

​oncall — On-call 许可证

​template — 通知模板

​session — AI SRE 会话

​monit-agent — 主机/数据库在线诊断

​monit-query — 监控数据源查询

​monit — 监控规则表达式预览

​monit servicemap — 服务拓扑（Beta）

​alert — 告警与告警事件查询

​automation — AI SRE 自动化规则

​全量命令覆盖

​knowledge — AI SRE 知识库

​工具命令

​输出格式

​结构化输出的字段投影

​Agent Skills

​常见用法

概述

安装

安装选项

认证

登录

凭证解析顺序

配置文件

配置命令

全局参数

命令清单

incident — 故障生命周期

工作项与跟进项（work-item-*）

复盘报告（post-mortem-*）

评论类型（comment-type-*）

change — 变更记录

member — 成员查询

team — 团队管理

channel — 协作空间查询

channel escalate-rule-list — 分派策略查询

channel 静默/抑制/丢弃规则 — 降噪规则管理

field — 自定义字段查询

status-page — 状态页管理

从 Atlassian Statuspage 迁移

rum — RUM 应用与会话回放

会话回放

错误摄入规则（error-ingestion-rules-*）

预设严重级别规则（issue-preset-severity-rules-*）

资源信息（resource-info）

oncall — On-call 许可证

template — 通知模板

session — AI SRE 会话

monit-agent — 主机/数据库在线诊断

monit-query — 监控数据源查询

monit — 监控规则表达式预览

monit servicemap — 服务拓扑（Beta）

alert — 告警与告警事件查询

automation — AI SRE 自动化规则

全量命令覆盖

knowledge — AI SRE 知识库

工具命令

输出格式

结构化输出的字段投影

Agent Skills

常见用法