CLI reference¶
Every dlt-ops command and option, generated from the CLI itself — this page and dlt-ops <command> --help render the same text. The project root comes from the top-level --root option, or is found by walking up from the working directory to the nearest .dlt/config.toml. For task-shaped walkthroughs, start from the guides; for the config keys these commands read, see the config reference.
dlt-ops¶
dlt-ops — opinionated project layout and toolchain for dlt pipelines.
Usage:
Options:
--version Show the version and exit.
-r, --root DIRECTORY Project root (holds .dlt/config.toml). Default: walk
up from cwd.
--help Show this message and exit.
dlt-ops checkpoints¶
Manage checkpoints for dlt pipelines.
Usage:
Options:
dlt-ops checkpoints cleanup¶
Delete completed checkpoints for a pipeline or resource.
Active rows are live resume state and are kept unless --include-active is passed; deleting one restarts that resource at its window start.
Examples: dlt-ops checkpoints cleanup --pipeline my_api_pipeline dlt-ops checkpoints cleanup --pipeline my_api_pipeline --resource orders dlt-ops checkpoints cleanup --pipeline my_api_pipeline --include-active
Usage:
Options:
-p, --pipeline TEXT The dlt pipeline_name (source <X> runs as
'<X>_pipeline'), not the dlt-ops source name.
[required]
-r, --resource TEXT Resource name (optional, cleans all resources if not
specified)
-t, --table TEXT Checkpoint table name
--include-active Also delete active rows — live resume state. Affected
resources restart at their window start.
--help Show this message and exit.
dlt-ops checkpoints list¶
List checkpoints for a pipeline.
Examples: dlt-ops checkpoints list --pipeline my_api_pipeline dlt-ops checkpoints list --pipeline my_api_pipeline --format json
Usage:
Options:
-p, --pipeline TEXT The dlt pipeline_name (source <X> runs as
'<X>_pipeline'), not the dlt-ops source name.
[required]
-t, --table TEXT Checkpoint table name
-f, --format [table|json] Output format
--help Show this message and exit.
dlt-ops init¶
Scaffold a dlt-ops project at ROOT (default: current directory).
Creates the project marker (.dlt/config.toml with a [dlt_ops] table), an empty .dlt/secrets.toml, and one starter pipeline directory with the mandatory source/ and resource/ subdirectories.
Examples: dlt-ops init dlt-ops init demo --pipeline web_events dlt-ops init demo --example
Usage:
Options:
-p, --pipeline TEXT Name of the starter pipeline directory. [default:
my_pipeline]
--example Add a runnable fixture-based example source (inline
rows, local DuckDB, no network).
--help Show this message and exit.
dlt-ops pipeline¶
Manage dlt pipelines - discover, run, validate.
The project root comes from the top-level --root option (or is found by walking up from cwd to the nearest .dlt/config.toml).
Usage:
Options:
dlt-ops pipeline backfill¶
Backfill a source over [--from, --to) in sequential chunks.
Each chunk runs the pipeline with injected [chunk_from, chunk_to) bounds and writes its own _dlt_ops_runs row. Progress is tracked in _dlt_backfills on the source's own destination: re-running the same --from/--to/--chunk triple skips completed chunks, retries failed ones, and continues pending ones. Concurrent invocations coordinate via the state table — every chunk executes exactly once.
Exit code 0 means this invocation covered every chunk of the window (completed here, or already completed by an earlier run). Chunks another worker holds are reported and exit non-zero: they did not run here, so this invocation cannot vouch for the window.
Timestamps must carry an explicit timezone offset (naive inputs are rejected); the source's selected resources must declare an incremental cursor, or the injected bounds would be silently ignored; and the destination must have a registered DestinationAdapter — chunk state is adapter-gated, so a core-mode destination is refused before anything runs.
Examples: dlt-ops pipeline backfill github_events --from 2024-01-01T00:00:00Z --to 2025-01-01T00:00:00Z --chunk 7d dlt-ops pipeline backfill my_api --from 2024-06-01T00:00:00+00:00 --to 2024-06-02T00:00:00+00:00 --chunk 6h
Usage:
Options:
--from TIMESTAMP Window start, inclusive. ISO-8601 with explicit timezone
offset; normalized to UTC. [required]
--to TIMESTAMP Window end, exclusive ([from, to)). ISO-8601 with explicit
timezone offset. [required]
--chunk INTERVAL Chunk size: simple <N>d / <N>h / <N>m forms only (e.g. 7d,
24h, 30m). [required]
--help Show this message and exit.
dlt-ops pipeline clean¶
Clean pipeline state and data tables.
Works without local state (identifies tables from the destination schema or source discovery).
Examples: dlt-ops pipeline clean -s my_api dlt-ops pipeline clean -s my_api -r orders dlt-ops pipeline clean -s my_api --local-only --auto-approve dlt-ops pipeline clean -s my_api --dry-run
Usage:
Options:
-s, --source TEXT Source name to clean [required]
-r, --resource TEXT Specific resources (default: all)
--local-only Clean local cache only
--remote-only Clean remote destination tables only
--dataset TEXT Dataset override. Default: resolved from
.dlt/config.toml
--auto-approve Skip confirmation (for programmatic runs)
--dry-run Show what would be cleaned without executing
--help Show this message and exit.
dlt-ops pipeline list¶
List available dlt sources.
Uses the Phase-1 static scan: source modules are never imported, so a
module-level side effect (or bug) cannot fire here. Resource counts come
from the static approximation; validate/run resolve the live list.
Examples: dlt-ops pipeline list dlt-ops pipeline list --schedule @daily dlt-ops pipeline list --json
Usage:
Options:
-s, --schedule TEXT Filter by schedule (@hourly, @daily, etc.)
--json Output as JSON
--help Show this message and exit.
dlt-ops pipeline reconcile¶
Detect schema drift (live destination schema vs declared model).
The default scan is additive: columns present in the destination that the declared Pydantic model doesn't know about. --include-removal adds the removal scan — a windowed non-null-coverage diff that catches model columns whose data went dark; it needs [dlt_ops] load_timestamp_column as the time axis and is skipped with a warning when that key is unset.
Runs against every source regardless of contract mode. Drifted resources surface an alert event (fingerprint ["schema-drift", pipeline, source, resource]; additive + removal on one resource collapse into one issue) unless --dry-run is set.
Examples: dlt-ops pipeline reconcile -s github_events dlt-ops pipeline reconcile --all dlt-ops pipeline reconcile --all --include-removal dlt-ops pipeline reconcile -s github_events --dry-run dlt-ops pipeline reconcile --all --dry-run
Usage:
Options:
-s, --source TEXT Source name to reconcile
--all Reconcile every discovered source
--include-removal Also run removal-drift detection (needs [dlt_ops]
load_timestamp_column)
--dry-run Skip alert emission; print findings only
--help Show this message and exit.
dlt-ops pipeline resources¶
List resources for a source.
Uses the Phase-1 static scan: source modules are never imported. The
resource list is a static approximation (declared @dlt.resource
functions); dynamically built resources resolve in validate/run.
Examples: dlt-ops pipeline resources -s github_events dlt-ops pipeline resources -s my_api --json dlt-ops pipeline resources # interactive selection
Usage:
Options:
-s, --source TEXT Source name (interactive if not provided)
--json Output as JSON
--help Show this message and exit.
dlt-ops pipeline run¶
Run a dlt pipeline.
Examples: dlt-ops pipeline run -s github_events dlt-ops pipeline run -s my_api -r orders -r customers dlt-ops pipeline run -s github_events --dataset raw_events dlt-ops pipeline run -s my_api -n 4 -f 1000000 dlt-ops pipeline run -s my_api -l 2 # reduce load workers dlt-ops pipeline run -I # interactive mode dlt-ops pipeline run -s github_events -y # non-interactive (for scripts)
Usage:
Options:
-s, --source TEXT Source name (required in non-interactive
mode)
-r, --resource TEXT Resource(s) to run. Omit for all.
-d, --dataset TEXT Dataset override. Default: resolved from
.dlt/config.toml
-n, --normalize-workers INTEGER
Parallel normalize workers. Unset:
config.toml, else 4 on DuckDB
-l, --load-workers INTEGER Parallel load workers. Unset: config.toml,
else 3 on DuckDB
-f, --file-max-items INTEGER Max rows per normalized file
-I, --interactive Interactive resource selection
-y, --yes Non-interactive mode, skip confirmations
--help Show this message and exit.
dlt-ops pipeline status¶
Show recent runs per source from the _dlt_ops_runs ledger.
The ledger lives where the data lands: one table per destination + dataset, written at every run/backfill start and end. Sources that never ran (no ledger table yet) are listed with no runs; a ledger the CLI cannot read (unresolved destination/dataset, unreachable destination) is reported as "ledger unreadable" with the reason; a destination with no DestinationAdapter runs in core mode — no ledger can exist there, so it is reported as "ledger unsupported" (a capability fact, not a fault). The verb itself never fails on a broken ledger path. Note the ledger is written best-effort: a run whose ledger write failed is a real run with no row here.
--json emits one object per source, keys stable across states: {"source", "ledger" ("ok"|"missing"|"unreadable"|"unsupported"), "error" (the unreadable/unsupported reason), "runs"}.
Examples: dlt-ops pipeline status dlt-ops pipeline status --resource orders dlt-ops pipeline status --limit 5 --json
Usage:
Options:
-r, --resource TEXT Only runs scoped to this resource
-n, --limit INTEGER RANGE Last N runs per source [default: 10; x>=1]
--json Output as JSON
--help Show this message and exit.
dlt-ops pipeline validate¶
Validate the project against the rule framework.
Runs the resolved rule set over the discovered sources and
.dlt/config.toml (config sections, schedules, schema contracts, naming,
column hints, ...). Rules resolve from the registry defaults overlaid by
[dlt_ops.rules] (missing = on, false = off; unknown rule IDs are
errors); per-source exemptions live in
[sources.
Examples: dlt-ops pipeline validate dlt-ops pipeline validate --strict dlt-ops pipeline validate --json dlt-ops pipeline validate --show-resolved-rules
Usage:
Options:
--strict Treat warnings as errors
--json Output as JSON
--show-resolved-rules Print every known rule with resolved on/off state and
origin, then exit
--help Show this message and exit.
dlt-ops plugins¶
Inspect the plugin registry.
Usage:
Options:
dlt-ops plugins doctor¶
Report every plugin axis: registered plugins, load failures, collisions.
Exits 0 when every discovered plugin loads cleanly and no <axis>/<name>
is contested; exits 1 otherwise (CI-usable).
Usage:
Options: