Intro

The oleander CLI lets you manage Spark artifacts and jobs, run SQL queries against the lake, browse catalogs, register infrastructure, and launch a DuckDB terminal from the command line. Queries go through the query router, so the CLI picks the engine and machine size for you.

Installation

macOS
Linux
Windows

curl -fsSL https://oleander.dev/install.sh | sh

brew tap OleanderHQ/tap
brew install oleander-cli

npm install -g oleander-cli

The install script puts a standalone oleander binary in ~/.oleander/bin and adds it to your PATH, so Node.js is not required. Re-run the script, or run oleander upgrade, to upgrade.

curl -fsSL https://oleander.dev/install.sh | sh

sudo apt-get update
sudo apt-get install -y curl ca-certificates gnupg

curl -fsSL https://oleander-cli-releases.s3.amazonaws.com/keys/oleander-archive-keyring.gpg \
  | sudo tee /usr/share/keyrings/oleander-archive-keyring.gpg >/dev/null

sudo tee /etc/apt/sources.list.d/oleander.sources >/dev/null <<'EOF'
Types: deb
URIs: https://oleander-cli-releases.s3.amazonaws.com/apt
Suites: stable
Components: main
Signed-By: /usr/share/keyrings/oleander-archive-keyring.gpg
EOF

sudo apt-get update
sudo apt-get install -y oleander-cli

npm install -g oleander-cli

The install script puts a standalone oleander binary in ~/.oleander/bin and adds it to your PATH, so Node.js is not required. Re-run the script, or run oleander upgrade, to upgrade. On Alpine and other musl distributions, install the C++ runtime first with apk add libstdc++ libgcc.

irm https://oleander.dev/install.ps1 | iex

scoop bucket add oleander https://github.com/OleanderHQ/scoop-bucket
scoop install oleander

npm install -g oleander-cli

The install script puts a standalone oleander.exe in ~\.oleander\bin and adds it to your user PATH, so Node.js is not required. Re-run the script, or run oleander upgrade, to upgrade. With Scoop, upgrade with scoop update oleander.

All install methods

Method	Platforms	Install
Install script	macOS, Linux	`curl -fsSL https://oleander.dev/install.sh \| sh`
PowerShell script	Windows	`irm https://oleander.dev/install.ps1 \| iex`
Homebrew	macOS	`brew tap OleanderHQ/tap && brew install oleander-cli`
APT	Ubuntu, Debian	Add the oleander repository, then `sudo apt-get install oleander-cli` (see the Linux tab)
Scoop	Windows	`scoop bucket add oleander https://github.com/OleanderHQ/scoop-bucket && scoop install oleander`
npm	Any OS with Node.js 18+	`npm install -g oleander-cli`
Standalone binaries	macOS, Linux, Windows	Download an archive for your platform from the releases bucket, with a `SHA256SUMS` file to check it against

The scripts, Scoop, and the standalone archives install a self-contained binary, so Node.js is only needed for the npm package.

Configuration

Authenticate with an API key from your oleander settings. Pass a profile name. In a terminal, the CLI prompts for the key and stores it in ~/.oleander/config.json. The first profile you configure becomes the current profile.

oleander configure --profile production

Outside a terminal, set OLEANDER_API_KEY or pipe the key on stdin:

OLEANDER_API_KEY=... oleander configure --profile ci

Configure one profile per organization or API key. Run oleander configure without --profile to update the current profile’s key.

oleander switch production                    # change the default profile
oleander whoami                               # show the current profile and organization
oleander query "SELECT 1" --profile sandbox   # use another profile for one command

Set OLEANDER_PROFILE to use a profile for a whole shell session.

Output format

Commands that print results accept -o, --output <format>: table (the default), json, or csv. Commands that don’t print rows, such as query submit, take table or json.

oleander catalogs list -o json
oleander query "SELECT * FROM oleander.default.flowers LIMIT 10" -o csv

Upgrade

Upgrade to the latest release:

oleander upgrade

Check whether an update is available without installing it:

oleander upgrade --check

Commands

General

Command	Description
`oleander configure`	Create or update a profile
`oleander switch`	Change the default profile
`oleander whoami`	Show the current profile and organization
`oleander upgrade`	Upgrade to the latest release

Lake

Command	Description
`oleander query`	Run a read against the lake; oleander picks the engine and machine size
`oleander query submit`	Run a query that writes - a `SELECT` plus `--destination`, or a statement that names its own target
`oleander polars`	Run a Polars SQL query or Python script against the lake
`oleander duckdb`	Launch a DuckDB terminal connected to your lake

Catalogs

Command	Description
`oleander catalogs list`	List registered catalogs
`oleander catalogs get`	Show a catalog’s type and settings
`oleander catalogs register`	Register an S3 Tables, Snowflake Horizon, or Confluent Tableflow catalog
`oleander catalogs credentials`	Get short-lived credentials for a catalog
`oleander catalogs namespaces list`	List namespaces in a catalog
`oleander catalogs namespaces create`	Create a namespace
`oleander catalogs tables list`	List tables in a namespace
`oleander catalogs tables describe`	Describe a table schema
`oleander catalogs tables create`	Create a new Iceberg table
`oleander catalogs tables delete`	Delete a table
`oleander catalogs tables load`	Load data from a file or URI into a new table
`oleander catalogs tables schema add`	Add columns to a table
`oleander catalogs tables schema rename`	Rename a column
`oleander catalogs tables schema drop`	Drop columns from a table

Spark

Command	Description
`oleander spark init`	Initialize a PySpark job workspace
`oleander spark jobs list`	List uploaded Spark artifacts
`oleander spark jobs upload`	Upload a Spark artifact
`oleander spark jobs get`	Download a Spark artifact’s source
`oleander spark jobs delete`	Delete a Spark artifact
`oleander spark jobs submit`	Submit a Spark job
`oleander spark jobs stop`	Stop a running Spark job
`oleander spark clusters list`	List registered Spark clusters
`oleander spark clusters register`	Register an external Spark cluster

Env

Command	Description
`oleander env list`	List organization environment variables (alias `ls`)
`oleander env set`	Set an environment variable; prompts for the value when omitted
`oleander env delete`	Delete an environment variable (alias `rm`)

Queries

Command	Description
`oleander queries list`	List saved queries
`oleander queries get`	Get a saved query by name
`oleander queries save`	Save a named query

See Spark, Lake, Polars, Env, and Queries for detailed usage.

Getting Started

Platform

IAM

Connections

Integrations

Coding with agents

CLI

External Compute

Installation

All install methods

Configuration

Output format

Upgrade

Commands

General

Lake

Catalogs

Spark

Env

Queries

​Installation

​All install methods

​Configuration

​Output format

​Upgrade

​Commands

​General

​Lake

​Catalogs

​Spark

​Env

​Queries

Installation

All install methods

Configuration

Output format

Upgrade

Commands

General

Lake

Catalogs

Spark

Env

Queries