命令行工具 - 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）

认证

凭证解析顺序

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 过滤	-
`--title`	按标题关键字搜索	-
`--since`	起始时间（时长、日期、日期时间或 Unix 时间戳）	`24h`
`--until`	截止时间	`now`
`--limit`	最大结果数	`20`
`--page`	页码	`1`

时间格式示例：5m、1h、24h、168h、2026-04-01、2026-04-01 10:00:00、1712000000。

change — 变更记录

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

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

member — 成员查询

flashduty member list [flags]    # 列出成员

支持 --name、--email、--page。

team — 团队查询

flashduty team list [flags]      # 列出团队及成员

支持 --name、--page。

channel — 协作空间查询

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

支持 --name。

escalation-rule — 分派策略查询

flashduty escalation-rule list --channel <id>          # 按协作空间 ID 查询
flashduty escalation-rule list --channel-name <name>   # 按协作空间名称查询（自动解析）

field — 自定义字段查询

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

支持 --name。

statuspage — 状态页管理

flashduty statuspage list [--id <ids>]                                   # 列出状态页
flashduty statuspage changes --page-id <id> --type <incident|maintenance> # 列出活跃的变更
flashduty statuspage create-incident --page-id <id> --title <title>      # 创建状态页事件
flashduty statuspage create-timeline --page-id <id> --change <id> --message <msg>  # 追加时间线更新

从 Atlassian Statuspage 迁移

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

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

# 2. 查询迁移进度
flashduty statuspage migrate status --job-id <job_id>

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

# 4. 取消运行中的任务
flashduty statuspage migrate cancel --job-id <job_id>

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`
`--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` 之后递归内联该子智能体自身的完整事件流

全量命令覆盖

除上述精选命令外，CLI 现已通过 spec 驱动的代码生成实现对 Flashduty OpenAPI 的「全量覆盖」（约 248 条命令），并按资源组织为顶层命令组。除 On-call 域（incident、change、channel、escalation-rule、field、statuspage、template 等）外，还覆盖了：

AI SRE（safari）：a2a-agents、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           # 查看告警相关的生成命令

工具命令

flashduty login          # 交互式登录
flashduty config show    # 查看当前配置
flashduty config set     # 设置配置项
flashduty version        # 打印版本信息
flashduty completion     # 生成 Shell 自动补全（bash/zsh/fish/powershell）

启用 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).

机器可解析，完整数据，不截断。适合脚本、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。

Agent Skills

Flashduty CLI 内置 10 个 Agent Skills，可让 Claude Code、Cursor、Codex、Gemini CLI、Windsurf 等 AI 编程代理通过 CLI 操作 Flashduty。一键安装到当前机器上检测到的所有代理：

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

可用技能列表：

技能	覆盖范围
`flashduty-shared`	基础：认证、三层降噪模型、全局参数、安全规则
`flashduty-incident`	故障生命周期：分诊、调查、解决、合并、暂停、转派
`flashduty-alert`	告警与告警事件调查：下钻、追踪、合并
`flashduty-change`	变更事件追踪与部署频率趋势
`flashduty-oncall`	值班查询：当前值班人、排班详情
`flashduty-channel`	协作空间与分派策略查询
`flashduty-statuspage`	状态页管理以及从 Atlassian 迁移到 Flashduty
`flashduty-insight`	分析：MTTA/MTTR、降噪率、通知趋势
`flashduty-admin`	团队/成员查询与审计日志搜索
`flashduty-template`	通知模板验证与预览

常见用法

在告警通知中追加 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 — 故障生命周期

​change — 变更记录

​member — 成员查询

​team — 团队查询

​channel — 协作空间查询

​escalation-rule — 分派策略查询

​field — 自定义字段查询

​statuspage — 状态页管理

​从 Atlassian Statuspage 迁移

​template — 通知模板

​session — AI SRE 会话

​全量命令覆盖

​工具命令

​输出格式

​Agent Skills

​常见用法

概述

安装

安装选项

认证

登录

凭证解析顺序

配置文件

配置命令

全局参数

命令清单

incident — 故障生命周期

change — 变更记录

member — 成员查询

team — 团队查询

channel — 协作空间查询

escalation-rule — 分派策略查询

field — 自定义字段查询

statuspage — 状态页管理

从 Atlassian Statuspage 迁移

template — 通知模板

session — AI SRE 会话

全量命令覆盖

工具命令

输出格式

Agent Skills

常见用法