agent-incident 是面向 incident.io 的分诊与响应命令行工具，用于查询和管理事件、告警、值班排班、升级路径与状态页，属于事件响应工作流，而非完整的 incident.io 后台管理。
主要能力包括：查看当前活动事件（incident list --status active）与正在触发的告警（alert list --status firing）；获取指定事件详情（incident get INC-2000，支持多个 ID）；查询值班人员（oncall schedule entries Engineering --from now --to now+1h）；创建升级（oncall escalation create --incident <id> --path "Primary Path"）；更新状态页（status-page update create --page "Public Status" --name "..."）；以及编辑事件字段如严重级别、状态、自定义字段和时间戳。创建事件可用 ref severity list 查找有效严重级别。
输出默认为 NDJSON（列表和 get 每条 ID 一行），--full 返回完整 API 响应，--format json|yaml|jsonl 可覆盖格式。时间支持相对格式（now-15m、now+1h）、RFC3339 或 Unix 时间戳。排班、升级路径、状态页、用户、严重级别等参数支持名称（不区分大小写、子串匹配），若像 ULID 则直接使用。分页用 --limit 和 --after <cursor>。
认证方式：推荐交互式 --form（agent-incident auth add prod --form），密钥不经过命令行；非交互环境可用 printf '%s' "$KEY" | agent-incident auth add prod 从 stdin 传入；也支持环境变量 INCIDENT_API_KEY。多组织可用 --org 指定别名。
限制：仅用于分诊与响应工作流，不覆盖完整的 incident.io 管理；API 密钥需在 incident.io 设置页获取。错误为 JSON 输出到 stderr，并标注 fixable_by（agent、human、retry）。