Oodle CLI — Core Usage

This skill teaches the agent to invoke the oodle CLI safely, with the right flags, time formats, and authentication for any subcommand.

Prerequisites

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

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

# Or via Go (any platform with Go 1.21+)
go install github.com/oodle-ai/oodle-cli@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

Verify the CLI works before issuing any other command:

oodle version
oodle monitors list -o json | head

Command Execution Order

Before running any oodle command:

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

Quick Reference

Common Operations

Output formats

-o selects the output format. Default is table (human-readable). Use json whenever a result is consumed by another tool.

# ✅ 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 list --match http_ -o csv

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

Non-interactive flags

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

Retries on transient failures

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

Time flags

--from and --to accept three formats:

# ✅ 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"

File input (-f)

create and update commands accept -f <file> and detect JSON or YAML from the file extension or the leading byte.

# ✅ 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"}'

Best Practices

Use -o json whenever output is consumed by another tool

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.

# ✅ 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}')

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

--force skips the destructive-action confirmation prompt. Always pair it with a prior get for safety.

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

Use environment variables for credentials in CI

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

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

Pin command sequences to discovered IDs

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

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

Failure Handling

References

• Oodle CLI repo
• Oodle docs