Oodle Onboarding — Integration Setup

Integrate infrastructure with the Oodle observability platform using

oodle integrations

commands. Actively discover the environment to recommend integrations and adapt setup steps. The setup spec is a blueprint — it defines the approach and parameters, but execution adapts based on what the codebase and environment reveal.

Prerequisites

Before starting any onboarding work, verify the Oodle CLI is installed and authenticated. Run these checks at the beginning of every session:

Step 1: Check if the CLI is installed

bash

oodle version

If the command is not found, install it:

bash

brew install oodle-ai/oodle/oodle

brew

is not available, fall back to:

bash

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

Step 2: Check if the CLI is authenticated

bash

oodle auth status

If not authenticated or the status shows an error, run interactive login:

bash

oodle auth login

This opens a browser for OAuth login. The user must complete the browser flow — prompt them to do so and wait for confirmation. After login succeeds, verify with

oodle auth status

Note:

oodle integrations list-setup-specs

and

oodle integrations get-setup-spec

do NOT require authentication. Use these to discover available integrations and fetch setup instructions even before auth is configured. All other integration commands require valid credentials — complete the auth steps above before proceeding past step 2 in the Command Execution Order.

Command Execution Order

Follow this sequence for every integration onboarding request:

Identify the integration type. If the user named one (e.g., "kubernetes", "aws-cloudwatch"), use it. Otherwise, run environment discovery to detect present infrastructure and recommend matching integrations (see
```
references/environment-discovery.md
```
).
Fetch available setup specs — run
```
oodle integrations list-setup-specs -o json
```
(no auth required) to confirm the type exists and cross-reference against discovery results.
Fetch integration records — run
```
oodle integrations list -o json
```
to extract: (a) the
```
type
```
field (lowercase it for step 4), (b)
```
apiKey
```
, (c)
```
collectorDomain
```
/
```
logsCollectorDomain
```
for helm values, (d) instance ID from the domain pattern. Requires authentication — if not configured, complete Prerequisites steps 1–2 first.
Fetch the setup spec — run
```
oodle integrations get-setup-spec <type-lowercase> -o json
```
. This is the blueprint for integration, not a rigid script. It defines the general approach, required tools, and parameters.
Discover the environment in depth — probe the codebase, running services, and existing configs. Use findings to resolve parameters and adapt the spec's steps (see
```
references/environment-discovery.md
```
).
Collect remaining parameters — after discovery, ask the user for anything that could not be auto-detected. Group questions together.
Execute the setup — work through the spec's steps, adapting each one based on discovery results. Confirm with the user before every non-read-only command. Review
```
references/gotchas.md
```
before executing.
Validate the integration — run
```
oodle integrations list -o json
```
and check the status.
Verify data presence on the Oodle side (see
```
references/post-install-validation.md
```
).

For failure scenarios, consult

references/failure-handling.md

Quick Reference

Task	Command	Auth required?
Discover available setup specs	`oodle integrations list-setup-specs -o json`	No
Discover available setup specs (table)	`oodle integrations list-setup-specs`	No
Get setup spec	`oodle integrations get-setup-spec <type> -o json`	No
Get setup spec (YAML)	`oodle integrations get-setup-spec <type> -o yaml`	No
List configured integrations	`oodle integrations list -o json`	Yes
List configured integrations (table)	`oodle integrations list`	Yes

Aliases:

oodle integration

oodle integ

Common Operations

Discovering available integration types

bash

# CORRECT — discover all types with setup specs (no auth required)
oodle integrations list-setup-specs -o json

# CORRECT — table output for display (no auth required)
oodle integrations list-setup-specs

# WRONG — guessing integration types without checking
oodle integrations get-setup-spec some-random-type -o json

Listing configured integrations

bash

# CORRECT — check which integrations are already configured (requires auth)
oodle integrations list -o json

# CORRECT — table output for display
oodle integrations list

Fetching a setup spec

bash

# CORRECT — fetch spec for a known type (no auth required)
oodle integrations get-setup-spec kubernetes -o json

# WRONG — hardcoding setup steps instead of fetching the spec
kubectl apply -f https://some-hardcoded-url/oodle-collector.yaml

Executing setup steps (adapting the blueprint)

The spec defines what needs to happen. Discover the current state before each step and adapt:

bash

# CORRECT — check existing state, then adapt
kubectl get namespace oodle-system 2>/dev/null && echo "Already exists, skipping" || kubectl create namespace oodle-system

# CORRECT — existing release? upgrade instead of install
helm list -n oodle-system | grep oodle && helm upgrade ... || helm install ...

# CORRECT — show the command and ask for confirmation before running
echo "I will run: kubectl create namespace oodle-system"
# [wait for user confirmation]
kubectl create namespace oodle-system

# WRONG — blindly running spec commands without checking existing state
kubectl create namespace oodle-system  # fails if already exists

# WRONG — running destructive commands without confirmation
kubectl delete namespace oodle-system

Validating the integration

bash

# CORRECT — check integration status after setup
oodle integrations list -o json

# CORRECT — check pods are running (for Kubernetes integrations)
kubectl get pods -n oodle-system

# WRONG — assuming success without verification
echo "Integration complete!"

Best Practices

Always fetch the latest setup spec

Run

oodle integrations get-setup-spec <type> -o json

at the start of every onboarding session. Never cache or reuse a previously fetched spec — requirements and steps change as the platform evolves. Treat the spec as a blueprint: it defines what needs to happen and what parameters are required, but adapt the exact commands and values based on environment discovery.

Resolve parameters by discovery first, ask second

Collect all required parameters before starting execution. Check these sources in order:

Environment discovery — probe actively:
```
kubectl config current-context
```
for cluster name,
```
helm list
```
for existing releases, process lists for running collectors, config files in the codebase for endpoints, env vars for API keys.
The user's request — the user may have specified values in the prompt.
Ask the user — only for what could not be auto-detected. Group remaining questions together.

Confirm before creating or modifying resources

Show the command to be run and wait for user confirmation before executing any command that creates, modifies, or deletes resources. Read-only commands (list, get, describe) do not need confirmation. Redact secrets in the displayed command — show the redacted version for confirmation, then run the unredacted version internally. For commands that require secret values (e.g.,

helm install --set apiKey=...

), prefer passing secrets via temp files, stdin, or environment variables rather than command-line arguments to avoid shell history exposure.

Handle existing resources gracefully

If a resource already exists (namespace, Helm release, ConfigMap), skip the creation step and note it was already present. Do not fail or attempt to delete and recreate.

Redact secrets in output

Never display full API keys, tokens, or passwords. Show only the first and last 4 characters (e.g.,

oodl...k9x2

). When rendering config templates from the spec, redact secret values before showing to the user.

One step at a time

Execute setup steps sequentially. Verify each step succeeded before moving to the next. If a step fails, diagnose the issue and suggest a fix — do not continue to the next step.

Present a summary when done

After all steps complete and validation passes, present a summary:

Integration type and name
What was installed/configured
Current status
How to check status later (
```
oodle integrations list
```
)

References

```
references/environment-discovery.md
```
— infrastructure detection and setup step adaptation
```
references/gotchas.md
```
— critical gotchas to review before executing setup
```
references/post-install-validation.md
```
— verifying data presence with query skills
```
references/failure-handling.md
```
— troubleshooting common failure scenarios
Oodle CLI repo — source of the
```
oodle
```
binary
Oodle docs — product documentation
oodle-cli skill — core CLI usage, auth, output formats

oodle-onboarding

NPX Install

Tags

SKILL.md Content

Oodle Onboarding — Integration Setup

Prerequisites

Step 1: Check if the CLI is installed

Step 2: Check if the CLI is authenticated

Command Execution Order

Quick Reference

Common Operations

Discovering available integration types

Listing configured integrations

Fetching a setup spec

Executing setup steps (adapting the blueprint)

Validating the integration

Best Practices

Always fetch the latest setup spec

Resolve parameters by discovery first, ask second

Confirm before creating or modifying resources

Handle existing resources gracefully

Redact secrets in output

One step at a time

Present a summary when done

References