CLI Reference

On this page

Single binary. All commands listed below.

Commands

Command	Description
`run`	Execute the pipeline
`sandbox`	Preview changes before committing
`schedule`	Install OS-native scheduler
`events`	Start event collection endpoint
`odata`	Start OData v4 server
`init`	Create a new project
`new`	Create a model file
`edit`	Open file in $EDITOR
`sql`	Run arbitrary SQL
`query`	Query a table directly
`stats`	Project overview
`history`	Run history for a model
`describe`	Model details and schema
`lineage`	Column-level lineage
`auth`	OAuth2 provider management
`checkpoint`	Run all maintenance
`flush`	Flush inlined data to Parquet
`merge`	Merge small Parquet files
`expire`	Expire old snapshots
`cleanup`	Delete unreferenced files
`orphaned`	Delete orphaned files
`rewrite`	Rewrite files with many deletes
`--json`	Machine-readable output
`version`	Print version

run

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

sandbox

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

See Preview Changes.

schedule

ondatrasql schedule "*/5 * * * *"   # Install (auto-detects OS)
ondatrasql schedule                 # Show status
ondatrasql schedule remove          # Remove

OS	Backend
Linux	systemd user timer
macOS	launchd plist
Windows	WSL2

See Schedule Pipeline Runs.

events

ondatrasql events 8080            # Public on 8080, admin on 8081

Admin endpoint runs on port + 1 (localhost-only).

See Collect Events.

odata

ondatrasql odata 8090

Serves @expose models at http://127.0.0.1:<port>/odata.

See Serve Data via OData.

init

ondatrasql init

new

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

edit

ondatrasql edit staging.orders      # Model
ondatrasql edit env                 # .env
ondatrasql edit catalog             # config/catalog.sql
ondatrasql edit macros/audits       # config/macros/audits.sql
ondatrasql edit macros/constraints  # config/macros/constraints.sql
ondatrasql edit macros/warnings     # config/macros/warnings.sql
ondatrasql edit macros/helpers      # config/macros/helpers.sql
ondatrasql edit macros/masking      # config/macros/masking.sql
ondatrasql edit variables/constants # config/variables/constants.sql
ondatrasql edit variables/global    # config/variables/global.sql
ondatrasql edit variables/local     # config/variables/local.sql
ondatrasql edit secrets             # config/secrets.sql
ondatrasql edit settings            # config/settings.sql
ondatrasql edit sources             # config/sources.sql
ondatrasql edit extensions          # config/extensions.sql

sql

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

query

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

Flag	Description
`--format`	`csv`, `json`, `markdown`
`--limit`	Maximum rows returned

stats

ondatrasql stats

history

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

describe

ondatrasql describe staging.orders

lineage

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

See Lineage & Metadata.

auth

ondatrasql auth                   # List providers
ondatrasql auth google-sheets     # Authenticate
ondatrasql auth fortnox           # Authenticate

Mode	Detected by	Description
Managed	`ONDATRA_KEY` in `.env`	Uses oauth2.ondatra.sh, no app registration
Local	`<PREFIX>_CLIENT_ID` in `.env`	Uses your own OAuth2 credentials

Tokens are stored in .ondatra/tokens/ and auto-refresh on every pipeline run.

See Environment Variables for OAuth2 variable reference.

–json

Machine-readable output on stdout. Human output redirected to stderr.

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

Field	Description
`model`	Target table
`kind`	`table`, `append`, `merge`, `scd2`, `partition`, `tracked`, `events`
`run_type`	`skip`, `backfill`, `incremental`, `full`, `create`
`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

ondatrasql checkpoint             # Run all maintenance in order
ondatrasql flush                  # Flush inlined data to Parquet
ondatrasql merge                  # Merge small Parquet files
ondatrasql expire                 # Expire old snapshots
ondatrasql cleanup                # Delete unreferenced files
ondatrasql orphaned               # Delete orphaned files
ondatrasql rewrite                # Rewrite files with many deletes

See Maintain DuckLake Storage.