OneUptime CLI 完全指南终端管理监控、事件与告警资源的实战手册【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptimeOneUptime CLIoneuptime/cli是 OneUptime 官方提供的命令行接口让你无需打开 Web 控制台即可在终端中完成监控、事件Incident、告警Alert、状态页Status Page、值班策略等资源的全套 CRUD 操作。本文以 CLI 官方文档为主线结合仓库内 CLI 源码 与单元测试系统讲解安装、认证上下文、资源操作、输出格式、CI/CD 脚本化等完整能力读完即可把 OneUptime 资源管理完全接入你的终端工作流与自动化管线。一、CLI 是什么核心能力一览OneUptime CLI 是一款专为终端与自动化场景设计的资源管理工具其核心特性包括多环境支持通过命名上下文named contexts区分生产、预发staging、开发等不同实例一键切换。资源自动发现CLI 会自动检测当前 OneUptime 实例上可用的资源类型所有开启了 MCP 能力的模型都会自动暴露为 CLI 资源无需手工配置。灵活认证支持通过命令行参数、环境变量、已保存的上下文三种途径提供凭据并可自由混用。智能输出格式提供 JSON、table、wide 三种输出模式交互终端默认表格管道场景自动切 JSON。脚本友好设计了明确的退出码与 JSON 输出专为 CI/CD 流水线而生。从源码结构看CLI 是一个基于 TypeScript 与commander框架构建的独立子项目位于仓库 CLI 目录 下由命令注册层Commands、核心层Core与类型定义Types/CLITypes.ts组成。二、安装与快速开始2.1 全局安装npm install -g oneuptime/cli安装后即可在任意终端使用oneuptime命令。如果身处本仓库开发环境也可以在 CLI 目录 内直接以开发模式运行cd CLI npm install npm start -- --help # 通过 ts-node 运行2.2 快速上手# 使用 API Key 认证并登录你的 OneUptime 实例 oneuptime login your-api-key https://oneuptime.com # 列出你的监控项 oneuptime monitor list # 查看某个具体的事件 oneuptime incident get incident-id # 查看实例上所有可用资源类型 oneuptime resources四条命令即可完成认证 → 发现资源 → 查询数据的完整闭环。三、认证、上下文与凭据解析3.1 登录oneuptime login认证的核心命令是login通过 API Key 与实例地址建立会话oneuptime login api-key instance-url参数说明参数说明api-keyOneUptime API Key形如sk-your-api-keyinstance-urlOneUptime 实例地址如https://oneuptime.com--context-name name为该登录会话命名的上下文默认default典型示例# 使用默认上下文登录 oneuptime login sk-abc123 https://oneuptime.com # 以 production 命名上下文登录 oneuptime login sk-abc123 https://oneuptime.com --context-name production # 同时配置多个环境 oneuptime login sk-prod-key https://oneuptime.com --context-name production oneuptime login sk-staging-key https://staging.oneuptime.com --context-name staging从 ConfigCommands.ts 的源码可以看到login的实现细节命令用commander定义了两个必填位置参数api-key与instance-url以及默认值为default的--context-name选项在动作函数中实例地址会先经过instanceUrl.replace(/\/$/, )去除末尾斜杠再封装成CLIContext写入配置并自动将该上下文设为当前激活状态。3.2 上下文管理oneuptime context上下文context用于保存多套环境凭据方便在生产、预发、开发之间快速切换。命令说明oneuptime context list列出所有已配置的上下文当前上下文以*标记oneuptime context use name切换到指定命名上下文影响之后所有命令oneuptime context current显示当前激活的上下文含实例 URL 与脱敏后的 API Keyoneuptime context delete name删除指定上下文若删除的是当前上下文CLI 自动切换到剩余的第一个上下文# 切换到 staging oneuptime context use staging # 切换到 production oneuptime context use production # 查看当前上下文 oneuptime context current3.3 凭据解析优先级CLI 按以下顺序解析凭据高优先级覆盖低优先级CLI 参数--api-key与--url环境变量ONEUPTIME_API_KEY与ONEUPTIME_URL具名上下文通过--context name显式指定的上下文当前上下文配置文件~/.oneuptime/config.json中保存的当前激活上下文不同来源可以自由混用例如用环境变量提供 API Key、同时用已保存的上下文提供实例 URL# 方式一全部用 CLI 参数 oneuptime --api-key sk-abc123 --url https://oneuptime.com incident list # 方式二全部用环境变量 export ONEUPTIME_API_KEYsk-abc123 export ONEUPTIME_URLhttps://oneuptime.com oneuptime incident list # 方式三指定某个具名上下文 oneuptime --context production incident list3.4 验证认证状态oneuptime whoamioneuptime whoami输出内容包括实例 URL、脱敏后的 API Key、当前上下文名称仅当存在已保存的激活上下文时显示。若未认证命令会给出友好提示并建议执行oneuptime login。3.5 配置文件与安全性所有凭据保存在~/.oneuptime/config.json文件权限被限制为0600仅当前用户可读写。典型结构如下{ currentContext: production, contexts: { production: { name: production, apiUrl: https://oneuptime.com, apiKey: sk-... }, staging: { name: staging, apiUrl: https://staging.oneuptime.com, apiKey: sk-... } }, defaults: { output: table, limit: 10 } }配置中除了上下文列表还包含defaults段用于记录默认输出格式与默认分页大小对应-o与--limit的缺省值。该文件由 ConfigManager.ts 负责读写上下文增删、当前上下文切换等操作在 ConfigCommands.ts 中均有对应实现并有 ConfigManager.test.ts 与 ConfigCommands.test.ts 覆盖。四、资源自动发现与 CRUD 操作4.1 资源发现oneuptime resourcesOneUptime 实例上所有启用了 MCP 能力的模型都会被 CLI 自动识别为可用资源# 查看全部资源类型 oneuptime resources # 只查看数据库类资源 oneuptime resources --type database # 只查看分析类资源 oneuptime resources --type analytics常见资源与对应命令资源命令事件Incidentoneuptime incident告警Alertoneuptime alert监控项Monitoroneuptime monitor监控状态Monitor Statusoneuptime monitor-status事件状态Incident Stateoneuptime incident-state状态页Status Pageoneuptime status-page值班策略On-Call Policyoneuptime on-call-policy团队Teamoneuptime team计划维护事件oneuptime scheduled-maintenance-event资源会随 OneUptime 侧 MCP 能力的开放而自动扩展无需升级 CLI。资源命令的实际注册逻辑位于 ResourceCommands.ts配合 SelectFieldGenerator.ts 动态生成字段提示。4.2 列表oneuptime resource listoneuptime resource list [options]选项说明默认值--query jsonJSON 格式的过滤条件无--limit n最大返回条数10--skip n跳过的条数分页0--sort jsonJSON 格式排序规则无-o, --output format输出格式table# 列出最近 10 个事件 oneuptime incident list # 按事件状态 ID 过滤 oneuptime incident list --query {currentIncidentStateId:state-id} # 分页跳过前 40 条取 20 条 oneuptime incident list --limit 20 --skip 40 # 按创建时间倒序 oneuptime incident list --sort {createdAt:-1} # JSON 输出 oneuptime incident list -o json4.3 查询单个资源oneuptime resource getoneuptime resource get idid为资源 UUID。例如# 获取指定事件 oneuptime incident get 550e8400-e29b-41d4-a716-446655440000 # 以 JSON 格式获取监控项 oneuptime monitor get abc-123 -o json4.4 创建资源oneuptime resource create数据可来自内联 JSON 或本地文件--data与--file二选一oneuptime resource create [options]选项说明--data json资源数据JSON 对象--file path包含资源数据的 JSON 文件路径-o, --output format输出格式# 内联 JSON 创建事件 oneuptime incident create --data {title:API Outage,currentIncidentStateId:state-id,incidentSeverityId:severity-id,declaredAt:2025-01-15T10:30:00Z} # 从 JSON 文件创建 oneuptime incident create --file incident.json # 创建监控项并以 JSON 输出以捕获新 ID oneuptime monitor create --data {name:API Health Check} -o json4.5 更新资源oneuptime resource updateoneuptime resource update id --data json [-o format]--data为必填用于指定要更新的字段# 将事件状态变更为已解决 oneuptime incident update abc-123 --data {currentIncidentStateId:resolved-state-id} # 重命名监控项 oneuptime monitor update abc-123 --data {name:Updated Monitor Name}4.6 删除资源oneuptime resource deleteoneuptime resource delete id [--force]删除默认会二次确认--force可跳过确认提示oneuptime incident delete abc-123 oneuptime monitor delete 550e8400-e29b-41d4-a716-446655440000 oneuptime monitor delete 550e8400-e29b-41d4-a716-446655440000 --force4.7 统计数量oneuptime resource countoneuptime resource count [--query json]# 统计所有事件 oneuptime incident count # 按状态统计事件 oneuptime incident count --query {currentIncidentStateId:state-id} # 统计监控项 oneuptime monitor count4.8 分析类资源的操作限制分析类资源Analytics支持的操作集比数据库类资源更小操作是否支持list是create是count是get否update否delete否可用oneuptime resources --type analytics查看当前实例暴露了哪些分析类资源。五、输出格式详解5.1 table默认格式交互终端下的默认输出展示为 ASCII 表格并智能选择列oneuptime incident list┌──────────────────┬───────────────────────┬─────────────────────┬─────────────────────┐ │ _id │ title │ createdAt │ updatedAt │ ├──────────────────┼───────────────────────┼─────────────────────┼─────────────────────┤ │ abc-123 │ API Outage │ 2025-01-15T10:30:00 │ 2025-01-15T12:00:00 │ │ def-456 │ Database Slowdown │ 2025-01-14T08:15:00 │ 2025-01-14T09:30:00 │ └──────────────────┴───────────────────────┴─────────────────────┴─────────────────────┘表格格式行为规则最多展示 6 列列优先级为_id、name、title、createdAt、updatedAt超过 60 字符的值截断并以...结尾表头带颜色编码可用--no-color关闭。5.2 JSON输出原始 JSON缩进为 2 个空格最适合脚本化处理oneuptime incident list -o json[ { _id: abc-123, title: API Outage, currentIncidentStateId: 550e8400-e29b-41d4-a716-446655440000, createdAt: 2025-01-15T10:30:00Z } ]关键行为当输出被重定向到其他命令非 TTY 模式时CLI 会自动切换为 JSON 格式oneuptime incident list | jq .[].title5.3 wide展示全部列且不截断适合详细检查但可能产生超宽输出oneuptime incident list -o wide5.4 禁用颜色# 使用 --no-color 参数 oneuptime --no-color incident list # 使用 NO_COLOR 环境变量 NO_COLOR1 oneuptime incident list5.5 特殊场景输出场景输出空结果集No results found.未返回数据No data returned.单对象如get键值对形式的表格count命令纯数字输出相关的实现集中在 OutputFormatter.ts其行为由 OutputFormatter.test.ts 验证。六、Scripting 与 CI/CD 自动化6.1 环境变量认证适合在无交互的流水线环境中使用无需保存上下文export ONEUPTIME_API_KEYsk-your-api-key export ONEUPTIME_URLhttps://oneuptime.com环境变量的优先级高于已保存的上下文但低于 CLI 参数。CLI 支持的完整环境变量清单见 READMEONEUPTIME_API_KEYAPI Key、ONEUPTIME_URL实例地址、NO_COLOR禁用彩色输出。6.2 退出码约定退出码含义0成功1一般错误2认证错误凭据缺失或无效3未找到404在脚本中可直接依赖退出码做错误处理if ! oneuptime monitor list /dev/null 21; then echo Failed to list monitors exit 1 fi退出码的映射逻辑由 ErrorHandler.ts 实现并被 ErrorHandler.test.ts 覆盖。6.3 结合 jq 的 JSON 处理# 提取所有事件标题 oneuptime incident list -o json | jq .[].title # 捕获新建监控项的 ID NEW_ID$(oneuptime monitor create --data {name:API Health} -o json | jq -r ._id) echo Created monitor: $NEW_ID # 按严重度统计事件 oneuptime incident count --query {incidentSeverityId:severity-id}6.4 从文件创建资源--file适合配合基础设施即代码Infrastructure as Code场景把资源定义纳入版本管理# monitor.json # { # name: API Health Check, # projectId: your-project-id # } oneuptime monitor create --file monitor.json6.5 批量操作处理大量资源时可用循环批量执行# 从 JSON 数组文件批量创建监控项 cat monitors.json | jq -r .[] | json | while read monitor; do oneuptime monitor create --data $monitor done6.6 CI/CD 流水线示例GitHub Actions定时检查活跃事件name: Check Active Incidents on: schedule: - cron: */5 * * * * jobs: health-check: runs-on: ubuntu-latest steps: - name: Install OneUptime CLI run: npm install -g oneuptime/cli - name: Check for active incidents env: ONEUPTIME_API_KEY: ${{ secrets.ONEUPTIME_API_KEY }} ONEUPTIME_URL: https://oneuptime.com run: | INCIDENT_COUNT$(oneuptime incident count) if [ $INCIDENT_COUNT -gt 0 ]; then echo WARNING: $INCIDENT_COUNT incidents found exit 1 fi通用 CI 脚本部署前后自动创建并关闭事件#!/bin/bash set -e export ONEUPTIME_API_KEY$CI_ONEUPTIME_API_KEY export ONEUPTIME_URL$CI_ONEUPTIME_URL # 创建部署事件并捕获 ID # 注意currentIncidentStateId 与 incidentSeverityId 必须引用项目中已存在的状态/严重度 ID INCIDENT_ID$(oneuptime incident create --data { title: Deployment Started, currentIncidentStateId: $INVESTIGATING_STATE_ID, incidentSeverityId: $SEVERITY_ID, declaredAt: $(date -u %Y-%m-%dT%H:%M:%SZ) } -o json | jq -r ._id) # 在此执行部署步骤... # 部署成功后关闭事件 oneuptime incident update $INCIDENT_ID --data {currentIncidentStateId:$RESOLVED_STATE_ID}Docker封装 CLI 为容器镜像FROM node:26-slim RUN npm install -g oneuptime/cli ENV ONEUPTIME_API_KEY ENV ONEUPTIME_URL ENTRYPOINT [oneuptime]docker run --rm \ -e ONEUPTIME_API_KEYsk-abc123 \ -e ONEUPTIME_URLhttps://oneuptime.com \ oneuptime-cli incident list6.7 脚本中指定上下文配置了多个上下文时可在脚本中精确指定目标环境oneuptime --context production incident list oneuptime --context staging monitor count七、命令速查与 API 端点映射7.1 认证命令命令说明oneuptime login api-key instance-url [--context-name name]认证并创建上下文oneuptime context list列出所有上下文oneuptime context use name切换当前上下文oneuptime context current显示当前上下文oneuptime context delete name删除上下文oneuptime whoami显示当前认证信息7.2 资源命令通用模式所有资源命令遵循同一模式将resource替换为任意已支持资源名如incident、monitor、alert、status-page命令说明oneuptime resource list [options]带过滤与分页的列表oneuptime resource get id按 ID 查询单个资源oneuptime resource create [--data json \| --file path]创建资源oneuptime resource update id --data json更新资源oneuptime resource delete id [--force]删除资源oneuptime resource count [--query json]统计数量7.3 实用命令命令说明oneuptime version打印 CLI 版本oneuptime whoami显示当前认证信息oneuptime resources [--type type]列出可用资源类型--type可过滤database或analytics7.4 全局选项所有命令通用选项说明--api-key key临时覆盖本次命令的 API Key--url url临时覆盖本次命令的实例地址--context name使用指定的具名上下文-o, --output format输出格式json、table、wide--no-color禁用彩色输出--help显示命令帮助--version显示 CLI 版本7.5 底层 API 端点映射作为参考CLI 各操作最终映射到 OneUptime 的 REST API 端点所有请求都会携带APIKey请求头用于认证命令HTTP 方法端点listPOST/api/resource/get-listgetPOST/api/resource/id/get-itemcreatePOST/api/resourceupdatePUT/api/resource/id/deleteDELETE/api/resource/id/countPOST/api/resource/count这一映射关系在 ApiClient.ts 中实现并由 ApiClient.test.ts 验证同时可结合 ConfigCommands.ts、ResourceCommands.ts 与 UtilityCommands.ts 对照命令注册与参数解析的完整逻辑。八、获取帮助CLI 内置了基于commander的完整帮助系统# 全局帮助 oneuptime --help # 某类资源的帮助 oneuptime monitor --help # 具体子命令的帮助 oneuptime monitor list --help九、实践建议与注意事项凭据安全~/.oneuptime/config.json使用0600权限保护包含明文 API Key请勿将其提交到版本库在共享机器上建议优先使用环境变量或--api-key一次性传参。上下文命名规范为生产、预发、开发环境分别建立命名上下文并在脚本中通过--context显式指定避免误操作生产环境。审计友好创建/更新资源时优先以-o json输出方便捕获返回 ID 并记录到日志或审计系统。分析类资源限制分析类资源只支持list、create、count设计脚本时需注意区分资源类别。扩展性OneUptime 侧新增 MCP 启用的模型后oneuptime resources即可自动发现CLI 无需升级即可操作新资源。通过本文的实战示例你可以将 OneUptime 的监控项、事件、告警、状态页等资源管理完全迁移到终端并轻松接入 GitHub Actions、通用 CI 脚本或 Docker 容器实现基础设施资源的声明式与自动化管理。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
OneUptime CLI 完全指南：终端管理监控、事件与告警资源的实战手册
OneUptime CLI 完全指南终端管理监控、事件与告警资源的实战手册【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptimeOneUptime CLIoneuptime/cli是 OneUptime 官方提供的命令行接口让你无需打开 Web 控制台即可在终端中完成监控、事件Incident、告警Alert、状态页Status Page、值班策略等资源的全套 CRUD 操作。本文以 CLI 官方文档为主线结合仓库内 CLI 源码 与单元测试系统讲解安装、认证上下文、资源操作、输出格式、CI/CD 脚本化等完整能力读完即可把 OneUptime 资源管理完全接入你的终端工作流与自动化管线。一、CLI 是什么核心能力一览OneUptime CLI 是一款专为终端与自动化场景设计的资源管理工具其核心特性包括多环境支持通过命名上下文named contexts区分生产、预发staging、开发等不同实例一键切换。资源自动发现CLI 会自动检测当前 OneUptime 实例上可用的资源类型所有开启了 MCP 能力的模型都会自动暴露为 CLI 资源无需手工配置。灵活认证支持通过命令行参数、环境变量、已保存的上下文三种途径提供凭据并可自由混用。智能输出格式提供 JSON、table、wide 三种输出模式交互终端默认表格管道场景自动切 JSON。脚本友好设计了明确的退出码与 JSON 输出专为 CI/CD 流水线而生。从源码结构看CLI 是一个基于 TypeScript 与commander框架构建的独立子项目位于仓库 CLI 目录 下由命令注册层Commands、核心层Core与类型定义Types/CLITypes.ts组成。二、安装与快速开始2.1 全局安装npm install -g oneuptime/cli安装后即可在任意终端使用oneuptime命令。如果身处本仓库开发环境也可以在 CLI 目录 内直接以开发模式运行cd CLI npm install npm start -- --help # 通过 ts-node 运行2.2 快速上手# 使用 API Key 认证并登录你的 OneUptime 实例 oneuptime login your-api-key https://oneuptime.com # 列出你的监控项 oneuptime monitor list # 查看某个具体的事件 oneuptime incident get incident-id # 查看实例上所有可用资源类型 oneuptime resources四条命令即可完成认证 → 发现资源 → 查询数据的完整闭环。三、认证、上下文与凭据解析3.1 登录oneuptime login认证的核心命令是login通过 API Key 与实例地址建立会话oneuptime login api-key instance-url参数说明参数说明api-keyOneUptime API Key形如sk-your-api-keyinstance-urlOneUptime 实例地址如https://oneuptime.com--context-name name为该登录会话命名的上下文默认default典型示例# 使用默认上下文登录 oneuptime login sk-abc123 https://oneuptime.com # 以 production 命名上下文登录 oneuptime login sk-abc123 https://oneuptime.com --context-name production # 同时配置多个环境 oneuptime login sk-prod-key https://oneuptime.com --context-name production oneuptime login sk-staging-key https://staging.oneuptime.com --context-name staging从 ConfigCommands.ts 的源码可以看到login的实现细节命令用commander定义了两个必填位置参数api-key与instance-url以及默认值为default的--context-name选项在动作函数中实例地址会先经过instanceUrl.replace(/\/$/, )去除末尾斜杠再封装成CLIContext写入配置并自动将该上下文设为当前激活状态。3.2 上下文管理oneuptime context上下文context用于保存多套环境凭据方便在生产、预发、开发之间快速切换。命令说明oneuptime context list列出所有已配置的上下文当前上下文以*标记oneuptime context use name切换到指定命名上下文影响之后所有命令oneuptime context current显示当前激活的上下文含实例 URL 与脱敏后的 API Keyoneuptime context delete name删除指定上下文若删除的是当前上下文CLI 自动切换到剩余的第一个上下文# 切换到 staging oneuptime context use staging # 切换到 production oneuptime context use production # 查看当前上下文 oneuptime context current3.3 凭据解析优先级CLI 按以下顺序解析凭据高优先级覆盖低优先级CLI 参数--api-key与--url环境变量ONEUPTIME_API_KEY与ONEUPTIME_URL具名上下文通过--context name显式指定的上下文当前上下文配置文件~/.oneuptime/config.json中保存的当前激活上下文不同来源可以自由混用例如用环境变量提供 API Key、同时用已保存的上下文提供实例 URL# 方式一全部用 CLI 参数 oneuptime --api-key sk-abc123 --url https://oneuptime.com incident list # 方式二全部用环境变量 export ONEUPTIME_API_KEYsk-abc123 export ONEUPTIME_URLhttps://oneuptime.com oneuptime incident list # 方式三指定某个具名上下文 oneuptime --context production incident list3.4 验证认证状态oneuptime whoamioneuptime whoami输出内容包括实例 URL、脱敏后的 API Key、当前上下文名称仅当存在已保存的激活上下文时显示。若未认证命令会给出友好提示并建议执行oneuptime login。3.5 配置文件与安全性所有凭据保存在~/.oneuptime/config.json文件权限被限制为0600仅当前用户可读写。典型结构如下{ currentContext: production, contexts: { production: { name: production, apiUrl: https://oneuptime.com, apiKey: sk-... }, staging: { name: staging, apiUrl: https://staging.oneuptime.com, apiKey: sk-... } }, defaults: { output: table, limit: 10 } }配置中除了上下文列表还包含defaults段用于记录默认输出格式与默认分页大小对应-o与--limit的缺省值。该文件由 ConfigManager.ts 负责读写上下文增删、当前上下文切换等操作在 ConfigCommands.ts 中均有对应实现并有 ConfigManager.test.ts 与 ConfigCommands.test.ts 覆盖。四、资源自动发现与 CRUD 操作4.1 资源发现oneuptime resourcesOneUptime 实例上所有启用了 MCP 能力的模型都会被 CLI 自动识别为可用资源# 查看全部资源类型 oneuptime resources # 只查看数据库类资源 oneuptime resources --type database # 只查看分析类资源 oneuptime resources --type analytics常见资源与对应命令资源命令事件Incidentoneuptime incident告警Alertoneuptime alert监控项Monitoroneuptime monitor监控状态Monitor Statusoneuptime monitor-status事件状态Incident Stateoneuptime incident-state状态页Status Pageoneuptime status-page值班策略On-Call Policyoneuptime on-call-policy团队Teamoneuptime team计划维护事件oneuptime scheduled-maintenance-event资源会随 OneUptime 侧 MCP 能力的开放而自动扩展无需升级 CLI。资源命令的实际注册逻辑位于 ResourceCommands.ts配合 SelectFieldGenerator.ts 动态生成字段提示。4.2 列表oneuptime resource listoneuptime resource list [options]选项说明默认值--query jsonJSON 格式的过滤条件无--limit n最大返回条数10--skip n跳过的条数分页0--sort jsonJSON 格式排序规则无-o, --output format输出格式table# 列出最近 10 个事件 oneuptime incident list # 按事件状态 ID 过滤 oneuptime incident list --query {currentIncidentStateId:state-id} # 分页跳过前 40 条取 20 条 oneuptime incident list --limit 20 --skip 40 # 按创建时间倒序 oneuptime incident list --sort {createdAt:-1} # JSON 输出 oneuptime incident list -o json4.3 查询单个资源oneuptime resource getoneuptime resource get idid为资源 UUID。例如# 获取指定事件 oneuptime incident get 550e8400-e29b-41d4-a716-446655440000 # 以 JSON 格式获取监控项 oneuptime monitor get abc-123 -o json4.4 创建资源oneuptime resource create数据可来自内联 JSON 或本地文件--data与--file二选一oneuptime resource create [options]选项说明--data json资源数据JSON 对象--file path包含资源数据的 JSON 文件路径-o, --output format输出格式# 内联 JSON 创建事件 oneuptime incident create --data {title:API Outage,currentIncidentStateId:state-id,incidentSeverityId:severity-id,declaredAt:2025-01-15T10:30:00Z} # 从 JSON 文件创建 oneuptime incident create --file incident.json # 创建监控项并以 JSON 输出以捕获新 ID oneuptime monitor create --data {name:API Health Check} -o json4.5 更新资源oneuptime resource updateoneuptime resource update id --data json [-o format]--data为必填用于指定要更新的字段# 将事件状态变更为已解决 oneuptime incident update abc-123 --data {currentIncidentStateId:resolved-state-id} # 重命名监控项 oneuptime monitor update abc-123 --data {name:Updated Monitor Name}4.6 删除资源oneuptime resource deleteoneuptime resource delete id [--force]删除默认会二次确认--force可跳过确认提示oneuptime incident delete abc-123 oneuptime monitor delete 550e8400-e29b-41d4-a716-446655440000 oneuptime monitor delete 550e8400-e29b-41d4-a716-446655440000 --force4.7 统计数量oneuptime resource countoneuptime resource count [--query json]# 统计所有事件 oneuptime incident count # 按状态统计事件 oneuptime incident count --query {currentIncidentStateId:state-id} # 统计监控项 oneuptime monitor count4.8 分析类资源的操作限制分析类资源Analytics支持的操作集比数据库类资源更小操作是否支持list是create是count是get否update否delete否可用oneuptime resources --type analytics查看当前实例暴露了哪些分析类资源。五、输出格式详解5.1 table默认格式交互终端下的默认输出展示为 ASCII 表格并智能选择列oneuptime incident list┌──────────────────┬───────────────────────┬─────────────────────┬─────────────────────┐ │ _id │ title │ createdAt │ updatedAt │ ├──────────────────┼───────────────────────┼─────────────────────┼─────────────────────┤ │ abc-123 │ API Outage │ 2025-01-15T10:30:00 │ 2025-01-15T12:00:00 │ │ def-456 │ Database Slowdown │ 2025-01-14T08:15:00 │ 2025-01-14T09:30:00 │ └──────────────────┴───────────────────────┴─────────────────────┴─────────────────────┘表格格式行为规则最多展示 6 列列优先级为_id、name、title、createdAt、updatedAt超过 60 字符的值截断并以...结尾表头带颜色编码可用--no-color关闭。5.2 JSON输出原始 JSON缩进为 2 个空格最适合脚本化处理oneuptime incident list -o json[ { _id: abc-123, title: API Outage, currentIncidentStateId: 550e8400-e29b-41d4-a716-446655440000, createdAt: 2025-01-15T10:30:00Z } ]关键行为当输出被重定向到其他命令非 TTY 模式时CLI 会自动切换为 JSON 格式oneuptime incident list | jq .[].title5.3 wide展示全部列且不截断适合详细检查但可能产生超宽输出oneuptime incident list -o wide5.4 禁用颜色# 使用 --no-color 参数 oneuptime --no-color incident list # 使用 NO_COLOR 环境变量 NO_COLOR1 oneuptime incident list5.5 特殊场景输出场景输出空结果集No results found.未返回数据No data returned.单对象如get键值对形式的表格count命令纯数字输出相关的实现集中在 OutputFormatter.ts其行为由 OutputFormatter.test.ts 验证。六、Scripting 与 CI/CD 自动化6.1 环境变量认证适合在无交互的流水线环境中使用无需保存上下文export ONEUPTIME_API_KEYsk-your-api-key export ONEUPTIME_URLhttps://oneuptime.com环境变量的优先级高于已保存的上下文但低于 CLI 参数。CLI 支持的完整环境变量清单见 READMEONEUPTIME_API_KEYAPI Key、ONEUPTIME_URL实例地址、NO_COLOR禁用彩色输出。6.2 退出码约定退出码含义0成功1一般错误2认证错误凭据缺失或无效3未找到404在脚本中可直接依赖退出码做错误处理if ! oneuptime monitor list /dev/null 21; then echo Failed to list monitors exit 1 fi退出码的映射逻辑由 ErrorHandler.ts 实现并被 ErrorHandler.test.ts 覆盖。6.3 结合 jq 的 JSON 处理# 提取所有事件标题 oneuptime incident list -o json | jq .[].title # 捕获新建监控项的 ID NEW_ID$(oneuptime monitor create --data {name:API Health} -o json | jq -r ._id) echo Created monitor: $NEW_ID # 按严重度统计事件 oneuptime incident count --query {incidentSeverityId:severity-id}6.4 从文件创建资源--file适合配合基础设施即代码Infrastructure as Code场景把资源定义纳入版本管理# monitor.json # { # name: API Health Check, # projectId: your-project-id # } oneuptime monitor create --file monitor.json6.5 批量操作处理大量资源时可用循环批量执行# 从 JSON 数组文件批量创建监控项 cat monitors.json | jq -r .[] | json | while read monitor; do oneuptime monitor create --data $monitor done6.6 CI/CD 流水线示例GitHub Actions定时检查活跃事件name: Check Active Incidents on: schedule: - cron: */5 * * * * jobs: health-check: runs-on: ubuntu-latest steps: - name: Install OneUptime CLI run: npm install -g oneuptime/cli - name: Check for active incidents env: ONEUPTIME_API_KEY: ${{ secrets.ONEUPTIME_API_KEY }} ONEUPTIME_URL: https://oneuptime.com run: | INCIDENT_COUNT$(oneuptime incident count) if [ $INCIDENT_COUNT -gt 0 ]; then echo WARNING: $INCIDENT_COUNT incidents found exit 1 fi通用 CI 脚本部署前后自动创建并关闭事件#!/bin/bash set -e export ONEUPTIME_API_KEY$CI_ONEUPTIME_API_KEY export ONEUPTIME_URL$CI_ONEUPTIME_URL # 创建部署事件并捕获 ID # 注意currentIncidentStateId 与 incidentSeverityId 必须引用项目中已存在的状态/严重度 ID INCIDENT_ID$(oneuptime incident create --data { title: Deployment Started, currentIncidentStateId: $INVESTIGATING_STATE_ID, incidentSeverityId: $SEVERITY_ID, declaredAt: $(date -u %Y-%m-%dT%H:%M:%SZ) } -o json | jq -r ._id) # 在此执行部署步骤... # 部署成功后关闭事件 oneuptime incident update $INCIDENT_ID --data {currentIncidentStateId:$RESOLVED_STATE_ID}Docker封装 CLI 为容器镜像FROM node:26-slim RUN npm install -g oneuptime/cli ENV ONEUPTIME_API_KEY ENV ONEUPTIME_URL ENTRYPOINT [oneuptime]docker run --rm \ -e ONEUPTIME_API_KEYsk-abc123 \ -e ONEUPTIME_URLhttps://oneuptime.com \ oneuptime-cli incident list6.7 脚本中指定上下文配置了多个上下文时可在脚本中精确指定目标环境oneuptime --context production incident list oneuptime --context staging monitor count七、命令速查与 API 端点映射7.1 认证命令命令说明oneuptime login api-key instance-url [--context-name name]认证并创建上下文oneuptime context list列出所有上下文oneuptime context use name切换当前上下文oneuptime context current显示当前上下文oneuptime context delete name删除上下文oneuptime whoami显示当前认证信息7.2 资源命令通用模式所有资源命令遵循同一模式将resource替换为任意已支持资源名如incident、monitor、alert、status-page命令说明oneuptime resource list [options]带过滤与分页的列表oneuptime resource get id按 ID 查询单个资源oneuptime resource create [--data json \| --file path]创建资源oneuptime resource update id --data json更新资源oneuptime resource delete id [--force]删除资源oneuptime resource count [--query json]统计数量7.3 实用命令命令说明oneuptime version打印 CLI 版本oneuptime whoami显示当前认证信息oneuptime resources [--type type]列出可用资源类型--type可过滤database或analytics7.4 全局选项所有命令通用选项说明--api-key key临时覆盖本次命令的 API Key--url url临时覆盖本次命令的实例地址--context name使用指定的具名上下文-o, --output format输出格式json、table、wide--no-color禁用彩色输出--help显示命令帮助--version显示 CLI 版本7.5 底层 API 端点映射作为参考CLI 各操作最终映射到 OneUptime 的 REST API 端点所有请求都会携带APIKey请求头用于认证命令HTTP 方法端点listPOST/api/resource/get-listgetPOST/api/resource/id/get-itemcreatePOST/api/resourceupdatePUT/api/resource/id/deleteDELETE/api/resource/id/countPOST/api/resource/count这一映射关系在 ApiClient.ts 中实现并由 ApiClient.test.ts 验证同时可结合 ConfigCommands.ts、ResourceCommands.ts 与 UtilityCommands.ts 对照命令注册与参数解析的完整逻辑。八、获取帮助CLI 内置了基于commander的完整帮助系统# 全局帮助 oneuptime --help # 某类资源的帮助 oneuptime monitor --help # 具体子命令的帮助 oneuptime monitor list --help九、实践建议与注意事项凭据安全~/.oneuptime/config.json使用0600权限保护包含明文 API Key请勿将其提交到版本库在共享机器上建议优先使用环境变量或--api-key一次性传参。上下文命名规范为生产、预发、开发环境分别建立命名上下文并在脚本中通过--context显式指定避免误操作生产环境。审计友好创建/更新资源时优先以-o json输出方便捕获返回 ID 并记录到日志或审计系统。分析类资源限制分析类资源只支持list、create、count设计脚本时需注意区分资源类别。扩展性OneUptime 侧新增 MCP 启用的模型后oneuptime resources即可自动发现CLI 无需升级即可操作新资源。通过本文的实战示例你可以将 OneUptime 的监控项、事件、告警、状态页等资源管理完全迁移到终端并轻松接入 GitHub Actions、通用 CI 脚本或 Docker 容器实现基础设施资源的声明式与自动化管理。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
