dlin-cli 0.2.0a2__tar.gz → 0.2.0b2__tar.gz

{dlin_cli-0.2.0a2 → dlin_cli-0.2.0b2}/Cargo.lock

@@ -231,7 +231,7 @@ checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
 
 [[package]]
 name = "dlin"
-version = "0.2.0-alpha.2"
+version = "0.2.0-beta.2"
 dependencies = [
  "anyhow",
  "clap",
@@ -247,7 +247,7 @@ dependencies = [
 
 [[package]]
 name = "dlin-core"
-version = "0.2.0-alpha.2"
+version = "0.2.0-beta.2"
 dependencies = [
  "anyhow",
  "clap",
@@ -617,9 +617,9 @@ checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
 
 [[package]]
 name = "polyglot-sql"
-version = "0.4.0"
+version = "0.4.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b155f49ed6a6bb331a4aead9dc2f5f69a70f2130edd2614a0387a82ac1eee5e6"
+checksum = "3e264f8907f3a2050232cd06503afb637525038ddd388a2c9e03424e336cd9c8"
 dependencies = [
  "serde",
  "serde_json",

{dlin_cli-0.2.0a2 → dlin_cli-0.2.0b2}/Cargo.toml

@@ -3,7 +3,7 @@ members = ["crates/*"]
 resolver = "3"
 
 [workspace.package]
-version = "0.2.0-alpha.2"
+version = "0.2.0-beta.2"
 edition = "2024"
 license = "MIT"
 repository = "https://github.com/eitsupi/dlin"
@@ -23,7 +23,7 @@ indexmap = "2"
 minijinja = "2"
 rayon = "1"
 globset = "0.4"
-polyglot-sql = { version = "0.4.0", default-features = false, features = ["all-dialects", "semantic"] }
+polyglot-sql = { version = "0.4.2", default-features = false, features = ["all-dialects", "semantic"] }
 path-slash = "0.2.1"
 clap = { version = "4", features = ["derive", "env"] }
 libc = "0.2"
@@ -34,18 +34,14 @@ insta = "1"
 serial_test = "3.4.0"
 
 # internal
-dlin-core = { version = "0.2.0-alpha.2", path = "crates/dlin-core" }
+dlin-core = { version = "0.2.0-beta.2", path = "crates/dlin-core" }
 
 [workspace.lints.rust]
 unexpected_cfgs = { level = "warn", check-cfg = ['cfg(tarpaulin_include)'] }
 
 [profile.dist]
 inherits = "release"
-# FIXME: fat LTO causes polyglot-sql's large match statements to be inlined into
-# the dlin binary, bloating it from ~7.5 MB to ~12 MB. Use thin LTO until the
-# upstream semantic→generate feature dependency is removed from polyglot-sql,
-# after which generator.rs will be excluded from the build entirely.
-lto = "thin"
+lto = "fat"
 codegen-units = 1
 strip = true
 opt-level = "s"

{dlin_cli-0.2.0a2 → dlin_cli-0.2.0b2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dlin-cli
-Version: 0.2.0a2
+Version: 0.2.0b2
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -26,10 +26,12 @@ Project-URL: Repository, https://github.com/eitsupi/dlin
 [![PyPI](https://img.shields.io/pypi/v/dlin-cli)](https://pypi.org/project/dlin-cli/)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/eitsupi/dlin)
 
-dbt lineage analysis CLI that parses SQL files directly. No `dbt compile`, no Python, no `manifest.json`.
+dbt model lineage CLI that parses SQL files directly. No `dbt compile`, no Python, no `manifest.json` (for model-level lineage).
 
 Builds a dependency graph from `ref()` and `source()` calls in SQL. Designed for AI agents and CI pipelines.
 
+Experimental column-level lineage (`dlin column upstream` / `dlin column downstream`) is also available. It requires `dbt compile` and `manifest.json`.
+
 ## Motivation
 
 When I edited dbt models in VS Code, [dbt Power User](https://marketplace.visualstudio.com/items?itemName=innoverio.vscode-dbt-power-user) was my go-to companion for navigating lineage. AI agents have no such companion. I watched them `grep` through dbt projects to find model dependencies. It works, but they end up calling `grep` repeatedly and relying on fragile string matching to piece together `ref()` and `source()` relationships.
@@ -38,7 +40,7 @@ dlin is designed to fill that gap: a CLI tool that lets AI agents understand a d
 
 To replace `grep`, speed and size matter. dlin is a small, self-contained binary with no runtime dependencies. It parses SQL directly, evaluates common Jinja patterns without Python, parallelizes file I/O, and caches aggressively.
 
-The key idea behind dlin is that finding the right models fast is what matters most. AI agents can read SQL and trace column-level relationships on their own; the hard part is knowing which models to look at in the first place. So dlin focuses on model-level lineage and makes that as fast as possible.
+The key idea behind dlin is that finding the right models fast is what matters most. The hard part for agents is knowing which models to look at in the first place. dlin focuses on making model-level lineage as fast as possible, and also offers experimental column-level lineage for deeper analysis.
 
 ## Install
 
@@ -114,11 +116,12 @@ The key line is **"Do NOT grep/cat/find through SQL files"** — without it, age
 
 ## Features
 
-- **No dependencies**: single binary, no Python, no `manifest.json`
+- **No dependencies for model lineage**: single binary, no Python, no `manifest.json`
 - **Recursive upstream / downstream**: `-u N` / `-d N` to control traversal depth
 - **Impact analysis with severity**: `dlin impact` scores downstream nodes and flags exposure reachability
 - **Composable**: stdin accepts model names or file paths; pipe with `jq`, `dlin list`, `git diff`, etc.
 - **Agent-friendly**: `--error-format json` emits structured `{"level","what","why","hint"}` on stderr; `--help` is designed for tool discovery
+- **Column-level lineage** (experimental): traces columns across models with transformation classification; requires `dbt compile` and `manifest.json`
 
 ## Mermaid diagrams
 
@@ -252,6 +255,135 @@ dlin graph -o dot | dot -Tsvg > out.svg                # Graphviz rendering
 
 Output formats: ASCII (default), JSON, Mermaid, Graphviz DOT, Plain, SVG, HTML.
 
+## Column-level lineage (Experimental)
+
+> [!WARNING]
+> Column-level lineage depends on [polyglot-sql](https://github.com/tobilg/polyglot) for SQL parsing. Coverage varies by SQL complexity and dialect. Patterns such as `SELECT *` chains, STRUCT expansion, and some database-specific syntax may not resolve correctly.
+
+`dlin column upstream` and `dlin column downstream` trace columns across models. Unlike model-level commands, they always require a compiled `manifest.json`. Run `dbt compile` first.
+
+```sh
+# Where does each output column of orders come from?
+dlin column upstream orders
+
+# What downstream columns are affected if stg_orders.order_id changes?
+dlin column downstream stg_orders --column order_id
+
+# Mermaid flowchart
+dlin column upstream customers -o mermaid
+dlin column downstream stg_orders --column order_id -o mermaid
+
+# Specific columns only
+dlin column upstream orders --column order_id --column status
+
+# Verify manifest freshness before querying
+dlin check-manifest && dlin column upstream orders
+```
+
+### Column upstream
+
+Traces each output column of a model back to its raw source columns, following references across intermediate models.
+
+```sh
+dlin column upstream customers -o mermaid
+```
+
+```mermaid
+flowchart LR
+  subgraph sg0["customers"]
+    n0_0["customer_id"]
+    n0_1["email"]
+    n0_2["first_name"]
+    n0_3["last_name"]
+    n0_4["lifetime_value"]
+    n0_5["order_count"]
+  end
+  subgraph sg1["orders"]
+    n1_0["order_id"]
+    n1_1["total_amount"]
+  end
+  subgraph sg2["raw.customers"]
+    n2_0["email"]
+    n2_1["first_name"]
+    n2_2["id"]
+    n2_3["last_name"]
+  end
+  subgraph sg3["raw.orders"]
+    n3_0["id"]
+  end
+  subgraph sg4["raw.payments"]
+    n4_0["amount"]
+  end
+  subgraph sg5["stg_customers"]
+    n5_0["customer_id"]
+    n5_1["email"]
+    n5_2["first_name"]
+    n5_3["last_name"]
+  end
+  subgraph sg6["stg_orders"]
+    n6_0["order_id"]
+  end
+  subgraph sg7["stg_payments"]
+    n7_0["amount"]
+  end
+
+  n2_2 -->|"direct"|n5_0
+  n5_0 -->|"direct"|n0_0
+  n2_0 -->|"direct"|n5_1
+  n5_1 -->|"direct"|n0_1
+  n2_1 -->|"direct"|n5_2
+  n5_2 -->|"direct"|n0_2
+  n2_3 -->|"direct"|n5_3
+  n5_3 -->|"direct"|n0_3
+  n4_0 -->|"direct"|n7_0
+  n7_0 -->|"direct"|n1_1
+  n1_1 -->|"aggregation"|n0_4
+  n3_0 -->|"direct"|n6_0
+  n6_0 -->|"direct"|n1_0
+  n1_0 -->|"aggregation"|n0_5
+```
+
+`customer_id`, `email`, etc. pass through `stg_customers` unchanged from `raw.customers` (all `direct`). `lifetime_value` and `order_count` are aggregated at the `customers` model — the final edge to `customers` is labeled `aggregation`, while all upstream hops carry their actual transformation type (here `direct`, since staging and mart models pass columns through unchanged).
+
+Transformation types shown on edges: `direct`, `aggregation`, `expression`, `cast`, `conditional`, `unknown`.
+
+### Column downstream
+
+Traces a column forward to all downstream models and columns that depend on it.
+
+```sh
+dlin column downstream stg_orders --column order_id -o mermaid
+```
+
+```mermaid
+flowchart LR
+  subgraph sg0["customers"]
+    n0_0["order_count"]
+  end
+  subgraph sg1["order_enriched"]
+    n1_0["order_id"]
+  end
+  subgraph sg2["orders"]
+    n2_0["order_id"]
+  end
+  subgraph sg3["stg_orders"]
+    n3_0["order_id"]
+  end
+
+  n2_0 -->|"aggregation"|n0_0
+  n3_0 -->|"direct"|n1_0
+  n3_0 -->|"direct"|n2_0
+```
+
+`stg_orders.order_id` flows directly into `orders.order_id` and `order_enriched.order_id`. `orders.order_id` is then aggregated into `customers.order_count`. Each edge shows its per-hop transformation type.
+
+### Known limitations
+
+- **Requires `dbt compile`**: no SQL parse mode fallback; manifest with compiled SQL is always needed
+- **SELECT \* chains**: resolution depends on YAML column definitions in upstream models; unresolved columns are reported in `errors[]`
+- **Dialect-specific syntax**: pass `--dialect bigquery` (or other dialect) for better coverage
+- **Performance**: first run parses all upstream models; results are cached in `.dlin_cache/` for subsequent queries
+
 ## Key subcommands
 
 ### `list`
@@ -290,7 +422,7 @@ dlin graph --node-type model,source   # filter by node type
 
 ## Data sources
 
-dlin aims to work without `dbt compile`. By default it parses SQL files directly, but it can also leverage a pre-compiled `manifest.json` for additional accuracy when one is available.
+dlin aims to work without `dbt compile` (except for column-level lineage, which always requires `manifest.json`). By default it parses SQL files directly, but it can also leverage a pre-compiled `manifest.json` for additional accuracy when one is available.
 
 **SQL parsing (default)**: extracts `ref()` and `source()` from SQL via regex + Jinja template evaluation. No Python or dbt needed. Generic tests (`not_null`, `unique`, `relationships`, etc.) are inferred from YAML schema declarations.
 

{dlin_cli-0.2.0a2 → dlin_cli-0.2.0b2}/README.md

@@ -4,10 +4,12 @@
 [![PyPI](https://img.shields.io/pypi/v/dlin-cli)](https://pypi.org/project/dlin-cli/)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/eitsupi/dlin)
 
-dbt lineage analysis CLI that parses SQL files directly. No `dbt compile`, no Python, no `manifest.json`.
+dbt model lineage CLI that parses SQL files directly. No `dbt compile`, no Python, no `manifest.json` (for model-level lineage).
 
 Builds a dependency graph from `ref()` and `source()` calls in SQL. Designed for AI agents and CI pipelines.
 
+Experimental column-level lineage (`dlin column upstream` / `dlin column downstream`) is also available. It requires `dbt compile` and `manifest.json`.
+
 ## Motivation
 
 When I edited dbt models in VS Code, [dbt Power User](https://marketplace.visualstudio.com/items?itemName=innoverio.vscode-dbt-power-user) was my go-to companion for navigating lineage. AI agents have no such companion. I watched them `grep` through dbt projects to find model dependencies. It works, but they end up calling `grep` repeatedly and relying on fragile string matching to piece together `ref()` and `source()` relationships.
@@ -16,7 +18,7 @@ dlin is designed to fill that gap: a CLI tool that lets AI agents understand a d
 
 To replace `grep`, speed and size matter. dlin is a small, self-contained binary with no runtime dependencies. It parses SQL directly, evaluates common Jinja patterns without Python, parallelizes file I/O, and caches aggressively.
 
-The key idea behind dlin is that finding the right models fast is what matters most. AI agents can read SQL and trace column-level relationships on their own; the hard part is knowing which models to look at in the first place. So dlin focuses on model-level lineage and makes that as fast as possible.
+The key idea behind dlin is that finding the right models fast is what matters most. The hard part for agents is knowing which models to look at in the first place. dlin focuses on making model-level lineage as fast as possible, and also offers experimental column-level lineage for deeper analysis.
 
 ## Install
 
@@ -92,11 +94,12 @@ The key line is **"Do NOT grep/cat/find through SQL files"** — without it, age
 
 ## Features
 
-- **No dependencies**: single binary, no Python, no `manifest.json`
+- **No dependencies for model lineage**: single binary, no Python, no `manifest.json`
 - **Recursive upstream / downstream**: `-u N` / `-d N` to control traversal depth
 - **Impact analysis with severity**: `dlin impact` scores downstream nodes and flags exposure reachability
 - **Composable**: stdin accepts model names or file paths; pipe with `jq`, `dlin list`, `git diff`, etc.
 - **Agent-friendly**: `--error-format json` emits structured `{"level","what","why","hint"}` on stderr; `--help` is designed for tool discovery
+- **Column-level lineage** (experimental): traces columns across models with transformation classification; requires `dbt compile` and `manifest.json`
 
 ## Mermaid diagrams
 
@@ -230,6 +233,135 @@ dlin graph -o dot | dot -Tsvg > out.svg                # Graphviz rendering
 
 Output formats: ASCII (default), JSON, Mermaid, Graphviz DOT, Plain, SVG, HTML.
 
+## Column-level lineage (Experimental)
+
+> [!WARNING]
+> Column-level lineage depends on [polyglot-sql](https://github.com/tobilg/polyglot) for SQL parsing. Coverage varies by SQL complexity and dialect. Patterns such as `SELECT *` chains, STRUCT expansion, and some database-specific syntax may not resolve correctly.
+
+`dlin column upstream` and `dlin column downstream` trace columns across models. Unlike model-level commands, they always require a compiled `manifest.json`. Run `dbt compile` first.
+
+```sh
+# Where does each output column of orders come from?
+dlin column upstream orders
+
+# What downstream columns are affected if stg_orders.order_id changes?
+dlin column downstream stg_orders --column order_id
+
+# Mermaid flowchart
+dlin column upstream customers -o mermaid
+dlin column downstream stg_orders --column order_id -o mermaid
+
+# Specific columns only
+dlin column upstream orders --column order_id --column status
+
+# Verify manifest freshness before querying
+dlin check-manifest && dlin column upstream orders
+```
+
+### Column upstream
+
+Traces each output column of a model back to its raw source columns, following references across intermediate models.
+
+```sh
+dlin column upstream customers -o mermaid
+```
+
+```mermaid
+flowchart LR
+  subgraph sg0["customers"]
+    n0_0["customer_id"]
+    n0_1["email"]
+    n0_2["first_name"]
+    n0_3["last_name"]
+    n0_4["lifetime_value"]
+    n0_5["order_count"]
+  end
+  subgraph sg1["orders"]
+    n1_0["order_id"]
+    n1_1["total_amount"]
+  end
+  subgraph sg2["raw.customers"]
+    n2_0["email"]
+    n2_1["first_name"]
+    n2_2["id"]
+    n2_3["last_name"]
+  end
+  subgraph sg3["raw.orders"]
+    n3_0["id"]
+  end
+  subgraph sg4["raw.payments"]
+    n4_0["amount"]
+  end
+  subgraph sg5["stg_customers"]
+    n5_0["customer_id"]
+    n5_1["email"]
+    n5_2["first_name"]
+    n5_3["last_name"]
+  end
+  subgraph sg6["stg_orders"]
+    n6_0["order_id"]
+  end
+  subgraph sg7["stg_payments"]
+    n7_0["amount"]
+  end
+
+  n2_2 -->|"direct"|n5_0
+  n5_0 -->|"direct"|n0_0
+  n2_0 -->|"direct"|n5_1
+  n5_1 -->|"direct"|n0_1
+  n2_1 -->|"direct"|n5_2
+  n5_2 -->|"direct"|n0_2
+  n2_3 -->|"direct"|n5_3
+  n5_3 -->|"direct"|n0_3
+  n4_0 -->|"direct"|n7_0
+  n7_0 -->|"direct"|n1_1
+  n1_1 -->|"aggregation"|n0_4
+  n3_0 -->|"direct"|n6_0
+  n6_0 -->|"direct"|n1_0
+  n1_0 -->|"aggregation"|n0_5
+```
+
+`customer_id`, `email`, etc. pass through `stg_customers` unchanged from `raw.customers` (all `direct`). `lifetime_value` and `order_count` are aggregated at the `customers` model — the final edge to `customers` is labeled `aggregation`, while all upstream hops carry their actual transformation type (here `direct`, since staging and mart models pass columns through unchanged).
+
+Transformation types shown on edges: `direct`, `aggregation`, `expression`, `cast`, `conditional`, `unknown`.
+
+### Column downstream
+
+Traces a column forward to all downstream models and columns that depend on it.
+
+```sh
+dlin column downstream stg_orders --column order_id -o mermaid
+```
+
+```mermaid
+flowchart LR
+  subgraph sg0["customers"]
+    n0_0["order_count"]
+  end
+  subgraph sg1["order_enriched"]
+    n1_0["order_id"]
+  end
+  subgraph sg2["orders"]
+    n2_0["order_id"]
+  end
+  subgraph sg3["stg_orders"]
+    n3_0["order_id"]
+  end
+
+  n2_0 -->|"aggregation"|n0_0
+  n3_0 -->|"direct"|n1_0
+  n3_0 -->|"direct"|n2_0
+```
+
+`stg_orders.order_id` flows directly into `orders.order_id` and `order_enriched.order_id`. `orders.order_id` is then aggregated into `customers.order_count`. Each edge shows its per-hop transformation type.
+
+### Known limitations
+
+- **Requires `dbt compile`**: no SQL parse mode fallback; manifest with compiled SQL is always needed
+- **SELECT \* chains**: resolution depends on YAML column definitions in upstream models; unresolved columns are reported in `errors[]`
+- **Dialect-specific syntax**: pass `--dialect bigquery` (or other dialect) for better coverage
+- **Performance**: first run parses all upstream models; results are cached in `.dlin_cache/` for subsequent queries
+
 ## Key subcommands
 
 ### `list`
@@ -268,7 +400,7 @@ dlin graph --node-type model,source   # filter by node type
 
 ## Data sources
 
-dlin aims to work without `dbt compile`. By default it parses SQL files directly, but it can also leverage a pre-compiled `manifest.json` for additional accuracy when one is available.
+dlin aims to work without `dbt compile` (except for column-level lineage, which always requires `manifest.json`). By default it parses SQL files directly, but it can also leverage a pre-compiled `manifest.json` for additional accuracy when one is available.
 
 **SQL parsing (default)**: extracts `ref()` and `source()` from SQL via regex + Jinja template evaluation. No Python or dbt needed. Generic tests (`not_null`, `unique`, `relationships`, etc.) are inferred from YAML schema declarations.
 

{dlin_cli-0.2.0a2 → dlin_cli-0.2.0b2}/crates/dlin/Cargo.toml

@@ -18,6 +18,7 @@ path = "src/main.rs"
 dlin-core = { workspace = true, features = ["clap", "column-lineage"] }
 clap = { workspace = true }
 anyhow = { workspace = true }
+regex = { workspace = true }
 serde_json = { workspace = true }
 path-slash = { workspace = true }
 polyglot-sql = { workspace = true }

{dlin_cli-0.2.0a2 → dlin_cli-0.2.0b2}/crates/dlin/README.md

@@ -4,10 +4,12 @@
 [![PyPI](https://img.shields.io/pypi/v/dlin-cli)](https://pypi.org/project/dlin-cli/)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/eitsupi/dlin)
 
-dbt lineage analysis CLI that parses SQL files directly. No `dbt compile`, no Python, no `manifest.json`.
+dbt model lineage CLI that parses SQL files directly. No `dbt compile`, no Python, no `manifest.json` (for model-level lineage).
 
 Builds a dependency graph from `ref()` and `source()` calls in SQL. Designed for AI agents and CI pipelines.
 
+Experimental column-level lineage (`dlin column upstream` / `dlin column downstream`) is also available. It requires `dbt compile` and `manifest.json`.
+
 ## Motivation
 
 When I edited dbt models in VS Code, [dbt Power User](https://marketplace.visualstudio.com/items?itemName=innoverio.vscode-dbt-power-user) was my go-to companion for navigating lineage. AI agents have no such companion. I watched them `grep` through dbt projects to find model dependencies. It works, but they end up calling `grep` repeatedly and relying on fragile string matching to piece together `ref()` and `source()` relationships.
@@ -16,7 +18,7 @@ dlin is designed to fill that gap: a CLI tool that lets AI agents understand a d
 
 To replace `grep`, speed and size matter. dlin is a small, self-contained binary with no runtime dependencies. It parses SQL directly, evaluates common Jinja patterns without Python, parallelizes file I/O, and caches aggressively.
 
-The key idea behind dlin is that finding the right models fast is what matters most. AI agents can read SQL and trace column-level relationships on their own; the hard part is knowing which models to look at in the first place. So dlin focuses on model-level lineage and makes that as fast as possible.
+The key idea behind dlin is that finding the right models fast is what matters most. The hard part for agents is knowing which models to look at in the first place. dlin focuses on making model-level lineage as fast as possible, and also offers experimental column-level lineage for deeper analysis.
 
 ## Install
 
@@ -92,11 +94,12 @@ The key line is **"Do NOT grep/cat/find through SQL files"** — without it, age
 
 ## Features
 
-- **No dependencies**: single binary, no Python, no `manifest.json`
+- **No dependencies for model lineage**: single binary, no Python, no `manifest.json`
 - **Recursive upstream / downstream**: `-u N` / `-d N` to control traversal depth
 - **Impact analysis with severity**: `dlin impact` scores downstream nodes and flags exposure reachability
 - **Composable**: stdin accepts model names or file paths; pipe with `jq`, `dlin list`, `git diff`, etc.
 - **Agent-friendly**: `--error-format json` emits structured `{"level","what","why","hint"}` on stderr; `--help` is designed for tool discovery
+- **Column-level lineage** (experimental): traces columns across models with transformation classification; requires `dbt compile` and `manifest.json`
 
 ## Mermaid diagrams
 
@@ -230,6 +233,135 @@ dlin graph -o dot | dot -Tsvg > out.svg                # Graphviz rendering
 
 Output formats: ASCII (default), JSON, Mermaid, Graphviz DOT, Plain, SVG, HTML.
 
+## Column-level lineage (Experimental)
+
+> [!WARNING]
+> Column-level lineage depends on [polyglot-sql](https://github.com/tobilg/polyglot) for SQL parsing. Coverage varies by SQL complexity and dialect. Patterns such as `SELECT *` chains, STRUCT expansion, and some database-specific syntax may not resolve correctly.
+
+`dlin column upstream` and `dlin column downstream` trace columns across models. Unlike model-level commands, they always require a compiled `manifest.json`. Run `dbt compile` first.
+
+```sh
+# Where does each output column of orders come from?
+dlin column upstream orders
+
+# What downstream columns are affected if stg_orders.order_id changes?
+dlin column downstream stg_orders --column order_id
+
+# Mermaid flowchart
+dlin column upstream customers -o mermaid
+dlin column downstream stg_orders --column order_id -o mermaid
+
+# Specific columns only
+dlin column upstream orders --column order_id --column status
+
+# Verify manifest freshness before querying
+dlin check-manifest && dlin column upstream orders
+```
+
+### Column upstream
+
+Traces each output column of a model back to its raw source columns, following references across intermediate models.
+
+```sh
+dlin column upstream customers -o mermaid
+```
+
+```mermaid
+flowchart LR
+  subgraph sg0["customers"]
+    n0_0["customer_id"]
+    n0_1["email"]
+    n0_2["first_name"]
+    n0_3["last_name"]
+    n0_4["lifetime_value"]
+    n0_5["order_count"]
+  end
+  subgraph sg1["orders"]
+    n1_0["order_id"]
+    n1_1["total_amount"]
+  end
+  subgraph sg2["raw.customers"]
+    n2_0["email"]
+    n2_1["first_name"]
+    n2_2["id"]
+    n2_3["last_name"]
+  end
+  subgraph sg3["raw.orders"]
+    n3_0["id"]
+  end
+  subgraph sg4["raw.payments"]
+    n4_0["amount"]
+  end
+  subgraph sg5["stg_customers"]
+    n5_0["customer_id"]
+    n5_1["email"]
+    n5_2["first_name"]
+    n5_3["last_name"]
+  end
+  subgraph sg6["stg_orders"]
+    n6_0["order_id"]
+  end
+  subgraph sg7["stg_payments"]
+    n7_0["amount"]
+  end
+
+  n2_2 -->|"direct"|n5_0
+  n5_0 -->|"direct"|n0_0
+  n2_0 -->|"direct"|n5_1
+  n5_1 -->|"direct"|n0_1
+  n2_1 -->|"direct"|n5_2
+  n5_2 -->|"direct"|n0_2
+  n2_3 -->|"direct"|n5_3
+  n5_3 -->|"direct"|n0_3
+  n4_0 -->|"direct"|n7_0
+  n7_0 -->|"direct"|n1_1
+  n1_1 -->|"aggregation"|n0_4
+  n3_0 -->|"direct"|n6_0
+  n6_0 -->|"direct"|n1_0
+  n1_0 -->|"aggregation"|n0_5
+```
+
+`customer_id`, `email`, etc. pass through `stg_customers` unchanged from `raw.customers` (all `direct`). `lifetime_value` and `order_count` are aggregated at the `customers` model — the final edge to `customers` is labeled `aggregation`, while all upstream hops carry their actual transformation type (here `direct`, since staging and mart models pass columns through unchanged).
+
+Transformation types shown on edges: `direct`, `aggregation`, `expression`, `cast`, `conditional`, `unknown`.
+
+### Column downstream
+
+Traces a column forward to all downstream models and columns that depend on it.
+
+```sh
+dlin column downstream stg_orders --column order_id -o mermaid
+```
+
+```mermaid
+flowchart LR
+  subgraph sg0["customers"]
+    n0_0["order_count"]
+  end
+  subgraph sg1["order_enriched"]
+    n1_0["order_id"]
+  end
+  subgraph sg2["orders"]
+    n2_0["order_id"]
+  end
+  subgraph sg3["stg_orders"]
+    n3_0["order_id"]
+  end
+
+  n2_0 -->|"aggregation"|n0_0
+  n3_0 -->|"direct"|n1_0
+  n3_0 -->|"direct"|n2_0
+```
+
+`stg_orders.order_id` flows directly into `orders.order_id` and `order_enriched.order_id`. `orders.order_id` is then aggregated into `customers.order_count`. Each edge shows its per-hop transformation type.
+
+### Known limitations
+
+- **Requires `dbt compile`**: no SQL parse mode fallback; manifest with compiled SQL is always needed
+- **SELECT \* chains**: resolution depends on YAML column definitions in upstream models; unresolved columns are reported in `errors[]`
+- **Dialect-specific syntax**: pass `--dialect bigquery` (or other dialect) for better coverage
+- **Performance**: first run parses all upstream models; results are cached in `.dlin_cache/` for subsequent queries
+
 ## Key subcommands
 
 ### `list`
@@ -268,7 +400,7 @@ dlin graph --node-type model,source   # filter by node type
 
 ## Data sources
 
-dlin aims to work without `dbt compile`. By default it parses SQL files directly, but it can also leverage a pre-compiled `manifest.json` for additional accuracy when one is available.
+dlin aims to work without `dbt compile` (except for column-level lineage, which always requires `manifest.json`). By default it parses SQL files directly, but it can also leverage a pre-compiled `manifest.json` for additional accuracy when one is available.
 
 **SQL parsing (default)**: extracts `ref()` and `source()` from SQL via regex + Jinja template evaluation. No Python or dbt needed. Generic tests (`not_null`, `unique`, `relationships`, etc.) are inferred from YAML schema declarations.