Quickstart - oleander

Install the CLI

brew tap OleanderHQ/tap
brew install oleander-cli

Configure your API key

oleander configure --api-key <YOUR_API_KEY>

Get your API key from oleander settings.

Connect your agent

Add the oleander MCP server to your agent in one command:

Claude Code
Codex
Cursor
OpenCode

claude mcp add --transport http oleander https://oleander.dev/mcp

codex mcp add oleander --url https://oleander.dev/mcp

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "oleander": {
      "url": "https://oleander.dev/mcp"
    }
  }
}

Then authenticate:

agent mcp login oleander

opencode mcp add oleander --url https://oleander.dev/mcp
opencode mcp auth oleander

When prompted, complete the OAuth flow to authorize access with your oleander account.

From here, pick a path:

Agent
Spark
Observability
Lake

Verify the connection

Ask your agent to confirm it’s connected:

“Are you connected to oleander? Who am I authenticated as?”

The agent will call oleander_whoami and return your organization context.

Load the sample dataset

Download the sample Iris dataset and load it into your lake:Download iris_dataset.parquet

oleander lake upload --file iris_dataset.parquet --table default.iris

Run your first query

Now ask your agent:

“What’s the average petal length in the iris dataset, broken down by species?”

The agent will call oleander_list_catalogs to find your tables, then oleander_query_lake to run the query - picking the right engine without you specifying it:

SELECT species, AVG(petal_length) AS avg_petal_length
FROM oleander.default.iris
GROUP BY species
ORDER BY avg_petal_length DESC;

From here, your agent can submit Spark jobs, trace lineage, investigate failures, and break down costs. See the MCP tools reference for the full list of what it can do.

Initialize a workspace

Create a new PySpark job workspace:

oleander spark init my-job
cd my-job

The workspace includes entrypoint.py, a mylib/ package directory, and a Makefile for building deployable artifacts.Install dependencies and build:

uv sync --dev
make

This produces out/pyfiles.zip and out/environment.tar.gz for upload.

Upload and submit

Upload your entrypoint and dependencies, then submit a run:

oleander spark jobs upload entrypoint.py \
  --py-files out/pyfiles.zip \
  --virtualenv out/environment.tar.gz

oleander spark jobs submit entrypoint.py \
  --namespace my-namespace \
  --name my-first-job \
  --wait

When the run finishes, open Runs in the oleander app to inspect timing, lineage, and cost attribution.

Verify credentials

Confirm your credentials work by listing your catalogs:

oleander catalogs list

This should return the oleander managed catalog and any others you have connected.

Send a lineage event

Send your first lineage event via curl or Python. Replace [OLEANDER-API-KEY] with your API key.

curl -X POST https://oleander.dev/api/v1/lineage \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer [OLEANDER-API-KEY]' \
  -d '{
    "eventType": "START",
    "eventTime": "2026-06-09T05:45:18.249Z",
    "run": {
      "runId": "e05c7916-6cbb-470e-b13b-25af0a757eac"
    },
    "job": {
      "namespace": "my-namespace",
      "name": "my-job"
    },
    "inputs": [{
      "namespace": "my-namespace",
      "name": "my-input"
    }],
    "producer": "https://github.com/OpenLineage/OpenLineage/blob/v1-0-0/client",
    "schemaURL": "https://openlineage.io/spec/1-0-5/OpenLineage.json#/definitions/RunEvent"
  }'

import requests

headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer [OLEANDER-API-KEY]',
}

json_data = {
    'eventType': 'START',
    'eventTime': "2026-06-09T05:45:18.249Z",
    'run': {
        'runId': 'e05c7916-6cbb-470e-b13b-25af0a757eac',
    },
    'job': {
        'namespace': 'my-namespace',
        'name': 'my-job',
    },
    'inputs': [
        {
            'namespace': 'my-namespace',
            'name': 'my-input',
        },
    ],
    'producer': 'https://github.com/OpenLineage/OpenLineage/blob/v1-0-0/client',
    'schemaURL': 'https://openlineage.io/spec/1-0-5/OpenLineage.json#/definitions/RunEvent',
}

response = requests.post('https://oleander.dev/api/v1/lineage', headers=headers, json=json_data)
print(response)

Navigate to the events tab to confirm the event arrived, making sure the date filter covers the eventTime above.

Query your telemetry

Every event lands in oleander.telemetry.run_events and is queryable immediately:

oleander query 'SELECT event_type, event_time, received_at, telemetry_correlation_id FROM oleander.telemetry.run_events LIMIT 10;'

Or run the same query from the lake UI:

SELECT event_type, event_time, received_at, telemetry_correlation_id FROM oleander.telemetry.run_events LIMIT 10;

Load a sample dataset

Download the sample Iris dataset and load it into your lake:Download iris_dataset.parquet

oleander lake upload --file iris_dataset.parquet --table default.iris

Query it

Once loaded, query it from the lake UI or via the CLI:

SELECT * FROM oleander.default.iris LIMIT 10;

For a full walkthrough of uploading data, syncing from S3, and running scheduled queries, see the DuckDB guide.

​Install the CLI

​Configure your API key

​Connect your agent

​Verify the connection

​Load the sample dataset

​Run your first query

​Initialize a workspace

​Upload and submit

​Verify credentials

​Send a lineage event

​Query your telemetry

​Load a sample dataset

​Query it