Introduction
HomeTutorial
Concepts
ArchitectureTemporal LogicSchema Evolution
Guides
Loading StrategiesFeatures & MLLineageObservabilityMigrationComparison
Reference
DSL SyntaxCLI

CLI Reference

SqlCAD is invoked via the sqlcad command (or python -m sqlcad.main).

build

Compiles the project into standard SQL files.

sqlcad build [OPTIONS]

Options:

  • --directory TEXT: The directory to scan for .sqlcad files. Defaults to current directory (.).
  • --output TEXT: Directory to write generated SQL. Defaults to output.
  • --dialect TEXT: Target SQL dialect (duckdb, bigquery, snowflake). Defaults to duckdb.

Outputs:

  • setup.sql: A warehouse initialization script containing DDL (CREATE SCHEMA/TABLE/VIEW) for all objects.
  • recurring/: Directory containing data loading scripts for materialized tables.
    • recurring/silver/*.sql: Load scripts for Silver Entities.
    • recurring/gold/*.sql: Load scripts for Gold Marts, Reports, Aggregations, and Feature Sets.
    • base/, silver/, gold/: Flat view definitions for reference (if needed, but mainly consolidated in setup.sql).

check

Validates the project structure, graph integrity, and types without generating code.

sqlcad check [OPTIONS]

Options:

  • --directory TEXT: The directory to scan.

Checks performed:

  • Cycles: Ensures no circular dependencies in the graph.
  • Architecture: Ensures Tables have columns, Entities have PKs.
    • Types: (Experimental) Validates column types propagate correctly.

lineage

Generates a visual dependency graph of the project (Entity or Column level).

sqlcad lineage [OPTIONS]

Options:

  • --directory TEXT: The directory to scan. Defaults to ..
  • --output TEXT: File path for the output. Defaults to lineage.html.
  • --format TEXT: Output format: html (interactive D3) or mermaid (static text). Defaults to html.
  • --column TEXT: (Optional) Trace lineage for a specific column (e.g., mart.revenue).

migrate dbtImports a dbt project by reading its manifest.json.

sqlcad migrate dbt [OPTIONS] MANIFEST

Arguments:

  • MANIFEST: Path to the dbt manifest.json file.

Options:

  • --output TEXT: Directory to write the new .sqlcad files. Defaults to migrated_project.

schema plan

Compares the desired state (your code) with the actual database state and generates a plan of DDL operations (CREATE, ALTER, DROP) to converge them.

sqlcad schema plan [OPTIONS]

Options:

  • --target TEXT: Database target type (e.g., duckdb).
  • --db-path TEXT: Path to database file (required for DuckDB).
  • --apply-on-plan: (Caution) Automatically apply changes after planning.
  • --output TEXT: Path to save the plan JSON. Defaults to .sqlcad/plan.json.

Example:

sqlcad schema plan --target duckdb --db-path warehouse.duckdb

schema apply

Applies a previously generated schema plan or executes pending changes to the database.

sqlcad schema apply [OPTIONS]

Options:

  • --plan-file TEXT: Path to the plan file to apply. Defaults to .sqlcad/plan.json.
  • --db-path TEXT: Path to database file.