CLI Reference

Every command in one page

One binary. These are the commands.

Overview

Three core commands:

Command	What it does
`run`	Execute your pipeline
`sandbox`	Preview changes safely
`daemon`	Collect events via HTTP

Everything else is optional.

Most Common Commands

ondatrasql run                    # Run your entire pipeline
ondatrasql sandbox                # Preview before committing
ondatrasql run staging.orders     # Run a single model
ondatrasql sql "SELECT * FROM staging.orders LIMIT 10"

Example Workflow

# 1. Create a model
ondatrasql new staging/orders.sql

# 2. Edit it
ondatrasql edit staging.orders

# 3. Preview changes
ondatrasql sandbox

# 4. Run pipeline
ondatrasql run

# 5. Query results
ondatrasql sql "SELECT * FROM staging.orders"

Core Commands

run

Run your entire pipeline in one command.

ondatrasql run                    # All models in DAG order
ondatrasql run staging.orders     # Single model

What it does:

Builds the DAG automatically
Detects what changed
Runs only what’s needed
Writes results to DuckLake

No configuration required.

sandbox

Preview all changes before committing.

ondatrasql sandbox                # All models
ondatrasql sandbox staging.orders # One model

Shows row count diffs, schema evolution, downstream propagation — without touching production. See Sandbox Mode.

daemon

Start the event collection endpoint.

COLLECT_PORT=8080 ondatrasql daemon

Receives events via HTTP, buffers them durably on disk. ondatrasql run flushes them to DuckLake.

# Custom ports
COLLECT_PORT=9090 COLLECT_ADMIN_PORT=9091 ondatrasql daemon

See Event Collection.

Development

init

Create a new project in the current directory.

ondatrasql init

new

Create a model file.

ondatrasql new staging/orders.sql
ondatrasql new raw/api_users.star
ondatrasql new raw/gam_report.yaml

edit

Open in $EDITOR.

ondatrasql edit staging.orders    # Model
ondatrasql edit env               # .env
ondatrasql edit catalog           # config/catalog.sql
ondatrasql edit macros            # config/macros.sql
ondatrasql edit secrets           # config/secrets.sql
ondatrasql edit settings          # config/settings.sql
ondatrasql edit variables         # config/variables.sql
ondatrasql edit sources           # config/sources.sql
ondatrasql edit extensions        # config/extensions.sql

Querying

sql

Run arbitrary SQL — no external database required.

ondatrasql sql "SELECT COUNT(*) FROM staging.orders"
ondatrasql sql "SELECT * FROM staging.orders" --format json

query

Query a table directly.

ondatrasql query staging.orders
ondatrasql query staging.orders --limit 10 --format csv

Supports --format csv|json|markdown and --limit N.

Introspection

stats

Project overview — all models, kinds, status.

ondatrasql stats

history

Run history for a model.

ondatrasql history staging.orders
ondatrasql history staging.orders --limit 5

describe

Schema, dependencies, directives, SQL definition.

ondatrasql describe staging.orders

lineage

Column-level lineage extracted from SQL AST.

ondatrasql lineage overview           # All models
ondatrasql lineage staging.orders     # One model
ondatrasql lineage staging.orders.total  # One column

Automation

–json

Machine-readable output. Use it for CI/CD, alerts, or orchestrator integration.

ondatrasql run --json 2>/dev/null | jq -s '.'

Every model emits one JSON object:

{
  "model": "staging.orders",
  "kind": "table",
  "run_type": "incremental",
  "rows_affected": 42,
  "duration_ms": 567,
  "status": "ok"
}

Field	Description
`model`	Target table
`kind`	`table`, `view`, `append`, `merge`, `scd2`, `partition`, `events`
`run_type`	`skip`, `backfill`, `incremental`, `full`, `create`, `flush`
`run_reason`	Why this run type was chosen
`rows_affected`	Rows written (0 for skip)
`duration_ms`	Execution time
`status`	`ok` or `error`
`errors`	Error messages (when `status` is `error`)
`warnings`	Warnings (schema evolution, validation)

version

ondatrasql version

Maintenance

DuckLake file management. All support sandbox to preview.

ondatrasql merge                  # Merge small Parquet files
ondatrasql expire                 # Expire old snapshots
ondatrasql cleanup                # Delete unreferenced files
ondatrasql orphaned               # Delete orphaned files

Preview first:

ondatrasql merge sandbox
ondatrasql expire sandbox

Building from Source

Requires Go 1.25+ and a C compiler (gcc or clang) for the embedded DuckDB driver.

go install github.com/ondatra-labs/ondatrasql/cmd/ondatrasql@latest

If you see cgo: C compiler not found:

# Ubuntu/Debian
sudo apt install build-essential

# macOS
xcode-select --install