cli-reference.md

title	CLI reference
description	Every dre command, subcommand and flag, with defaults and environment variables.
section	reference
position	1

CLI reference

Every dre command and flag. dre <command> --help prints the same text. Every command exits with one of the documented exit codes; each problem it reports has an error code. Settings that also come from the environment are listed with their variable; every variable is on the environment variables page.

Global options

These work with every command.

Option	Default	Description
-v, --verbose		Show every step (same as --log-level debug).
-q, --quiet		Only show errors and the final summary.
--log-level <LOG_LEVEL>		How much to show. One of quiet, info, debug.
--log-format <LOG_FORMAT>	text	text for people, json (one object per line) for CI and tooling. One of text, json.
--color <COLOR>	auto	Colour output: auto (default; off when NO_COLOR is set or output isn't a terminal), always or never. One of auto, always, never.

dre validate

Check the project (config, references, templates, schedules) and compile its SQL.

dre validate [OPTIONS] [SELECTOR]...

Argument	Description
SELECTOR...	Which reports to compile and check (same selectors as dre run; default: all). With a selector, validate also shows where each selected Binding's output would go. Reports whose templates query the database (run_query(), columns()) connect, and may sign in, to compile.

Option	Default	Description
-s, --select <SELECTOR>		What to select (dbt's --select): report names, tag:<tag>, folder names or dotted folder paths. Several match any of them: -s a b, -s a,b, -s a -s b (or "a;b").
--project-dir <PROJECT_DIR>	.	Project directory (default: the current directory).
--profiles-dir <PROFILES_DIR>		Directory holding profiles.yml (default: $DRE_PROFILES_DIR, then the project directory if it has a profiles.yml, then ~/.dre). Environment: DRE_PROFILES_DIR.
--no-auto-install		Fail instead of installing declared plugins that are missing.
--target <TARGET>		The run's target (environment), target.name in templates: every profile uses its entry for it (default: $DRE_TARGET; without either, each profile uses its own target:, else dev). Environment: DRE_TARGET.
--target-path <PATH>		Where DRE writes its generated files (default: $DRE_TARGET_PATH, then target_path in dre_project.yml, then target/). A local or mounted path, absolute or relative to the project root. Unrelated to --target. Environment: DRE_TARGET_PATH.
--var <NAME=VALUE>		Set a variable for var(), overriding every other level: --var name=value. The value is YAML 1.2 (false, 5, [a, b] are typed); quote it to keep text: --var x='"false"'.
--timezone <TIMEZONE>		The run's timezone (IANA name, e.g. Australia/Sydney), above every timezone: setting (default: $DRE_TIMEZONE). Environment: DRE_TIMEZONE.
--json		Emit machine-readable JSON instead of text.
--live		After the offline checks, connect to each Binding's source and check every rendered statement without executing it (EXPLAIN or the dialect's equivalent).
--set <SET>		Compile (and with --live, check) one Set instead of every Set.
--strict		Treat warnings as errors: exit 1 when there are any.
--all-targets		Check the connection settings of every entry in profiles.yml, not only the entries the selected reports would use with these flags.

Example:

dre validate --live monthly_revenue

dre run

Run reports: render, execute, format into the target folder, and deliver.

dre run [OPTIONS] [SELECTOR]...

Argument	Description
SELECTOR...	What to run: report names, tag:<tag>, folder names or dotted folder paths (dre run a b runs both). Runs every report when omitted.

Option	Default	Description
-s, --select <SELECTOR>		What to select (dbt's --select): report names, tag:<tag>, folder names or dotted folder paths. Several match any of them: -s a b, -s a,b, -s a -s b (or "a;b").
--project-dir <PROJECT_DIR>	.	Project directory (default: the current directory).
--profiles-dir <PROFILES_DIR>		Directory holding profiles.yml (default: $DRE_PROFILES_DIR, then the project directory if it has a profiles.yml, then ~/.dre). Environment: DRE_PROFILES_DIR.
--no-auto-install		Fail instead of installing declared plugins that are missing.
--target <TARGET>		The run's target (environment), target.name in templates: every profile uses its entry for it (default: $DRE_TARGET; without either, each profile uses its own target:, else dev). Environment: DRE_TARGET.
--target-path <PATH>		Where DRE writes its generated files (default: $DRE_TARGET_PATH, then target_path in dre_project.yml, then target/). A local or mounted path, absolute or relative to the project root. Unrelated to --target. Environment: DRE_TARGET_PATH.
--var <NAME=VALUE>		Set a variable for var(), overriding every other level: --var name=value. The value is YAML 1.2 (false, 5, [a, b] are typed); quote it to keep text: --var x='"false"'.
--timezone <TIMEZONE>		The run's timezone (IANA name, e.g. Australia/Sydney), above every timezone: setting (default: $DRE_TIMEZONE). Environment: DRE_TIMEZONE.
--set <SET>		Run one Set (declared or ad hoc), or all of a report's Sets.
--schedule <NAME>		Run the Bindings a schedules.yml entry targets, with its vars. Pass the scheduled instant through DRE_RUN_AT (or the date through DRE_RUN_DATE) so reruns render the same. With a selector and/or --set, run just those of its Bindings.
--profile <PROFILE>		Use this connection instead of the inherited one (report, Set, folder +profile, default_profile), e.g. for an ad hoc Set. A query's own profile: or a source's wins.
--output-name <OUTPUT_NAME>		Override the output file name for this run (the first output, with several).
--output-path <OUTPUT_PATH>		Override the full output (delivery) path for this run (the first output, with several).
--dry-run		Render SQL into target/compiled/ and stop; no report query is executed.
--no-deliver		Keep normal outputs locally without delivering them to any destination.
--output-json <DIR>		Write typed JSON rows per query and isolate this run's outputs/history in DIR.
--from-results <DIR>		Re-render the outputs from results saved with --output-json DIR, without running any query or opening a connection; implies --no-deliver. For designing a template.
--preview [<ROWS>]		Execute with a row limit (default 100); output stays in target/ and is never delivered.
--accept-schema-change		Deliver even if the output schema changed since the last successful run, and accept the new schema. Snapshots live in the target path, so a fresh CI runner has no history unless --target-path (or DRE_TARGET_PATH) points at a folder that persists.
--timeout <DURATION>		Stop the run if it takes longer than this: a duration such as 2h or 90m, or seconds (default: $DRE_RUN_TIMEOUT, then flags: run_timeout in dre_project.yml; off without any). Its Bindings are then recorded as timed_out, and dre exits 124.
--keep-runs <N>		How many runs of each report and Set to keep in the target path, the current one included (default: $DRE_KEEP_RUNS, then flags: keep_runs in dre_project.yml, then 1).
--threads <N>		How many Bindings may run at once in this run (default: $DRE_THREADS; without it, each connection entry's threads:, default 1). --threads 1 runs them one at a time.
--row-concurrency <N>		How many rows of a per-row (for_each) output render and deliver at once, over for_each.concurrency (default: $DRE_ROW_CONCURRENCY, then for_each.concurrency, then 4).
--hold		Hold every delivery: render and record them, and deliver them later with dre release.
--retry-failed <RUN_ID>		Redo a run's failed and never-started rows of its per-row outputs, from the query results it saved, with no query; other outputs are skipped. The new run doesn't become current.
--only-keys <KEYS>		Make only these rows of each per-row output (keys, comma-separated); recorded as partial.
--limit-rows <N>		Make at most this many rows of each per-row output; recorded as partial.
--unmask		With --preview: show per-row values (addresses, paths) as they are, not masked.
--rate <N/UNIT>		Pace every destination at this rate for this run, over its rate:: a count and a unit, like 100/minute, 5/second or 20000/hour, spaced evenly.

Example:

dre run monthly_revenue --set client_a --target prod

dre compile

Render reports' SQL into /compiled/ without running it, and list the files.

dre compile [OPTIONS] [SELECTOR]...

Argument	Description
SELECTOR...	What to compile: report names, tag:<tag>, folder names or dotted folder paths. Compiles every report when omitted.

Option	Default	Description
-s, --select <SELECTOR>		What to select (dbt's --select): report names, tag:<tag>, folder names or dotted folder paths. Several match any of them: -s a b, -s a,b, -s a -s b (or "a;b").
--project-dir <PROJECT_DIR>	.	Project directory (default: the current directory).
--profiles-dir <PROFILES_DIR>		Directory holding profiles.yml (default: $DRE_PROFILES_DIR, then the project directory if it has a profiles.yml, then ~/.dre). Environment: DRE_PROFILES_DIR.
--no-auto-install		Fail instead of installing declared plugins that are missing.
--target <TARGET>		The run's target (environment), target.name in templates: every profile uses its entry for it (default: $DRE_TARGET; without either, each profile uses its own target:, else dev). Environment: DRE_TARGET.
--target-path <PATH>		Where DRE writes its generated files (default: $DRE_TARGET_PATH, then target_path in dre_project.yml, then target/). A local or mounted path, absolute or relative to the project root. Unrelated to --target. Environment: DRE_TARGET_PATH.
--var <NAME=VALUE>		Set a variable for var(), overriding every other level: --var name=value. The value is YAML 1.2 (false, 5, [a, b] are typed); quote it to keep text: --var x='"false"'.
--timezone <TIMEZONE>		The run's timezone (IANA name, e.g. Australia/Sydney), above every timezone: setting (default: $DRE_TIMEZONE). Environment: DRE_TIMEZONE.
--set <SET>		Compile one Set (declared or ad hoc), or all of a report's Sets.

Example:

dre compile tag:finance

dre query

Run one read-only query on a configured connection and write typed JSON rows.

dre query [OPTIONS] --profile <PROFILE> --sql-file <SQL_FILE> --output-file <OUTPUT_FILE>

Option	Default	Description
--project-dir <PROJECT_DIR>	.	Project directory (default: the current directory).
--profiles-dir <PROFILES_DIR>		Directory holding profiles.yml (default: $DRE_PROFILES_DIR, then the project directory if it has a profiles.yml, then ~/.dre). Environment: DRE_PROFILES_DIR.
--no-auto-install		Fail instead of installing declared plugins that are missing.
--target <TARGET>		The run's target (environment), target.name in templates: every profile uses its entry for it (default: $DRE_TARGET; without either, each profile uses its own target:, else dev). Environment: DRE_TARGET.
--target-path <PATH>		Where DRE writes its generated files (default: $DRE_TARGET_PATH, then target_path in dre_project.yml, then target/). A local or mounted path, absolute or relative to the project root. Unrelated to --target. Environment: DRE_TARGET_PATH.
--var <NAME=VALUE>		Set a variable for var(), overriding every other level: --var name=value. The value is YAML 1.2 (false, 5, [a, b] are typed); quote it to keep text: --var x='"false"'.
--timezone <TIMEZONE>		The run's timezone (IANA name, e.g. Australia/Sydney), above every timezone: setting (default: $DRE_TIMEZONE). Environment: DRE_TIMEZONE.
--profile <PROFILE>		The configured source connection.
--sql-file <SQL_FILE>		File containing one read-only SQL query (relative to the project directory).
--output-file <OUTPUT_FILE>		The JSON file to write, relative to the project directory.
--max-rows <MAX_ROWS>	1000	Maximum result rows. The result records whether more rows were available.

dre catalog

Read live table/column definitions and comments through a configured connection.

dre catalog [OPTIONS] --profile <PROFILE> --tables-file <TABLES_FILE> --output-file <OUTPUT_FILE>

Option	Default	Description
--project-dir <PROJECT_DIR>	.	Project directory (default: the current directory).
--profiles-dir <PROFILES_DIR>		Directory holding profiles.yml (default: $DRE_PROFILES_DIR, then the project directory if it has a profiles.yml, then ~/.dre). Environment: DRE_PROFILES_DIR.
--no-auto-install		Fail instead of installing declared plugins that are missing.
--target <TARGET>		The run's target (environment), target.name in templates: every profile uses its entry for it (default: $DRE_TARGET; without either, each profile uses its own target:, else dev). Environment: DRE_TARGET.
--target-path <PATH>		Where DRE writes its generated files (default: $DRE_TARGET_PATH, then target_path in dre_project.yml, then target/). A local or mounted path, absolute or relative to the project root. Unrelated to --target. Environment: DRE_TARGET_PATH.
--var <NAME=VALUE>		Set a variable for var(), overriding every other level: --var name=value. The value is YAML 1.2 (false, 5, [a, b] are typed); quote it to keep text: --var x='"false"'.
--timezone <TIMEZONE>		The run's timezone (IANA name, e.g. Australia/Sydney), above every timezone: setting (default: $DRE_TIMEZONE). Environment: DRE_TIMEZONE.
--profile <PROFILE>		The source connection to inspect.
--tables-file <TABLES_FILE>		JSON object with tables and schemas arrays of relation names.
--output-file <OUTPUT_FILE>		The JSON file to write, relative to the project directory.

dre mcp

Hand arguments to the companion that provides dre mcp, offering to install it.

dre mcp [OPTIONS] [ARGS]...

Argument	Description
ARGS...	Arguments passed unchanged to the installed companion.

Option	Default	Description
--accept-proprietary		Install the companion without asking, after reviewing the licence the registry names.

dre extension

Install or update companion binaries, separately from source/format/destination plugins.

Subcommands:

• dre extension install: Install, or update to the newest version, a separately licensed companion executable.

dre extension install

Install, or update to the newest version, a separately licensed companion executable.

dre extension install [OPTIONS] <NAME>

Argument	Description
NAME	Companion package name, optionally with @version.

Option	Default	Description
--accept-proprietary		Install without asking, after reviewing the licence the registry names.

dre clean

Remove the target folder (compiled SQL, run outputs, schema snapshots, the manifest).

dre clean [OPTIONS]

Option	Default	Description
--project-dir <PROJECT_DIR>	.	Project directory (default: the current directory).
--prune		Don't delete the folder: only remove the runs beyond keep_runs (and unfinished ones) from every report and Set, keeping each current run.
--keep-runs <N>		With --prune, keep this many runs of each (default: $DRE_KEEP_RUNS, then flags: keep_runs, then 1).
--target-path <PATH>		The folder to clean (default: $DRE_TARGET_PATH, then target_path in dre_project.yml, then target/). Only a folder DRE created is deleted. Environment: DRE_TARGET_PATH.

Example:

dre clean

dre ls

List the reports and Bindings a selection or schedule covers, without running anything.

dre ls [OPTIONS] [SELECTOR]...

Argument	Description
SELECTOR...	What to list: report names, tag:<tag>, folder names or dotted folder paths. Lists every report when omitted.

Option	Default	Description
-s, --select <SELECTOR>		What to select (dbt's --select), as on dre run.
--set <SET>		Only this Set's Bindings (all: every Set). Without it, every declared Binding of each selected report is listed, not only the default Set a plain dre run would pick.
--schedule <NAME>		The Bindings a schedules.yml entry runs.
--output <OUTPUT>	text	text for people, json for tools (the manifest's shape, holding only what matched). One of text, json.
--resource-type <RESOURCE_TYPE>	report	What to list: reports (default), or the declared sources (each table, its connection, and the reports that read it; unused ones are flagged). One of report, source.
--target <TARGET>		The run's target (environment), which sets every profile's entry (default: $DRE_TARGET; without either, each profile uses its own target:, else dev). Environment: DRE_TARGET.
--var <NAME=VALUE>		Set a variable for var(), as on dre run.
--project-dir <PROJECT_DIR>	.	Project directory (default: the current directory).
--profiles-dir <PROFILES_DIR>		Directory holding profiles.yml (not needed; accepted as on the other project commands). Environment: DRE_PROFILES_DIR.
--target-path <PATH>		The target path, accepted as on the other project commands; ls writes nothing to it. Environment: DRE_TARGET_PATH.

Example:

dre ls --schedule daily

dre schedule

Work out when schedules fire, for people and orchestrators.

Subcommands:

• dre schedule ls: List when schedules fire (occurrences) within a window, with the command to run each one.

dre schedule ls

List when schedules fire (occurrences) within a window, with the command to run each one.

dre schedule ls [OPTIONS]

Option	Default	Description
--schedule <NAME>		Only this schedule (repeatable).
-s, --select <SELECTOR>		Only schedules that run one of these reports: report names, tag:<tag>, folder names or dotted folder paths, as on dre run.
--from <WHEN>		Start of the window: a date (00:00 UTC) or an RFC 3339 date-time (default: now, to the minute). May be in the past.
--to <WHEN>		End of the window, exclusive (default: 35 days after --from; at most 366 days after it).
--limit <N>		At most this many firings per schedule (text output defaults to 5).
--split		One occurrence per report and Set instead of one per firing.
--output <OUTPUT>	text	text for people, json for tools (the versioned schedule document). One of text, json.
--project-dir <PROJECT_DIR>	.	Project directory (default: the current directory).
--profiles-dir <PROFILES_DIR>		Directory holding profiles.yml (not needed; accepted as on the other project commands). Environment: DRE_PROFILES_DIR.

Example:

dre schedule ls --from 2026-11-01 --to 2026-12-01

dre init

Set up a connection (installing its plugin) and optionally a starter project, interactively.

dre init [OPTIONS]

Option	Default	Description
--profiles-dir <PROFILES_DIR>		Directory holding profiles.yml (default: $DRE_PROFILES_DIR, then ~/.dre). Environment: DRE_PROFILES_DIR.

Example:

dre init

dre new

Create a starter project in a new directory.

dre new [OPTIONS] <DIR>

Argument	Description
DIR	Directory to create (must be missing or empty).

Option	Default	Description
--profile <PROFILE>	warehouse	The connection profile the project uses by default.
--type <PLUGIN>	duckdb	The plugin of that connection (its type), which the project declares. --source is the 0.1 name.

Example:

dre new my_reports --type postgres

dre deps

Install the project's declared plugins (pinned by dre.lock) without running anything.

dre deps [OPTIONS]

Option	Default	Description
--accept-proprietary		Install the project's declared companions without asking, after reviewing their licences.
--project-dir <PROJECT_DIR>	.
--profiles-dir <PROFILES_DIR>		Environment: DRE_PROFILES_DIR.

Example:

dre deps

dre plugin

Manage plugins (sources, formats, destinations).

Subcommands:

• dre plugin list: List installed plugins, with each one's version and protocol version.
• dre plugin install: Install a plugin from the registry: name, kind/name, optionally @<version req>.
• dre plugin update: Install the newest version allowed by the constraint (ignoring dre.lock's pin) and re-pin it.
• dre plugin remove: Remove installed versions of a plugin (name@version removes just one).

dre plugin list

List installed plugins, with each one's version and protocol version.

dre plugin list [OPTIONS]

Example:

dre plugin list

dre plugin install

Install a plugin from the registry: name, kind/name, optionally @<version req>.

dre plugin install [OPTIONS] <PLUGIN>

Argument	Description
PLUGIN	duckdb, source/duckdb, xlsx@^1, ...

Option	Default	Description
--project-dir <PROJECT_DIR>	.	Project whose dre.lock to update (default: the current directory, if it's a project).

Example:

dre plugin install xlsx@^1

dre plugin update

Install the newest version allowed by the constraint (ignoring dre.lock's pin) and re-pin it.

dre plugin update [OPTIONS] <PLUGIN>

Argument	Description
PLUGIN	duckdb, source/duckdb, xlsx@^1, ...

Option	Default	Description
--project-dir <PROJECT_DIR>	.	Project whose dre.lock to update (default: the current directory, if it's a project).

Example:

dre plugin update postgres

dre plugin remove

Remove installed versions of a plugin (name@version removes just one).

dre plugin remove [OPTIONS] <PLUGIN>

Argument	Description
PLUGIN	duckdb, source/duckdb, xlsx@^1, ...

Option	Default	Description
--project-dir <PROJECT_DIR>	.	Project whose dre.lock to update (default: the current directory, if it's a project).

Example:

dre plugin remove duckdb@1.1.0

dre system

Commands about DRE itself rather than a project.

Subcommands:

• dre system update: Update DRE to the newest release (or VERSION), the way it was installed.

dre system update

Update DRE to the newest release (or VERSION), the way it was installed.

dre system update [OPTIONS] [VERSION]

Option	Default	Description
--check		Only report whether an update exists; change nothing.

Example:

dre system update --check

dre explain

Explain an error code (dre explain unknown-key): what it means and how to fix it.

dre explain [OPTIONS] <CODE>

Argument	Description
CODE	The code, as in error[unknown-key].

Example:

dre explain unknown-key

dre history

A report's runs in the target path, newest first, and which is current (the latest finished); --latest --path prints where the latest files are.

dre history [OPTIONS] <REPORT>

Argument	Description
REPORT	The report.

Option	Default	Description
--binding <BINDING>		Only this Binding: a Set's name, or default for a report without Sets.
--latest		Only the current run (the latest that finished) of each Binding.
--path		Print only the runs' folders, one per line (with --latest: where the latest files are).
--output <OUTPUT>	text	text for people, json for scripts. One of text, json.
--project-dir <PROJECT_DIR>	.	Project directory (default: the current directory).
--target-path <PATH>		The target path (default: $DRE_TARGET_PATH, then target_path in dre_project.yml, then target/). Environment: DRE_TARGET_PATH.

Example:

dre history monthly_revenue --latest --path

dre unlock

Remove a Binding's lock left by a run that's no longer going on (it shows the holder and asks first).

dre unlock [OPTIONS] <REPORT>

Argument	Description
REPORT	The report.

Option	Default	Description
--binding <BINDING>	default	The Binding: a Set's name, or default (the default) for a report without Sets.
--yes		Don't ask for confirmation (for scripts).
--project-dir <PROJECT_DIR>	.	Project directory (default: the current directory).
--target-path <PATH>		The target path (default: $DRE_TARGET_PATH, then target_path in dre_project.yml, then target/). Environment: DRE_TARGET_PATH.

Example:

dre unlock monthly_revenue --binding client_a

dre release

Deliver a run's held deliveries (hold: true, dre run --hold) from its run folder, byte for byte what was rendered; never re-renders or re-queries, and never sends twice.

dre release [OPTIONS] --run <RUN_ID> <REPORT>

Argument	Description
REPORT	The report.

Option	Default	Description
--run <RUN_ID>		The run whose held deliveries to deliver (its id, as dre history lists it).
--binding <BINDING>	default	The Binding: the Set's name, or default for a report without Sets.
--only-keys <KEYS>		Release only these rows of a per-row output (keys, comma-separated).
--exclude-keys <KEYS>		Release every held delivery but these rows' (keys, comma-separated).
--by <NAME>		Who releases, recorded in the release's run_results.json (default: $USER).
--rate <N/UNIT>		Pace the deliveries at this rate, over each one's recorded rate:: a count and a unit, like 100/minute, 5/second or 20000/hour, spaced evenly.
--project-dir <PROJECT_DIR>	.	Project directory (default: the current directory).
--profiles-dir <PROFILES_DIR>		Directory holding profiles.yml (default: $DRE_PROFILES_DIR, then the project directory if it has a profiles.yml, then ~/.dre). Environment: DRE_PROFILES_DIR.
--no-auto-install		Fail instead of installing declared plugins that are missing.
--target <TARGET>		The run's target (environment), target.name in templates: every profile uses its entry for it (default: $DRE_TARGET; without either, each profile uses its own target:, else dev). Environment: DRE_TARGET.
--target-path <PATH>		Where DRE writes its generated files (default: $DRE_TARGET_PATH, then target_path in dre_project.yml, then target/). A local or mounted path, absolute or relative to the project root. Unrelated to --target. Environment: DRE_TARGET_PATH.
--var <NAME=VALUE>		Set a variable for var(), overriding every other level: --var name=value. The value is YAML 1.2 (false, 5, [a, b] are typed); quote it to keep text: --var x='"false"'.
--timezone <TIMEZONE>		The run's timezone (IANA name, e.g. Australia/Sydney), above every timezone: setting (default: $DRE_TIMEZONE). Environment: DRE_TIMEZONE.

Example:

dre release statements --run 20261017T060000Z-k3f9 --by jane

---

Previous: Google Chat · Next: YAML reference