oodle-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Oodle CLI — Core Usage

Oodle CLI — 核心使用方法

This skill teaches the agent to invoke the

oodle

CLI safely, with the right flags, time formats, and authentication for any subcommand.

本技能指导Agent安全调用

oodle

CLI，针对所有子命令使用正确的参数、时间格式和认证方式。

Prerequisites

前置条件

Install the CLI before running any other command in this repo:

bash

undefined

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

bash

undefined

Install via Homebrew (macOS / Linux)

通过Homebrew安装（macOS / Linux）

brew install oodle-ai/oodle/oodle

Or via Go (any platform with Go 1.21+)

或通过Go安装（支持所有安装了Go 1.21+的平台）

go install github.com/oodle-ai/oodle-cli@latest

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

配置认证（交互式操作——会写入~/.oodle/config.yaml）

oodle configure

Or set env vars (preferred for CI / containers)

或设置环境变量（CI/容器环境推荐使用）

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


Verify the CLI works before issuing any other command:

```bash
oodle version
oodle monitors list -o json | head

export OODLE_API_KEY=<your-api-key> export OODLE_INSTANCE=<your-instance-id> export OODLE_DEPLOYMENT=<your-deployment-url> # 示例：https://app.oodle.ai


在执行其他命令前，请验证CLI是否正常工作：

```bash
oodle version
oodle monitors list -o json | head

Command Execution Order

命令执行顺序

Before running any oodle command:

Check whether the required resource ID or name is already in context.
If not, run the discovery command (e.g.,
```
oodle <resource> list -o json
```
).
If the result is ambiguous, ask the user to confirm before proceeding.
Run the target command with the resolved ID.
Do not run speculative commands (e.g., do not
```
delete
```
without first
```
get
```
-ing the resource).

运行任何oodle命令前：

检查所需的资源ID或名称是否已在上下文环境中。
如果没有，执行发现命令（例如：
```
oodle <resource> list -o json
```
）。
如果结果不明确，请先请求用户确认再继续。
使用解析后的ID运行目标命令。
不要执行推测性命令（例如：在未先执行
```
get
```
获取资源信息的情况下，不要执行
```
delete
```
命令）。

Quick Reference

快速参考

Command	Purpose
`oodle monitors`	Manage metric monitors
`oodle dashboards`	Manage dashboards
`oodle folders`	Manage dashboard folders
`oodle notifiers`	Manage notification channels
`oodle notification-policies`	Manage routing of alerts to notifiers
`oodle muting-rules`	Silence alerts during maintenance
`oodle metrics query`	Run PromQL instant query
`oodle metrics query-range`	Run PromQL range query
`oodle logs index-patterns`	List available log index patterns
`oodle logs query`	Search logs using OpenSearch Query DSL
`oodle metrics`	Query metric names, labels, label values
`oodle traces`	Search and fetch traces
`oodle log-metrics`	Manage log-derived metric rules
`oodle synthetic-monitors`	Manage HTTP/TCP synthetic checks
`oodle drop-rules`	Manage metric drop / sample rules
`oodle api-keys`	Manage API keys
`oodle users`	Manage users
`oodle configure`	Interactive auth setup
`oodle skills`	Install and manage agent skills (this repo)

命令	用途
`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 log-metrics`	管理日志衍生指标规则
`oodle synthetic-monitors`	管理HTTP/TCP合成监控检查
`oodle drop-rules`	管理指标丢弃/采样规则
`oodle api-keys`	管理API密钥
`oodle users`	管理用户
`oodle configure`	交互式认证设置
`oodle skills`	安装并管理Agent技能（本仓库）

Common Operations

常见操作

Output formats

输出格式

-o

selects the output format. Default is

table

(human-readable). Use

json

whenever a result is consumed by another tool.

bash

undefined

-o

参数用于选择输出格式。默认格式为

table

（适合人类阅读）。当结果需要被其他工具消费时，请使用

json

格式。

bash

undefined

✅ CORRECT — JSON for scripting; jq can parse it

✅ 正确用法 — 脚本使用JSON格式；jq可解析

oodle monitors list -o json | jq '.[].id'

✅ CORRECT — table for humans skimming a list

✅ 正确用法 — 人类浏览列表使用table格式

oodle monitors list -o table

✅ CORRECT — yaml when round-tripping into a

-f

input file

✅ 正确用法 — 当需要将结果回写到

-f

输入文件时使用yaml格式

oodle monitors get mon_123 -o yaml > monitor.yaml

✅ CORRECT — csv for spreadsheets / quick grep

✅ 正确用法 — 导出到电子表格/快速搜索使用csv格式

oodle metrics list --match http_ -o csv

❌ WRONG — parsing the default table format with awk/grep is fragile

❌ 错误用法 — 使用awk/grep解析默认的table格式易出错

oodle monitors list | awk '{print $1}'

undefined

oodle monitors list | awk '{print $1}'

undefined

Non-interactive flags

非交互式参数

bash

undefined

bash

undefined

✅ CORRECT — --force skips destructive-action confirmation in CI

✅ 正确用法 — 在CI环境中使用--force跳过破坏性操作的确认

oodle monitors delete mon_123 --force

❌ WRONG — running a destructive command without --force in a non-TTY pipeline

❌ 错误用法 — 在非TTY管道中运行破坏性命令时未使用--force

oodle monitors delete mon_123

undefined

oodle monitors delete mon_123

undefined

Retries on transient failures

临时故障重试

bash

undefined

bash

undefined

✅ CORRECT — retry transient 5xx / network errors up to 3 times

✅ 正确用法 — 针对临时5xx/网络错误最多重试3次

oodle monitors list -o json --retries 3

❌ WRONG — wrapping the command in a custom shell loop instead of using --retries

❌ 错误用法 — 使用自定义shell循环代替--retries参数

until oodle monitors list -o json; do sleep 5; done

undefined

until oodle monitors list -o json; do sleep 5; done

undefined

Time flags

时间参数

--from

and

--to

accept three formats:

Format	Example	Meaning
Epoch seconds	`1731628800`	absolute unix timestamp
`now`	`now`	current server time
Relative duration	`-1h` , `-30m` , `-7d`	now minus the duration

bash

undefined

--from

和

--to

支持三种格式：

格式	示例	含义
时间戳秒数	`1731628800`	绝对Unix时间戳
`now`	`now`	当前服务器时间
相对时长	`-1h` , `-30m` , `-7d`	当前时间减去指定时长

bash

undefined

✅ CORRECT — relative duration is timezone-safe and readable

✅ 正确用法 — 相对时长无需考虑时区且可读性强

oodle traces list --service api --from -1h --to now -o json

✅ CORRECT — epoch when the caller has an exact timestamp

✅ 正确用法 — 当调用者有精确时间戳时使用时间戳

oodle traces list --service api --from 1731628800 --to 1731632400 -o json

❌ WRONG — human strings are not parsed

❌ 错误用法 — 不解析自然语言字符串

oodle traces list --service api --from "1 hour ago"

undefined

oodle traces list --service api --from "1 hour ago"

undefined

File input (

-f

)

文件输入（

-f

）

create

and

update

commands accept

-f <file>

and detect JSON or YAML from the file extension or the leading byte.

bash

undefined

create

和

update

命令支持

-f <file>

参数，会根据文件扩展名或开头字节自动检测JSON或YAML格式。

bash

undefined

✅ CORRECT — JSON file

✅ 正确用法 — JSON文件

oodle monitors create -f monitor.json

✅ CORRECT — YAML file

✅ 正确用法 — YAML文件

oodle monitors create -f monitor.yaml

✅ CORRECT — round-trip through yaml for in-place edits

✅ 正确用法 — 通过yaml格式来回编写以实现就地编辑

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)

❌ 错误用法 — 未使用-f参数直接传入JSON内容

oodle monitors create --body '{"name":"x"}'

undefined

oodle monitors create --body '{"name":"x"}'

undefined

Best Practices

最佳实践

Use

-o json

whenever output is consumed by another tool

当输出需要被其他工具消费时，请使用

-o json

格式

If the next step in the workflow is a

jq

filter, a script, or another

oodle

command, request JSON. Table output is for humans only.

bash

undefined

如果工作流的下一步是使用

jq

过滤、脚本或其他

oodle

命令，请使用JSON格式。Table格式仅适合人类阅读。

bash

undefined

✅ CORRECT

✅ 正确用法

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

❌ WRONG — column positions in table output can change between releases

❌ 错误用法 — table格式的列位置可能会在版本更新时发生变化

ID=$(oodle monitors list | grep "High CPU" | awk '{print $1}')

undefined

ID=$(oodle monitors list | grep "High CPU" | awk '{print $1}')

undefined

Use

--force

in CI, never in interactive sessions you don't own

在CI环境中使用

--force

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

--force

skips the destructive-action confirmation prompt. Always pair it with a prior

get

for safety.

bash

undefined

--force

会跳过破坏性操作的确认提示。为了安全，使用前务必先执行

get

命令确认资源存在。

bash

undefined

✅ CORRECT — in CI: confirm the resource exists, then delete

✅ 正确用法 — 在CI环境中：先确认资源存在，再执行删除

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

❌ 错误用法 — 仅通过名称匹配就使用--force，未验证ID

oodle monitors delete $(oodle monitors list | grep CPU | head -1 | awk '{print $1}') --force

undefined

oodle monitors delete $(oodle monitors list | grep CPU | head -1 | awk '{print $1}') --force

undefined

Use environment variables for credentials in CI

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

Never hardcode the API key or write it into shell history.

bash

undefined

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

bash

undefined

✅ CORRECT — credentials come from the CI secret store

✅ 正确用法 — 凭据来自CI密钥存储

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

undefined

OODLE_API_KEY=sk_live_abc123 oodle monitors list -o json

undefined

Pin command sequences to discovered IDs

将命令序列绑定到已发现的ID

When a workflow modifies a resource, capture the ID once and reuse it.

bash

undefined

当工作流需要修改资源时，只需捕获一次ID并重复使用。

bash

undefined

✅ 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)

❌ 错误用法 — 每一步都重新解析名称（存在竞态条件、额外延迟）

undefined

undefined

Failure Handling

故障处理

Error	Cause	Fix
401 Unauthorized	Invalid or missing API key	Run `oodle configure` or set `OODLE_API_KEY`
404 Not Found	Resource ID does not exist	Verify with `oodle <resource> list -o json`
connection refused	Wrong `OODLE_DEPLOYMENT` URL	Check `OODLE_DEPLOYMENT` env var, ensure no trailing slash, confirm network egress
429 Too Many Requests	Rate limited	Add `--retries 3` , back off 5–10s, batch fewer requests per minute
`unknown command`	CLI version too old	Upgrade with `brew upgrade oodle` or `go install ...@latest`
`error parsing -f file`	File is not valid JSON/YAML	Validate with `python3 -m json.tool` or `yq .` before retrying

错误	原因	修复方法
401 Unauthorized	API密钥无效或缺失	执行 `oodle configure` 或设置 `OODLE_API_KEY` 环境变量
404 Not Found	资源ID不存在	使用 `oodle <resource> list -o json` 验证
connection refused	`OODLE_DEPLOYMENT` URL错误	检查 `OODLE_DEPLOYMENT` 环境变量，确保无末尾斜杠，确认网络出口正常
429 Too Many Requests	触发速率限制	添加 `--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

Original

Translation

Oodle CLI — Core Usage

Oodle CLI — 核心使用方法

Prerequisites

前置条件

Install via Homebrew (macOS / Linux)

通过Homebrew安装（macOS / Linux）

Or via Go (any platform with Go 1.21+)

或通过Go安装（支持所有安装了Go 1.21+的平台）

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

配置认证（交互式操作——会写入~/.oodle/config.yaml）

Or set env vars (preferred for CI / containers)

或设置环境变量（CI/容器环境推荐使用）

Command Execution Order

命令执行顺序

Quick Reference

快速参考

Common Operations

常见操作

Output formats

输出格式

✅ CORRECT — JSON for scripting; jq can parse it

✅ 正确用法 — 脚本使用JSON格式；jq可解析

✅ CORRECT — table for humans skimming a list

✅ 正确用法 — 人类浏览列表使用table格式

✅ CORRECT — yaml when round-tripping into a -f input file

✅ 正确用法 — 当需要将结果回写到-f输入文件时使用yaml格式

✅ CORRECT — csv for spreadsheets / quick grep

✅ 正确用法 — 导出到电子表格/快速搜索使用csv格式

❌ WRONG — parsing the default table format with awk/grep is fragile

❌ 错误用法 — 使用awk/grep解析默认的table格式易出错

Non-interactive flags

非交互式参数

✅ CORRECT — --force skips destructive-action confirmation in CI

✅ 正确用法 — 在CI环境中使用--force跳过破坏性操作的确认

❌ WRONG — running a destructive command without --force in a non-TTY pipeline

❌ 错误用法 — 在非TTY管道中运行破坏性命令时未使用--force

Retries on transient failures

临时故障重试

✅ CORRECT — retry transient 5xx / network errors up to 3 times

✅ 正确用法 — 针对临时5xx/网络错误最多重试3次

❌ WRONG — wrapping the command in a custom shell loop instead of using --retries

❌ 错误用法 — 使用自定义shell循环代替--retries参数

Time flags

时间参数

✅ CORRECT — relative duration is timezone-safe and readable

✅ 正确用法 — 相对时长无需考虑时区且可读性强

✅ CORRECT — epoch when the caller has an exact timestamp

✅ 正确用法 — 当调用者有精确时间戳时使用时间戳

❌ WRONG — human strings are not parsed

❌ 错误用法 — 不解析自然语言字符串

File input (-f)

文件输入（-f）

✅ CORRECT — JSON file

✅ 正确用法 — JSON文件

✅ CORRECT — YAML file

✅ 正确用法 — YAML文件

✅ CORRECT — round-trip through yaml for in-place edits

✅ 正确用法 — 通过yaml格式来回编写以实现就地编辑

❌ WRONG — passing JSON inline as a flag value (no -f)

❌ 错误用法 — 未使用-f参数直接传入JSON内容

Best Practices

最佳实践

Use -o json whenever output is consumed by another tool

当输出需要被其他工具消费时，请使用-o json格式

✅ CORRECT

✅ 正确用法

❌ WRONG — column positions in table output can change between releases

❌ 错误用法 — table格式的列位置可能会在版本更新时发生变化

Use --force in CI, never in interactive sessions you don't own

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

✅ CORRECT — in CI: confirm the resource exists, then delete

✅ 正确用法 — 在CI环境中：先确认资源存在，再执行删除

❌ WRONG — blanket --force on a name match without verifying the ID

❌ 错误用法 — 仅通过名称匹配就使用--force，未验证ID

Use environment variables for credentials in CI

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

✅ CORRECT — credentials come from the CI secret store

✅ CORRECT — yaml when round-tripping into a
`-f`
input file

✅ 正确用法 — 当需要将结果回写到
`-f`
输入文件时使用yaml格式

File input (
`-f`
)

文件输入（
`-f`
）

Use
`-o json`
whenever output is consumed by another tool

当输出需要被其他工具消费时，请使用
`-o json`
格式

Use
`--force`
in CI, never in interactive sessions you don't own

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