databricks-schema 0.7.0__tar.gz → 0.8.0__tar.gz

{databricks_schema-0.7.0 → databricks_schema-0.8.0}/.gitignore

@@ -14,4 +14,3 @@ wheels/
 
 # Claude Code
 .claude/*
-!.claude/skills/

{databricks_schema-0.7.0 → databricks_schema-0.8.0}/CLAUDE.md

@@ -32,12 +32,13 @@ tests/
   test_diff.py       # pure model comparison, no SDK calls
   test_sql_gen.py    # pure SQL generation tests, no SDK calls
   test_validate.py
-.claude/skills/databricks-schema-cli/SKILL.md  # Agent Skill: teaches an AI agent to drive the CLI
+skills/databricks-schema-cli/SKILL.md  # Agent Skill: teaches an AI agent to drive the CLI
 ```
 
 ## Conventions
 
 - Package manager: `uv`; do not use `pip` directly
+- Version bumps: use `uv version --bump <major|minor|patch>` (updates `pyproject.toml` and `uv.lock` together) — do not hand-edit the version string
 - Ruff: select E, W, F, I, UP; line-length 100; target py311
 - Use `X | None` not `Optional[X]`; use `datetime.UTC` not `timezone.utc`
 - `from __future__ import annotations` in every module
@@ -64,4 +65,4 @@ tests/
 - `sql_gen.py` is pure (no SDK, no I/O); diff direction: `FieldChange.old` = stored (target), `.new` = live
 - FK refs in SQL use same catalog as the source table (`ref_schema` + `ref_table` from model)
 - Unsupported field changes (`table_type`) emit `-- TODO: unsupported change: …` comments
-- When CLI commands, flags, or output shape change, update `.claude/skills/databricks-schema-cli/SKILL.md` to match
+- When CLI commands, flags, or output shape change, update `skills/databricks-schema-cli/SKILL.md` to match

{databricks_schema-0.7.0 → databricks_schema-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: databricks-schema
-Version: 0.7.0
+Version: 0.8.0
 Summary: Databricks Unity Catalog schema extractor
 Project-URL: Homepage, https://github.com/frizzleqq/databricks-schema
 Project-URL: Repository, https://github.com/frizzleqq/databricks-schema
@@ -25,7 +25,7 @@ Description-Content-Type: text/markdown
 
 # databricks-schema
 
-A CLI tool and Python library that uses the Databricks SDK to extract and diff Unity Catalog schemas as YAML files. It can also generate Databricks Spark SQL to apply schema changes across catalogs.
+A CLI tool and Python library that uses the Databricks SDK to extract and diff Unity Catalog schemas in YAML format. It can also generate Databricks Spark SQL to apply schema changes across catalogs.
 
 ## Getting Started
 
@@ -53,11 +53,76 @@ databricks-schema diff test_catalog ./schemas/
 databricks-schema generate-sql test_catalog ./schemas/ --output-dir ./migrations/
 ```
 
-The YAML files act as a version-controllable snapshot of your schema. The `diff` command exits with code `1` when differences are found, making it suitable for CI pipelines.
+## Databricks Authentication
+
+The tool uses the [Databricks SDK](https://github.com/databricks/databricks-sdk-py) for auth. Configure it via environment variables:
+
+```bash
+export DATABRICKS_HOST=https://<databricks-url>
+export DATABRICKS_TOKEN=<your-personal-access-token>
+```
+
+Or use a [Databricks CLI profile](https://docs.databricks.com/dev-tools/cli/profiles.html) (`~/.databrickscfg`) — the SDK will pick it up automatically.
+
+You can also pass credentials directly as flags using `--host` / `--token` below.
+
+## Development
+
+Requires Python 3.11+ and [uv](https://github.com/astral-sh/uv).
+
+```bash
+git clone https://github.com/frizzleqq/databricks-schema
+cd databricks-schema
+uv sync --all-groups  # includes pytest and ruff
+```
+
+```bash
+# Run tests
+uv run pytest
+
+# Lint
+uv run ruff check databricks_schema/ tests/
+
+# Format
+uv run ruff format databricks_schema/ tests/
+```
+
+## Agent Skill
+
+This repo ships an [Agent Skill](https://code.claude.com/docs/en/skills) at
+[`skills/databricks-schema-cli/SKILL.md`](skills/databricks-schema-cli/SKILL.md)
+that teaches an AI coding agent (e.g. Claude Code) how to use the `databricks-schema` CLI to
+explore, snapshot, diff, and generate migration SQL for a live Unity Catalog. Copy the skill into
+your own project and it can use the CLI directly instead of writing ad-hoc Databricks SDK calls
+or queries.
+
+The skill assumes the `databricks-schema` command is on `PATH`. Install it as a standalone tool
+with [uv](https://github.com/astral-sh/uv):
+
+```bash
+uv tool install databricks-schema
+```
+
+To use the skill in your own project without cloning this repo, download it directly into your
+project's `.claude/skills/`:
+
+```bash
+mkdir -p .claude/skills/databricks-schema-cli
+curl -o .claude/skills/databricks-schema-cli/SKILL.md \
+  https://raw.githubusercontent.com/frizzleqq/databricks-schema/main/skills/databricks-schema-cli/SKILL.md
+```
+
+For agentic harnesses other than Claude Code that look under `.agents/skills/` instead:
+
+```bash
+mkdir -p .agents/skills/databricks-schema-cli
+curl -o .agents/skills/databricks-schema-cli/SKILL.md \
+  https://raw.githubusercontent.com/frizzleqq/databricks-schema/main/skills/databricks-schema-cli/SKILL.md
+```
 
 ## Output Format
 
-Each schema is written to `{output-dir}/{schema-name}.yaml`. Fields with no value (null comments, empty tag dicts, empty FK lists) are omitted. Use `--format json` to write `.json` files with the same structure.
+Each schema is written to `{output-dir}/{schema-name}.yaml` if `--output-dir` is specified. Fields with no value (null comments, empty tag dicts, empty FK lists) are omitted. Use `--format json` to write `.json` files with the same structure.
 
 ```yaml
 name: main
@@ -105,73 +170,33 @@ schemas:
     tables: [...]
 ```
 
-## Authentication
-
-The tool uses the [Databricks SDK](https://github.com/databricks/databricks-sdk-py) for auth. Configure it via environment variables:
+## CLI Usage
 
-```bash
-export DATABRICKS_HOST=https://<databricks-url>
-export DATABRICKS_TOKEN=<your-personal-access-token>
 ```
-
-Or use a [Databricks CLI profile](https://docs.databricks.com/dev-tools/cli/profiles.html) (`~/.databrickscfg`) — the SDK will pick it up automatically.
-
-You can also pass credentials directly as flags (see `--host` / `--token` below).
-
-## Agent Skill
-
-This repo ships an [Agent Skill](https://code.claude.com/docs/en/skills) at
-[`.claude/skills/databricks-schema-cli/SKILL.md`](.claude/skills/databricks-schema-cli/SKILL.md)
-that teaches an AI coding agent (e.g. Claude Code) how to use the `databricks-schema` CLI to
-explore, snapshot, diff, and generate migration SQL for a live Unity Catalog. Point an agent at
-this repo (or copy the skill into your own project) and it can use the CLI directly instead of
-writing ad-hoc Databricks SDK calls.
-
-The skill assumes the `databricks-schema` command is on `PATH`. Install it as a standalone tool
-with [uv](https://github.com/astral-sh/uv):
-
-```bash
-uv tool install databricks-schema
+databricks-schema [OPTIONS] COMMAND [ARGS]...
 ```
 
-To use the skill in your own project without cloning this repo, download it directly:
+`extract`, `diff`, `generate-sql`, and `diff-files` print progress messages (e.g. `Extracting catalog 'X'...`) to stderr as they run. Pass `--quiet` / `-q` to suppress them;
+results and errors are unaffected.
 
-```bash
-mkdir -p .claude/skills/databricks-schema-cli
-curl -o .claude/skills/databricks-schema-cli/SKILL.md \
-  https://raw.githubusercontent.com/frizzleqq/databricks-schema/main/.claude/skills/databricks-schema-cli/SKILL.md
-```
-
-## Development
+### `list-catalogs`
 
-Requires Python 3.11+ and [uv](https://github.com/astral-sh/uv).
+List all accessible catalogs:
 
 ```bash
-git clone https://github.com/frizzleqq/databricks-schema
-cd databricks-schema
-uv sync --all-groups  # includes pytest and ruff
+databricks-schema list-catalogs
 ```
 
-```bash
-# Run tests
-uv run pytest
-
-# Lint
-uv run ruff check databricks_schema/ tests/
-
-# Format
-uv run ruff format databricks_schema/ tests/
-```
+### `list-schemas`
 
-## CLI Usage
+List schemas in a catalog:
 
-```
-databricks-schema [OPTIONS] COMMAND [ARGS]...
+```bash
+databricks-schema list-schemas <catalog>
 ```
 
-`extract`, `diff`, `generate-sql`, and `diff-files` print progress messages (e.g. `Extracting
-catalog 'X'...`) to stderr as they run. Pass `--quiet` / `-q` to suppress them; results and
-errors are unaffected.
+Both print one name per line by default. Pass `--format json` / `-f json` (or `--format yaml`) to
+get the names as a JSON array or YAML list instead.
 
 ### `extract`
 
@@ -181,7 +206,11 @@ Extract all schemas from a catalog to YAML files:
 databricks-schema extract <catalog> --output-dir ./schemas/
 ```
 
-Use `--format json` to write `.json` files instead of `.yaml`.
+Print to stdout instead of writing files (no `--output-dir`) — the catalog and its schemas are printed as a single `Catalog` document (`name` + `schemas: [...]`):
+
+```bash
+databricks-schema extract <catalog>
+```
 
 Extract specific schemas only:
 
@@ -196,12 +225,6 @@ databricks-schema extract <catalog>.<schema>
 databricks-schema extract <catalog>.<schema>.<table>
 ```
 
-Print to stdout instead of writing files (no `--output-dir`) — the catalog and its matching schemas are printed as a single `Catalog` document (`name` + `schemas: [...]`):
-
-```bash
-databricks-schema extract <catalog> --schema main
-```
-
 Include Unity Catalog tags in the output (extra API calls per entity; excluded by default):
 
 ```bash
@@ -214,7 +237,7 @@ Include additional metadata (`owner`, `storage_location`) in the output:
 databricks-schema extract <catalog> --output-dir ./schemas/ --include-metadata
 ```
 
-Control the number of parallel workers (default: 4):
+Control the number of parallel workers (default: 4), useful for large schemas with many tags:
 
 ```bash
 databricks-schema extract <catalog> --output-dir ./schemas/ --workers 8
@@ -228,7 +251,21 @@ Compare the live catalog against previously extracted schema files (format auto-
 databricks-schema diff <catalog> ./schemas/
 ```
 
-Or compare two live catalogs directly, e.g. dev against prod — no local files needed. The second argument is treated as a directory if one exists at that path, otherwise as a catalog name:
+Exits with code `0` if no differences are found, `1` if there are — making it suitable for CI pipelines. Output example:
+
+```
+~ Schema: main [MODIFIED]
+  ~ Table: users [MODIFIED]
+    ~ Column: score [MODIFIED]
+        data_type: 'int' -> 'double'
+    + Column: phone [ADDED]
+  + Table: events [ADDED]
+- Schema: legacy [REMOVED]
+```
+
+Markers: `+` added in catalog, `-` removed from catalog, `~` modified.
+
+Or compare two live catalogs directly, e.g. dev against prod. The second argument is treated as a directory if one exists at that path, otherwise as a catalog name:
 
 ```bash
 databricks-schema diff dev_catalog prod_catalog
@@ -252,20 +289,13 @@ Include `owner` in the comparison (excluded by default):
 databricks-schema diff <catalog> ./schemas/ --include-metadata
 ```
 
-Exits with code `0` if no differences are found, `1` if there are — making it suitable for CI pipelines. Output example:
+Get the same comparison as structured JSON or YAML instead of the `+`/`-`/`~` tree (exit codes unchanged) — useful for scripts or agents:
 
-```
-~ Schema: main [MODIFIED]
-  ~ Table: users [MODIFIED]
-    ~ Column: score [MODIFIED]
-        data_type: 'int' -> 'double'
-    + Column: phone [ADDED]
-  + Table: events [ADDED]
-- Schema: legacy [REMOVED]
+```bash
+databricks-schema diff <catalog> ./schemas/ --format json
+databricks-schema diff <catalog> ./schemas/ --format yaml
 ```
 
-Markers: `+` added in catalog, `-` removed from catalog, `~` modified.
-
 ### `generate-sql`
 
 Generate Databricks Spark SQL statements to bring the live catalog in line with local schema files (format auto-detected, YAML or JSON, not mixed). Statements are printed to stdout by default:
@@ -312,29 +342,28 @@ Validate local schema files for structural integrity (no Databricks connection n
 databricks-schema validate ./schemas/
 ```
 
+Pass `--format json` or `--format yaml` for an `{"issues": [...]}` document instead of `OK`/`ERROR:` text.
+
 ### `diff-files`
 
 Compare two local directories of schema files (no Databricks connection needed). Same output,
-exit codes, and `--schema` / `--include-metadata` flags as `diff`:
+exit codes, `--format json`/`yaml`, and `--schema` / `--include-metadata` flags as `diff`:
 
 ```bash
 databricks-schema diff-files ./schemas-prod/ ./schemas-test/
 ```
 
-### `list-catalogs`
-
-List all accessible catalogs:
-
-```bash
-databricks-schema list-catalogs
-```
-
-### `list-schemas`
+### `json-schema`
 
-List schemas in a catalog:
+Print the JSON Schema for one of the CLI's structured output shapes — no Databricks connection
+needed. Useful before parsing `--format json`/`yaml` output (or `extract`'s output)
+programmatically. Add `--format yaml` to render the schema itself as YAML:
 
 ```bash
-databricks-schema list-schemas <catalog>
+databricks-schema json-schema catalog    # extract's stdout Catalog document
+databricks-schema json-schema schema     # one per-schema extract file
+databricks-schema json-schema diff       # diff / diff-files --format json/yaml
+databricks-schema json-schema validate   # validate --format json/yaml
 ```
 
 ## Python Library Usage

{databricks_schema-0.7.0 → databricks_schema-0.8.0}/README.md

@@ -1,6 +1,6 @@
 # databricks-schema
 
-A CLI tool and Python library that uses the Databricks SDK to extract and diff Unity Catalog schemas as YAML files. It can also generate Databricks Spark SQL to apply schema changes across catalogs.
+A CLI tool and Python library that uses the Databricks SDK to extract and diff Unity Catalog schemas in YAML format. It can also generate Databricks Spark SQL to apply schema changes across catalogs.
 
 ## Getting Started
 
@@ -28,11 +28,76 @@ databricks-schema diff test_catalog ./schemas/
 databricks-schema generate-sql test_catalog ./schemas/ --output-dir ./migrations/
 ```
 
-The YAML files act as a version-controllable snapshot of your schema. The `diff` command exits with code `1` when differences are found, making it suitable for CI pipelines.
+## Databricks Authentication
+
+The tool uses the [Databricks SDK](https://github.com/databricks/databricks-sdk-py) for auth. Configure it via environment variables:
+
+```bash
+export DATABRICKS_HOST=https://<databricks-url>
+export DATABRICKS_TOKEN=<your-personal-access-token>
+```
+
+Or use a [Databricks CLI profile](https://docs.databricks.com/dev-tools/cli/profiles.html) (`~/.databrickscfg`) — the SDK will pick it up automatically.
+
+You can also pass credentials directly as flags using `--host` / `--token` below.
+
+## Development
+
+Requires Python 3.11+ and [uv](https://github.com/astral-sh/uv).
+
+```bash
+git clone https://github.com/frizzleqq/databricks-schema
+cd databricks-schema
+uv sync --all-groups  # includes pytest and ruff
+```
+
+```bash
+# Run tests
+uv run pytest
+
+# Lint
+uv run ruff check databricks_schema/ tests/
+
+# Format
+uv run ruff format databricks_schema/ tests/
+```
+
+## Agent Skill
+
+This repo ships an [Agent Skill](https://code.claude.com/docs/en/skills) at
+[`skills/databricks-schema-cli/SKILL.md`](skills/databricks-schema-cli/SKILL.md)
+that teaches an AI coding agent (e.g. Claude Code) how to use the `databricks-schema` CLI to
+explore, snapshot, diff, and generate migration SQL for a live Unity Catalog. Copy the skill into
+your own project and it can use the CLI directly instead of writing ad-hoc Databricks SDK calls
+or queries.
+
+The skill assumes the `databricks-schema` command is on `PATH`. Install it as a standalone tool
+with [uv](https://github.com/astral-sh/uv):
+
+```bash
+uv tool install databricks-schema
+```
+
+To use the skill in your own project without cloning this repo, download it directly into your
+project's `.claude/skills/`:
+
+```bash
+mkdir -p .claude/skills/databricks-schema-cli
+curl -o .claude/skills/databricks-schema-cli/SKILL.md \
+  https://raw.githubusercontent.com/frizzleqq/databricks-schema/main/skills/databricks-schema-cli/SKILL.md
+```
+
+For agentic harnesses other than Claude Code that look under `.agents/skills/` instead:
+
+```bash
+mkdir -p .agents/skills/databricks-schema-cli
+curl -o .agents/skills/databricks-schema-cli/SKILL.md \
+  https://raw.githubusercontent.com/frizzleqq/databricks-schema/main/skills/databricks-schema-cli/SKILL.md
+```
 
 ## Output Format
 
-Each schema is written to `{output-dir}/{schema-name}.yaml`. Fields with no value (null comments, empty tag dicts, empty FK lists) are omitted. Use `--format json` to write `.json` files with the same structure.
+Each schema is written to `{output-dir}/{schema-name}.yaml` if `--output-dir` is specified. Fields with no value (null comments, empty tag dicts, empty FK lists) are omitted. Use `--format json` to write `.json` files with the same structure.
 
 ```yaml
 name: main
@@ -80,73 +145,33 @@ schemas:
     tables: [...]
 ```
 
-## Authentication
-
-The tool uses the [Databricks SDK](https://github.com/databricks/databricks-sdk-py) for auth. Configure it via environment variables:
+## CLI Usage
 
-```bash
-export DATABRICKS_HOST=https://<databricks-url>
-export DATABRICKS_TOKEN=<your-personal-access-token>
 ```
-
-Or use a [Databricks CLI profile](https://docs.databricks.com/dev-tools/cli/profiles.html) (`~/.databrickscfg`) — the SDK will pick it up automatically.
-
-You can also pass credentials directly as flags (see `--host` / `--token` below).
-
-## Agent Skill
-
-This repo ships an [Agent Skill](https://code.claude.com/docs/en/skills) at
-[`.claude/skills/databricks-schema-cli/SKILL.md`](.claude/skills/databricks-schema-cli/SKILL.md)
-that teaches an AI coding agent (e.g. Claude Code) how to use the `databricks-schema` CLI to
-explore, snapshot, diff, and generate migration SQL for a live Unity Catalog. Point an agent at
-this repo (or copy the skill into your own project) and it can use the CLI directly instead of
-writing ad-hoc Databricks SDK calls.
-
-The skill assumes the `databricks-schema` command is on `PATH`. Install it as a standalone tool
-with [uv](https://github.com/astral-sh/uv):
-
-```bash
-uv tool install databricks-schema
+databricks-schema [OPTIONS] COMMAND [ARGS]...
 ```
 
-To use the skill in your own project without cloning this repo, download it directly:
+`extract`, `diff`, `generate-sql`, and `diff-files` print progress messages (e.g. `Extracting catalog 'X'...`) to stderr as they run. Pass `--quiet` / `-q` to suppress them;
+results and errors are unaffected.
 
-```bash
-mkdir -p .claude/skills/databricks-schema-cli
-curl -o .claude/skills/databricks-schema-cli/SKILL.md \
-  https://raw.githubusercontent.com/frizzleqq/databricks-schema/main/.claude/skills/databricks-schema-cli/SKILL.md
-```
-
-## Development
+### `list-catalogs`
 
-Requires Python 3.11+ and [uv](https://github.com/astral-sh/uv).
+List all accessible catalogs:
 
 ```bash
-git clone https://github.com/frizzleqq/databricks-schema
-cd databricks-schema
-uv sync --all-groups  # includes pytest and ruff
+databricks-schema list-catalogs
 ```
 
-```bash
-# Run tests
-uv run pytest
-
-# Lint
-uv run ruff check databricks_schema/ tests/
-
-# Format
-uv run ruff format databricks_schema/ tests/
-```
+### `list-schemas`
 
-## CLI Usage
+List schemas in a catalog:
 
-```
-databricks-schema [OPTIONS] COMMAND [ARGS]...
+```bash
+databricks-schema list-schemas <catalog>
 ```
 
-`extract`, `diff`, `generate-sql`, and `diff-files` print progress messages (e.g. `Extracting
-catalog 'X'...`) to stderr as they run. Pass `--quiet` / `-q` to suppress them; results and
-errors are unaffected.
+Both print one name per line by default. Pass `--format json` / `-f json` (or `--format yaml`) to
+get the names as a JSON array or YAML list instead.
 
 ### `extract`
 
@@ -156,7 +181,11 @@ Extract all schemas from a catalog to YAML files:
 databricks-schema extract <catalog> --output-dir ./schemas/
 ```
 
-Use `--format json` to write `.json` files instead of `.yaml`.
+Print to stdout instead of writing files (no `--output-dir`) — the catalog and its schemas are printed as a single `Catalog` document (`name` + `schemas: [...]`):
+
+```bash
+databricks-schema extract <catalog>
+```
 
 Extract specific schemas only:
 
@@ -171,12 +200,6 @@ databricks-schema extract <catalog>.<schema>
 databricks-schema extract <catalog>.<schema>.<table>
 ```
 
-Print to stdout instead of writing files (no `--output-dir`) — the catalog and its matching schemas are printed as a single `Catalog` document (`name` + `schemas: [...]`):
-
-```bash
-databricks-schema extract <catalog> --schema main
-```
-
 Include Unity Catalog tags in the output (extra API calls per entity; excluded by default):
 
 ```bash
@@ -189,7 +212,7 @@ Include additional metadata (`owner`, `storage_location`) in the output:
 databricks-schema extract <catalog> --output-dir ./schemas/ --include-metadata
 ```
 
-Control the number of parallel workers (default: 4):
+Control the number of parallel workers (default: 4), useful for large schemas with many tags:
 
 ```bash
 databricks-schema extract <catalog> --output-dir ./schemas/ --workers 8
@@ -203,7 +226,21 @@ Compare the live catalog against previously extracted schema files (format auto-
 databricks-schema diff <catalog> ./schemas/
 ```
 
-Or compare two live catalogs directly, e.g. dev against prod — no local files needed. The second argument is treated as a directory if one exists at that path, otherwise as a catalog name:
+Exits with code `0` if no differences are found, `1` if there are — making it suitable for CI pipelines. Output example:
+
+```
+~ Schema: main [MODIFIED]
+  ~ Table: users [MODIFIED]
+    ~ Column: score [MODIFIED]
+        data_type: 'int' -> 'double'
+    + Column: phone [ADDED]
+  + Table: events [ADDED]
+- Schema: legacy [REMOVED]
+```
+
+Markers: `+` added in catalog, `-` removed from catalog, `~` modified.
+
+Or compare two live catalogs directly, e.g. dev against prod. The second argument is treated as a directory if one exists at that path, otherwise as a catalog name:
 
 ```bash
 databricks-schema diff dev_catalog prod_catalog
@@ -227,20 +264,13 @@ Include `owner` in the comparison (excluded by default):
 databricks-schema diff <catalog> ./schemas/ --include-metadata
 ```
 
-Exits with code `0` if no differences are found, `1` if there are — making it suitable for CI pipelines. Output example:
+Get the same comparison as structured JSON or YAML instead of the `+`/`-`/`~` tree (exit codes unchanged) — useful for scripts or agents:
 
-```
-~ Schema: main [MODIFIED]
-  ~ Table: users [MODIFIED]
-    ~ Column: score [MODIFIED]
-        data_type: 'int' -> 'double'
-    + Column: phone [ADDED]
-  + Table: events [ADDED]
-- Schema: legacy [REMOVED]
+```bash
+databricks-schema diff <catalog> ./schemas/ --format json
+databricks-schema diff <catalog> ./schemas/ --format yaml
 ```
 
-Markers: `+` added in catalog, `-` removed from catalog, `~` modified.
-
 ### `generate-sql`
 
 Generate Databricks Spark SQL statements to bring the live catalog in line with local schema files (format auto-detected, YAML or JSON, not mixed). Statements are printed to stdout by default:
@@ -287,29 +317,28 @@ Validate local schema files for structural integrity (no Databricks connection n
 databricks-schema validate ./schemas/
 ```
 
+Pass `--format json` or `--format yaml` for an `{"issues": [...]}` document instead of `OK`/`ERROR:` text.
+
 ### `diff-files`
 
 Compare two local directories of schema files (no Databricks connection needed). Same output,
-exit codes, and `--schema` / `--include-metadata` flags as `diff`:
+exit codes, `--format json`/`yaml`, and `--schema` / `--include-metadata` flags as `diff`:
 
 ```bash
 databricks-schema diff-files ./schemas-prod/ ./schemas-test/
 ```
 
-### `list-catalogs`
-
-List all accessible catalogs:
-
-```bash
-databricks-schema list-catalogs
-```
-
-### `list-schemas`
+### `json-schema`
 
-List schemas in a catalog:
+Print the JSON Schema for one of the CLI's structured output shapes — no Databricks connection
+needed. Useful before parsing `--format json`/`yaml` output (or `extract`'s output)
+programmatically. Add `--format yaml` to render the schema itself as YAML:
 
 ```bash
-databricks-schema list-schemas <catalog>
+databricks-schema json-schema catalog    # extract's stdout Catalog document
+databricks-schema json-schema schema     # one per-schema extract file
+databricks-schema json-schema diff       # diff / diff-files --format json/yaml
+databricks-schema json-schema validate   # validate --format json/yaml
 ```
 
 ## Python Library Usage