CLI reference

The delta-engine command has one read-only workflow:

delta-engine plan myproject.tables:all_tables

It loads one explicit declaration collection, reads one live Unity Catalog target through a Databricks SQL warehouse, and runs Engine.sync(..., dry_run=True). The engine invocation never executes planned DDL. Declaration modules are ordinary Python and remain responsible for their own import-time behaviour. Use the Python API when you intend to apply changes.

Install the optional CLI dependencies first:

pip install "delta-engine[cli]"

The base distribution remains dependency-free. If the console script is run without the extra, it prints the install command instead of importing Typer, the Databricks SDK, or the SQL connector.

Command

delta-engine plan MODULE:ATTRIBUTE

Routine use has no options. The root command retains --help and --version, and plan --help describes its one argument. Shell-completion installation options are disabled.

The command performs these operations in order:

  1. Import the selected declaration module from the current checkout.

  2. Validate that the attribute contains one non-empty ordered sequence of DeltaTable declarations.

  3. Open a SQL warehouse connection using Databricks unified authentication.

  4. Read catalog state and build a plan without executing it.

  5. Print the target identity, semantic diff, sync report, and any planned SQL.

A stopped warehouse may start when the plan reads catalog metadata, so the command can incur compute cost despite being read-only.

Declaration reference

The argument is always one MODULE:ATTRIBUTE reference. The attribute must be a non-empty ordered sequence, such as a list or tuple:

from delta_engine.schema import Column, DeltaTable, Integer

orders = DeltaTable(
    "dev",
    "silver",
    "orders",
    columns=(Column("id", Integer(), nullable=False),),
)

all_tables = [orders]

Point the command at the collection, even when it currently holds one table:

delta-engine plan myproject.tables:all_tables

A single DeltaTable, an empty collection, an unordered collection such as a set, a mixed sequence, or duplicate qualified table names is a configuration error. The CLI does not scan module globals and does not accept multiple declaration references.

Declaration order never changes the plan: the engine reports tables in sorted qualified-name order and derives execution order from foreign-key dependencies. The sequence requirement exists so error messages can point at a stable item index, not because position carries meaning.

The current working directory takes import precedence, so repository code does not need to be installed first. Declaration imports execute arbitrary Python; run plans only for code you trust. A missing target module or attribute is a short configuration error. Exceptions raised by the selected module, including a missing dependency imported by that module, retain their original traceback.

Databricks connection

Every invocation requires one CLI-specific target setting:

Environment variable

Meaning

DATABRICKS_SQL_WAREHOUSE_ID

Warehouse ID, not a connector HTTP path

The CLI constructs databricks.sdk.core.Config() without choosing an authentication method. The SDK resolves the workspace and credentials from its standard environment variables or configuration profiles. Authentication is therefore deployment configuration, not a CLI option or code path.

For example, a GitHub Actions job can select workload identity federation with DATABRICKS_HOST, DATABRICKS_CLIENT_ID, and DATABRICKS_AUTH_TYPE=github-oidc; see the CI guide. Local profiles and other Databricks unified-auth configurations use the same command without flags.

The warehouse ID becomes /sql/1.0/warehouses/<id> inside the connection boundary. Users never configure connector transport paths directly.

Authentication and connection failures are rendered as one-line configuration errors. Secret-looking environment values are redacted from failure details. A local file that shadows the installed databricks packages is also reported as a configuration error.

Output

Every completed plan writes these text sections to stdout in order:

  1. TARGET: normalized host, warehouse ID, and declaration reference

  2. DIFF: semantic changes for each table

  3. SYNC REPORT: statuses, failures, and summary

  4. PLANNED SQL: exact statements, when the plan compiled any

The sync report labels this boundary PLAN — no planned SQL executed. Catalog reads still occur and may start the warehouse; only the generated statements are guaranteed not to execute.

Credentials are never intentionally rendered. Planned SQL is shown by default; there is no SQL display flag or JSON mode.

Imported-code output, SDK or connector output, engine logs, configuration errors, and tracebacks go to stderr. This keeps the complete human-readable plan together on stdout while preserving diagnostics separately.

SQL is compiled before cross-table dependency resolution. A table later blocked by a failed dependency can therefore carry table-local planned SQL; the report explains why those statements were not eligible to run.

Exit codes

Code

Meaning

0

The plan completed successfully, whether in sync or carrying pending changes

1

Configuration, catalog read, or planning failed

2

Typer/Click rejected malformed command-line usage

Unexpected declaration-code and engine defects propagate with tracebacks and exit non-zero. The connection is still closed; a cleanup failure is logged and never replaces the completed report or primary exception.