Metadata-Version: 2.4
Name: dbt-lens
Version: 0.3.0
Summary: CLI tool for navigating and understanding dbt projects
Author: Ishan Yash
License-Expression: MIT
License-File: LICENSE
Keywords: analytics,cli,dbt,lineage
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Requires-Dist: click>=8.0
Requires-Dist: rapidfuzz>=3.0
Requires-Dist: rich>=13.0
Requires-Dist: sqlglot<26.0,>=20.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# dbt-lens

CLI tool for navigating and understanding dbt projects. Read your `manifest.json` and get instant answers about impact, lineage, and project health — no warehouse connection required.

## Install

```bash
pip install dbt-lens
```

## Quick Start

```bash
# Generate your manifest first
dbt compile

# See what breaks if you change a model
dbt-lens impact stg_orders

# Trace a column back to its source
dbt-lens trace mrt_daily_revenue.gross_revenue

# Git-aware blast radius
dbt-lens diff

# Project health report
dbt-lens health
```

## Commands

### Navigation

| Command | Description |
|---------|------------|
| `impact <model>` | Show downstream models/tests affected by a change |
| `upstream <model>` | Trace a model back to its sources |
| `find <query>` | Fuzzy search across models, columns, macros |

### Column Lineage

| Command | Description |
|---------|------------|
| `trace <model.column>` | Trace a column's lineage back through upstream models to its source |
| `explain <model>` | Auto-generated model summary: sources, joins, filters, aggregations |

### Git Integration

| Command | Description |
|---------|------------|
| `diff` | Git-aware impact analysis — changed files → downstream blast radius → dbt selector |
| `macro-impact <macro>` | Show all models affected by a macro, including transitive macro chains |

### Project Health

| Command | Description |
|---------|------------|
| `health` | Test coverage, documentation gaps, model size warnings, source freshness |

## Global Options

| Option | Default | Description |
|--------|---------|------------|
| `--manifest PATH` | `target/manifest.json` | Path to manifest.json |
| `--format terminal\|json` | `terminal` | Output format |
| `--dialect DIALECT` | auto-detect | sqlglot dialect override (bigquery, snowflake, postgres) |

## Examples

### Impact analysis
```
$ dbt-lens impact stg_orders

stg_orders (staging | view)
├── int_orders_enriched (intermediate | view)
│   └── dim_order (dimension | table) ← 2 tests
│       └── mrt_order_summary (mart | table) ← 1 test
└── ...

 5 models affected │ 3 tests │ 3 layers deep
```

### Column trace
```
$ dbt-lens trace mrt_order_summary.customer_name

mrt_order_summary.customer_name
  <- dim_customer.name
    <- stg_customers.name
      <- customers.name
```

### Diff
```
$ dbt-lens diff

 Modified files (vs main):
  models/staging/stg_orders.sql

 Blast radius:
  stg_orders → 5 downstream models, 3 tests

 Total: 5 unique models affected

 Suggested selector:
  dbt build -s stg_orders+
```

### Macro impact
```
$ dbt-lens macro-impact filter_test_emails

 Macro chain:
  filter_test_emails
  └── filter_and_validate_emails (depends on filter_test_emails)

 Models using this chain (direct + transitive): 2
  dimension:    2
```

## Requirements

- Python >= 3.9
- dbt-core >= 1.4 (manifest v7+)
- No warehouse connection needed — reads `manifest.json` only

## License

MIT
