oodle-cli

Oodle CLI — 核心用法

本技能将教会 Agent 如何安全地调用 oodle CLI，并为任何子命令使用正确的标志、时间格式和身份验证方式。

前置条件

在本仓库中运行任何其他命令之前，请先安装 CLI：

# Install via Homebrew (macOS / Linux)
brew install oodle-ai/oodle/oodle

# Or via Go (any platform with Go 1.25+)
go install github.com/oodle-ai/oodle-cli/cmd/oodle@latest

# Configure auth (interactive — writes ~/.oodle/config.yaml)
oodle configure

# Or set env vars (preferred for CI / containers)
export OODLE_API_KEY=<your-api-key>
export OODLE_INSTANCE=<your-instance-id>
export OODLE_DEPLOYMENT=<your-deployment-url>   # e.g. https://app.oodle.ai

在执行任何其他命令之前，确认 CLI 可以正常运行：

oodle version
oodle monitors list -o json | head

命令执行顺序

运行任何 oodle 命令之前：

1. 检查所需的资源 ID 或名称是否已在上下文中。
2. 如果没有，运行发现命令（例如：oodle <resource> list -o json）。
3. 如果结果不明确，先请用户确认，再继续操作。
4. 使用已确认的 ID 运行目标命令。
5. 不要运行试探性命令（例如：不要在 delete 资源之前先执行 get 获取该资源）。

快速参考

命令	用途
oodle monitors	管理指标监控器
oodle dashboards	管理仪表板
oodle folders	管理仪表板文件夹
oodle notifiers	管理通知渠道
oodle notification-policies	管理将告警路由到通知渠道的规则
oodle muting-rules	在维护期间静默告警
oodle metrics query	执行 PromQL 即时查询
oodle metrics query-range	执行 PromQL 范围查询
oodle logs index-patterns	列出可用的日志索引模式
oodle logs query	使用 OpenSearch Query DSL 搜索日志
oodle metrics	查询指标名称、标签和标签值
oodle traces	搜索和获取链路追踪
oodle traces traceql search / metrics	使用 TraceQL 查找链路追踪，或计算速率、计数和分位数（参见 oodle-traces 技能）
oodle log-metrics	管理基于日志生成的指标规则
oodle synthetic-monitors	管理 HTTP/TCP 合成检查
oodle drop-rules	管理指标丢弃规则
oodle api-keys	管理 API 密钥
oodle users	管理用户
oodle configure	交互式身份验证设置
oodle skills	安装和管理 Agent 技能（本仓库）

常见操作

输出格式

-o 用于选择输出格式。默认格式为 table（便于阅读）。如果结果将由其他工具使用，请使用 json。

# ✅ CORRECT — JSON for scripting; jq can parse it
oodle monitors list -o json | jq '.[].id'

# ✅ CORRECT — table for humans skimming a list
oodle monitors list -o table

# ✅ CORRECT — yaml when round-tripping into a `-f` input file
oodle monitors get mon_123 -o yaml > monitor.yaml

# ✅ CORRECT — csv for spreadsheets / quick grep
oodle metrics names -o csv

# ❌ WRONG — parsing the default table format with awk/grep is fragile
oodle monitors list | awk '{print $1}'

非交互式标志

# ✅ CORRECT — --force skips destructive-action confirmation in CI
oodle monitors delete mon_123 --force

# ❌ WRONG — running a destructive command without --force in a non-TTY pipeline
oodle monitors delete mon_123

临时故障重试

# ✅ CORRECT — retry transient 5xx / network errors up to 3 times
oodle monitors list -o json --retries 3

# ❌ WRONG — wrapping the command in a custom shell loop instead of using --retries
until oodle monitors list -o json; do sleep 5; done

时间标志

--start、--end 和 --time 接受以下格式（没有 --from 或 --to 标志）：

格式	示例	含义
Epoch 秒	1731628800	绝对 Unix 时间戳（也接受毫秒、微秒和纳秒）
RFC 3339	2026-10-07T10:00:00Z	绝对时间
now	now	当前服务端时间
相对时长	-1h、-30m、-7d	当前时间减去该时长

大多数命令默认使用 --start -1h --end now。oodle traces list 和 oodle traces get 必须同时指定这两个标志。

# ✅ CORRECT — relative duration is timezone-safe and readable
oodle traces list --service api --start -1h --end now -o json

# ✅ CORRECT — epoch when the caller has an exact timestamp
oodle traces list --service api --start 1731628800 --end 1731632400 -o json

# ❌ WRONG — human strings are not parsed
oodle traces list --service api --start "1 hour ago" --end now

文件输入（-f）

create 和 update 命令接受 -f <file>，并根据文件扩展名或首个字节检测 JSON 或 YAML 格式。

# ✅ CORRECT — JSON file
oodle monitors create -f monitor.json

# ✅ CORRECT — YAML file
oodle monitors create -f monitor.yaml

# ✅ CORRECT — round-trip through yaml for in-place edits
oodle monitors get mon_123 -o yaml > monitor.yaml
$EDITOR monitor.yaml
oodle monitors update mon_123 -f monitor.yaml

# ❌ WRONG — passing JSON inline as a flag value (no -f)
oodle monitors create --body '{"name":"x"}'

最佳实践

如果输出将由其他工具使用，请使用 -o json

如果工作流的下一步是 jq 过滤器、脚本或另一条 oodle 命令，请请求 JSON 格式。表格输出仅供人阅读。

# ✅ CORRECT
ID=$(oodle monitors list -o json | jq -r '.[] | select(.name=="High CPU") | .id')

# ❌ WRONG — column positions in table output can change between releases
ID=$(oodle monitors list | grep "High CPU" | awk '{print $1}')

在 CI 中使用 --force，切勿在不属于你的交互式会话中使用

--force 会跳过破坏性操作确认提示。为确保安全，始终先执行 get。

# ✅ CORRECT — in CI: confirm the resource exists, then delete
oodle monitors get mon_123 -o json > /dev/null && oodle monitors delete mon_123 --force

# ❌ WRONG — blanket --force on a name match without verifying the ID
oodle monitors delete $(oodle monitors list | grep CPU | head -1 | awk '{print $1}') --force

在 CI 中使用环境变量存放凭据

切勿将 API 密钥硬编码或写入 shell 历史记录。

# ✅ CORRECT — credentials come from the CI secret store
export OODLE_API_KEY="$CI_OODLE_API_KEY"
export OODLE_INSTANCE="$CI_OODLE_INSTANCE"
oodle monitors list -o json

# ❌ WRONG — credential in plain text on the command line
OODLE_API_KEY=sk_live_abc123 oodle monitors list -o json

使用已发现的 ID 固定命令序列

当工作流要修改资源时，请记录一次该资源的 ID 并重复使用。

# ✅ CORRECT
ID=$(oodle monitors list -o json | jq -r '.[] | select(.name=="High CPU") | .id')
oodle monitors get "$ID" -o json
oodle monitors update "$ID" -f monitor.json

# ❌ WRONG — re-resolving the name on every step (race conditions, extra latency)
oodle monitors get $(oodle monitors list -o json | jq -r '.[] | select(.name=="High CPU") | .id')
oodle monitors update $(oodle monitors list -o json | jq -r '.[] | select(.name=="High CPU") | .id') -f monitor.json

故障处理

错误	原因	修复方法
401 未授权	API 密钥无效或缺失	运行 oodle configure 或设置 OODLE_API_KEY
404 未找到	资源 ID 不存在	使用 oodle <resource> list -o json 验证
connection refused	OODLE_DEPLOYMENT URL 错误	检查 OODLE_DEPLOYMENT 环境变量，确保末尾没有斜杠，并确认网络允许出站连接
429 请求过多	触发速率限制	添加 --retries 3，等待 5–10 秒后重试，并减少每分钟批量请求的数量
unknown command	CLI 版本过旧	使用 brew upgrade oodle 或 go install ...@latest 升级
error parsing -f file	文件不是有效的 JSON/YAML	重试前使用 python3 -m json.tool 或 yq . 验证

参考资料

• Oodle CLI 仓库
• Oodle 文档