oodle-cli

Oodle CLI — 基本的な使い方

このスキルでは、適切なフラグ、時刻形式、認証を使用して、エージェントがあらゆるサブコマンドで 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. 推測に基づくコマンドは実行しないでください（例：リソースを get する前に delete しないでください）。

クイックリファレンス

コマンド	目的
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	エージェントスキル（このリポジトリ）をインストールして管理します

よく使う操作

出力形式

-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 フラグはありません）。

形式	例	意味
エポック秒	1731628800	絶対的な Unix タイムスタンプ（ms、µs、ns も使用できます）
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}')

--force は CI で使用し、自分が管理していない対話型セッションでは使用しない

--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 キーをコードに直接記述したり、シェルの履歴に書き込んだりしないでください。

# ✅ 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 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 秒待ってから、1 分あたりのリクエスト数を減らしてまとめて送信してください
unknown command	CLI のバージョンが古すぎます	brew upgrade oodle または go install ...@latest でアップグレードしてください
error parsing -f file	ファイルが有効な JSON/YAML ではありません	再試行する前に、python3 -m json.tool または yq . で検証してください

参考資料

• Oodle CLI リポジトリ
• Oodle ドキュメント