Oodle CLI

Command-line interface for the Oodle observability platform.

oodle lets you manage monitors, notifiers, dashboards, synthetic monitors, log metrics, drop rules, API keys, users, and more from your terminal or CI pipeline. It is designed to be friendly for both humans (rich tables, prompts) and agents (deterministic JSON output, exit codes, env-based config).

brew tap oodle-ai/oodle
brew install oodle

To upgrade:

brew upgrade oodle

Pre-built binaries for macOS, Linux, and Windows are available on the Releases page. Download the archive for your platform, extract it, and place the oodle binary on your PATH.

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

This places the oodle binary in $(go env GOPATH)/bin. Make sure that directory is on your PATH.

git clone https://github.com/oodle-ai/oodle-cli.git
cd oodle-cli
make build
# Binary is written to ./bin/oodle
./bin/oodle version

# Configure (interactive)
oodle configure

# Or login with OAuth (interactive browser flow)
oodle auth login

# Or use environment variables
export OODLE_API_KEY="your-api-key"
export OODLE_INSTANCE="your-instance"

# List monitors
oodle monitors list

# Get JSON output
oodle monitors list -o json

oodle needs three things to talk to the API:

Each value can be provided via CLI flag, environment variable, or the config file. Resolution order (highest priority first):

1. CLI flags (--api-key, --instance, --api-url)
2. Environment variables (OODLE_API_KEY / OODLE_OAUTH_ACCESS_TOKEN, OODLE_INSTANCE, OODLE_DEPLOYMENT / OODLE_API_URL)
3. Config file at ~/.oodle/config.yaml
4. Built-in defaults (only for API URL)

The config file is created and managed by oodle configure.

Save credentials to ~/.oodle/config.yaml.

Interactive mode — run with no flags (or with some flags) in a TTY and oodle will prompt for any missing values:

oodle configure

Non-interactive mode — provide all values as flags and nothing is prompted:

oodle configure \
  --api-key "your-api-key" \
  --instance "your-instance" \
  --api-url "https://us1.oodle.ai"

Run browser-based OAuth login and save tokens to ~/.oodle/config.yaml. If an API key already exists in config, oodle asks whether to delete it. If both API key and OAuth token remain configured, OAuth is used. OAuth access tokens are refreshed automatically using the saved refresh token.

oodle auth login

Optional flags:

oodle auth login -d us1

The -d/--deployment flag accepts a deployment slug (us1, ap1, eu1) or a full deployment URL/host.

Clear saved OAuth credentials from ~/.oodle/config.yaml.

oodle auth logout

Show current auth configuration and precedence.

oodle auth status
oodle auth status -o json

Print the current OAuth access token (environment override first, then saved config). If the saved token has expired, the command returns an error and does not print it.

oodle auth token

~/.oodle/config.yaml:

api_key: your-api-key
instance: your-instance
api_url: https://us1.oodle.ai

The CLI is organized into resource groups. Use oodle <group> --help and oodle <group> <subcommand> --help for detailed flags on any command.

Aliases: monitor, mon.

| template-files | Create monitor template files |

oodle monitors list
oodle monitors get mon-abc123 -o json
oodle monitors create -f monitor.yaml
oodle monitors delete mon-abc123 --force
oodle monitors triggers -o json

Alias: notifier.

oodle notifiers list
oodle notifiers create -f slack-notifier.yaml

Aliases: np, notification-policy.

oodle np list -o json
oodle notification-policies get np-123

Aliases: mr, muting-rule.

oodle muting-rules list
oodle mr create -f muting-rule.yaml

Aliases: lm, logmetrics.

oodle log-metrics list
oodle lm create -f log-metric.yaml

Aliases: sm, synthetics.

oodle synthetic-monitors list
oodle sm run sm-123

Aliases: dashboard, dash.

oodle dashboards list
oodle dashboards create -f dashboard.json

Alias: folder.

oodle folders list

Aliases: dr, drop-rule.

oodle drop-rules list

Alias: metric. Inspect metrics, labels, and label values.

oodle metrics names -o json
oodle metrics labels http_requests_total
oodle metrics label-values http_requests_total status

Alias: trace. Query traces, trace labels, and label values.

oodle traces labels -o json
oodle traces list

Aliases: llmops, ai. The evaluation side of Agent Observability: versioned prompts, evaluation datasets, evaluators, scores, and experiment runs. Reading GenAI telemetry stays under oodle traces and oodle metrics.

Every create adds a version; applications resolve a prompt by label (production by default), so moving a label is how a new version is rolled out with no deploy.

oodle genai prompts get support-reply
oodle genai prompts label support-reply --version 4 --labels production

Aliases: dataset, ds. Datasets are versioned by time: items --at <RFC3339> recovers exactly the inputs a past experiment ran against.

oodle genai datasets create --name support-eval
oodle genai datasets items list support-eval --at 2026-08-01T00:00:00Z

A dataset carries at most one schedule, which runs its experiment without anyone starting it. set replaces the whole definition, and takes the same config flags as experiments run. Two shapes:

• calendar — --time HH:MM (repeatable) in --timezone, optionally narrowed by --weekday or --day-of-month. The times follow daylight saving rather than drifting twice a year.
• interval — --every 30m|6h|1d, at least 5m and at most 365d. No timezone applies to a duration.

A firing starts shortly after it is due rather than exactly on the minute, and a schedule that falls behind runs once instead of replaying every firing it missed.

# Every six hours.
oodle genai datasets schedule set support-eval --every 6h \
  --dataset-id "$DS" --connection-id "$CONN" \
  --prompt-name support-reply --model gpt-4o

# Weekday mornings, Los Angeles time.
oodle genai datasets schedule set support-eval \
  --time 09:00 --weekday monday --weekday friday \
  --timezone America/Los_Angeles --dataset-id "$DS" \
  --connection-id "$CONN" --prompt-name support-reply

# Keep the definition, stop it firing.
oodle genai datasets schedule set support-eval --enabled=false \
  --dataset-id "$DS" --connection-id "$CONN" \
  --prompt-name support-reply

Aliases: template, library. The judges themselves — what the UI calls Evaluations > Library, and the API calls eval-templates. list includes Oodle-managed templates (ids beginning oodle-managed-), which are read-only.

Three type values: llm (a judge prompt), code (a Python scorer), and output_comparer (a judge that scores the output against a dataset item's expected output, using {{output}} and {{expected_output}}). A comparer has ground truth only inside an experiment, so it never runs against live traffic.

Aliases: evaluator, eval-rules, rules. What makes a template run against live traffic — the UI's Evaluations > Evaluators, the API's evaluation-rules. An LLM template requires an llmConnectionId; the server rejects an evaluator with no model to call. Set samplingRate and maxInvocationsPerHour before enabling one on a busy service — an unsampled, uncapped rule is one model call per matching span.

list reports each rule's KIND — the type of the template it runs — so an output comparer can be told from an ordinary judge. --type narrows the list to one kind.

oodle genai evaluators update rule_123 --disable
oodle genai evaluators list --type output_comparer

Alias: score. Scores are read out of the trace store, so list defaults to the last 15 minutes; pass --start for anything older.

oodle genai scores list --name Hallucination --start -24h --max 0.5
oodle genai scores get "$SCORE_ID"

Aliases: experiment, runs, exp. A run is queued and picked up by a worker, so run returns as soon as the job exists.

Evaluators come in two kinds and each id goes in its own flag. An ordinary judge scores the generation on its own merits (--evaluator-id); an output comparer scores it against the dataset item's expected output (--output-comparer-id), and skips an item that has none. The server rejects an id put in the wrong flag.

An evaluator judges with the model its template names, falling back to the eval connection's default model. --evaluator-model overrides that for every evaluator given by flag — the way to judge with a cheaper model than you generate with, without defining a rule first.

oodle genai experiments run --dataset-id "$DS" --connection-id "$CONN" \
  --prompt-name support-reply --model gpt-4o \
  --evaluator-id oodle-managed-hallucination-v1 \
  --output-comparer-id oodle-managed-output-match-v1 \
  --evaluator-model gpt-4o-mini

Aliases: connection, conn. Provider credentials that evaluators and experiments call models through. Keys are encrypted at rest and never returned, so an update that omits --api-key leaves the stored key in place.

Aliases: ak, api-key.

oodle api-keys list

oodle users list -o json
oodle users invitations --help

Migrate a Grafana instance's dashboards, folders, data sources and alert rules into Oodle. The command runs entirely from your machine, so it works even when Grafana is only reachable locally (for example behind a VPN): it exports the assets from Grafana, uploads them to Oodle, and imports them.

# Full migration (export -> upload -> import)
oodle grafana migrate \
  --grafana-url https://grafana.internal.acme.com \
  --grafana-token <grafana-service-account-token>

# Only migrate dashboards carrying specific tags
oodle grafana migrate --grafana-url ... --grafana-token ... \
  --include-tags team-a,prod

# Export and upload only, then review and import from the Oodle UI
oodle grafana migrate --grafana-url ... --grafana-token ... --skip-import

Non-Prometheus data sources (CloudWatch, Cloud Monitoring, Athena, BigQuery, Azure Monitor, ...) are recreated in Oodle with their original IDs so your dashboards keep working; configure their credentials from the Oodle UI after migration. Prometheus panels are repointed at Oodle's built-in data source.

Use -o / --output to control how results are rendered.

If you do not pass --output, oodle picks a sensible default:

• Stdout is a terminal → table
• Stdout is a pipe or file → json

This means commands like oodle monitors list | jq Just Work without needing to pass -o json.

# Pretty table for humans
oodle monitors list

# JSON for jq / scripting
oodle monitors list -o json | jq '.[] | .id'

# YAML
oodle monitors list -o yaml

# CSV (first line is headers)
oodle monitors list -o csv > monitors.csv

oodle is designed to work well in non-interactive environments such as CI pipelines and AI agents.

• Configure with environment variables so you don't need a config file:

  export OODLE_API_KEY="$OODLE_API_KEY"
  export OODLE_INSTANCE="prod"
  export OODLE_DEPLOYMENT="https://us1.oodle.ai"

• Force JSON output for predictable parsing — either pass -o json or rely on auto-detection (stdout is not a TTY in CI, so JSON is the default).

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

• Exit codes:

  • 0 — success
  • non-zero — error (authentication failure, not-found, validation error, network error, etc.)

  Errors are written to stderr; structured output (when applicable) goes to stdout.

• Skip confirmation prompts for destructive operations with --force:

  oodle monitors delete mon-abc123 --force

• Pipe-friendly: when stdout is not a TTY, the default output format becomes JSON automatically. No interactive prompts are issued in non-interactive mode (the CLI errors out clearly instead).

Create / update commands accept a JSON or YAML file via -f / --file. The format is detected from the file extension (.json, .yaml, .yml).

# YAML
oodle monitors create -f monitor.yaml

# JSON
oodle dashboards create -f dashboard.json

# Update from a file
oodle log-metrics update -f log-metric.yaml

The same file format is used for all resource types that support create and update. Use oodle monitors template-files to generate starter templates for monitors.

This project uses Go and a simple Makefile. Common commands:

# Build the binary into ./bin/oodle
make build

# Run unit tests
make test

# Run integration tests (requires OODLE_API_KEY and OODLE_INSTANCE)
make test-integration

# Regenerate API client code (if specs change)
make generate

# Run linters
make lint

# Remove build artifacts
make clean

cmd/oodle/        # main entry point
internal/         # CLI commands, output formatting, client wiring
api/              # OpenAPI specs
test/             # integration tests (build tag: integration)

Releases are automated via GoReleaser and GitHub Actions. To cut a new release:

git tag v0.1.0
git push origin v0.1.0

This triggers the release workflow which:

1. Builds cross-platform binaries (macOS/Linux/Windows, amd64/arm64)
2. Creates a GitHub Release with the binaries and checksums
3. Updates the Homebrew formula in oodle-ai/homebrew-oodle

Prerequisites (one-time setup):

1. Create the oodle-ai/homebrew-oodle repository with an empty Formula/ directory.
2. Create a GitHub Personal Access Token for GoReleaser to push the formula update. Prefer a fine-grained PAT scoped only to the oodle-ai/homebrew-oodle repository with Contents: Read and write permission. A classic PAT with repo scope also works but grants broader access than necessary.
3. Add the token as a repository secret named HOMEBREW_TAP_GITHUB_TOKEN in the oodle-cli repo settings.

Integration tests live under test/ and are gated by the integration build tag. They will skip automatically if OODLE_API_KEY or OODLE_INSTANCE are not set:

OODLE_API_KEY=... OODLE_INSTANCE=... \
  go test -tags integration -v -count=1 ./test/...

See LICENSE.