CLI Reference

Summary of the SchemaX CLI. Run schemax --help and schemax <command> --help for full options.

Project and validation

Command	Description
schemax init	Initialize a new SchemaX project (or use VS Code Designer once).
schemax validate [workspace]	Validate .schemax/ project files and dependency graph.

SQL and snapshots

Command	Description
schemax sql [--output FILE] [--target ENV]	Generate SQL migration from changelog; --target uses that env’s catalog mapping and deployment scope (managed categories, existing objects).
schemax snapshot create --name NAME [--version v0.2.0] [--comment "..."] [--tags t1 t2]	Create snapshot from current changelog; changelog cleared.
schemax snapshot validate [workspace]	Detect stale snapshots after Git rebase.
schemax snapshot rebase VERSION [--base BASE]	Rebase snapshot onto new base after rebase.

Diff

Command	Description
schemax diff --from v0.1.0 --to v0.2.0 [--show-sql] [--target ENV]	Show diff operations (and optional SQL) between two snapshot versions.

Deploy and rollback

Command	Description
schemax apply --target ENV --profile PROFILE --warehouse-id ID [--dry-run] [--no-interaction] [--auto-rollback]	Execute SQL against target (filtered by env’s deployment scope); records deployment.
schemax rollback --deployment ID --partial --target ENV --profile P --warehouse-id W	Undo successful ops from a failed deployment.
schemax rollback --to-snapshot VERSION --target ENV --profile P --warehouse-id W [--force]	Complete rollback to a previous snapshot.
schemax import --target ENV --profile P --warehouse-id W [--catalog NAME] [--adopt-baseline]	Import from live Databricks: discover catalog/schema/table and write ops to changelog; optional baseline.
schemax import --from-sql PATH [--mode diff|replace] [--dry-run] [--target ENV]	Import from a SQL DDL file: parse file, diff vs current state (or replace as new baseline), write ops to changelog.

Common options

• --target ENV — Use environment config (catalog mapping, deployment scope) for SQL generation and apply. See Environments and deployment scope.
• --dry-run — Preview without executing (apply, rollback).
• --no-interaction — Skip prompts (CI/CD).
• --force — Override baseline guard for complete rollback (use with care).

Import from SQL file

You can bring existing DDL into SchemaX by pointing the CLI at a .sql file instead of a live Databricks workspace:

schemax import --from-sql path/to/schema.sql [--mode diff|replace] [--dry-run] [--target ENV]

• --from-sql PATH — Path to a SQL file containing Unity Catalog DDL (Databricks dialect). Supported statements (applied in file order): CREATE CATALOG, CREATE SCHEMA, CREATE TABLE, CREATE VIEW, COMMENT ON, and ALTER — ALTER TABLE (ADD COLUMN, DROP COLUMN, RENAME COLUMN, ALTER COLUMN SET NOT NULL / SET DATA TYPE, RENAME TO, SET TBLPROPERTIES) and ALTER CATALOG / ALTER SCHEMA / ALTER TABLE SET TAGS. Statements are applied in the order they appear (e.g. create a table then alter it to add columns or set properties). Unsupported statements are skipped and reported in the summary.
• --mode diff (default) — Compare the parsed state to your current project state and append the difference as operations to the changelog. Use this to add objects from the file on top of what you already have.
• --mode replace — Treat the parsed file as the new baseline: the diff is computed against an empty state, so the changelog will contain operations that recreate everything in the file. Use this when the SQL file is the single source of truth and you want to replace or bootstrap the project.
• --dry-run — Print what would be imported (parsed object counts and planned operations) without writing to the changelog.
• --target ENV — Optional; used for catalog mapping consistency when generating SQL later.

Statement order: The parser applies each statement in the order it appears in the file. For example, CREATE TABLE t (id INT); followed by ALTER TABLE t ADD COLUMN name STRING; and ALTER TABLE t SET TBLPROPERTIES ('k' = 'v'); produces a table with two columns and the property set. This matches the usual script style (create then alter).

If the workspace has no .schemax/ project yet, schemax import --from-sql will create a default Unity Catalog project before importing. In the VS Code extension, use Import assets → From SQL file tab to pick a file and run the same flow with a UI.