命令行工具

使用 Flashduty CLI 在终端中管理故障、值班、状态页和通知模板

​

概述

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

工具开源在 flashcatcloud/flashduty-cli，支持 macOS、Linux 和 Windows。

​

安装

macOS / Linux

curl -sSL https://raw.githubusercontent.com/flashcatcloud/flashduty-cli/main/install.sh | sh

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

Windows (PowerShell)

irm https://raw.githubusercontent.com/flashcatcloud/flashduty-cli/main/install.ps1 | iex

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

手动下载

访问 GitHub Releases 下载对应平台的二进制包，解压后放入 PATH 即可。

​

安装选项

环境变量	说明	默认值
FLASHDUTY_VERSION	安装指定版本，如 v0.6.0	最新版本
FLASHDUTY_INSTALL_DIR	安装目录	/usr/local/bin（Shell）、~\.flashduty\bin（PowerShell）

​

认证

​

登录

flashduty login

按提示输入 APP Key。获取方式：登录 Flashduty 控制台，进入 个人中心 > 个人信息，复制 APP Key。

​

凭证解析顺序

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

1. --app-key 命令行参数（脚本场景使用）
2. FLASHDUTY_APP_KEY 环境变量
3. 配置文件 ~/.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 地址

​

全局参数

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

参数	说明
--json	以 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。

​

工具命令

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"

​

输出格式

CLI 提供三种输出形态，便于在不同场景下消费：

表格（默认）

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

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（--json）

机器可解析，完整数据，不截断。适合脚本、CI/CD 流水线消费。

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

完整表格（--no-trunc）

表格视图但不截断长字段，便于复制粘贴或终端宽度较大的场景。

​

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，可在模板提交时立即捕获语法或字段错误。

完整源码、Release 列表和问题反馈请访问 GitHub 仓库。