dbt-colibri

A lightweight, developer-friendly CLI tool and self-hostable dashboard for extracting and visualizing column-level lineage from your dbt projects.

Built for data teams who want transparent, flexible lineage tracking without vendor lock-in or complex enterprise tooling.

🎯 Why dbt-colibri?

• 🔍 Complete visibility: Easy UI, track how every column flows through your dbt transformations
• ⚡ Fast & lightweight: Generate reports in seconds from your existing dbt artifacts
• 🏠 Self-hosted: No cloud dependencies or external services required

Live demo of dashboard: https://b-ned.github.io/colibri-demo/

🚀 Quick Start

Installation

# Using uv (recommended)
uv add dbt-colibri

# Using pip
pip install dbt-colibri

Basic Usage

• Run dbt to generate the required artifacts:

  dbt compile
  dbt docs generate
  

• Generate lineage report:

  colibri generate
  

• View results: Open dist/index.html in your browser

That's it! Your column lineage dashboard is ready. Note you can also use dbt run, to generate the manifest.json.

📖 Documentation

CLI Commands

colibri generate

Generates column lineage reports from your dbt project.

colibri generate [OPTIONS]

Options:

• --manifest-path: Path to dbt manifest.json (default: target/manifest.json)
• --catalog-path: Path to dbt catalog.json (default: target/catalog.json)
• --output-dir: Output directory (default: dist/)
• --help: Show help message

Output Files

• colibri-manifest.json: Lineage data
• index.html: Interactive (standalone) visualization dashboard

Project Structure

your-dbt-project/
├── target/
│   ├── manifest.json    # Generated by dbt
│   └── catalog.json     # Generated by dbt docs generate
└── dist/                # Generated by colibri
    ├── index.html       # Interactive dashboard
    └── colibri-manifest.json

🔧 Advanced Usage

CI/CD Integration

The easiest way to deploy your static html is through github/gitlab pages (if you are on enterprise license you can do this privately)

You can find the full example workflow at docs/github_pages_example.yml.

General idea

• After every change to the production dbt code (push the main branch), GitHub Actions will:
  • Set up Python and install dependencies with uv.
  • Compile and generate docs needed for colibri.
  • Run colibri generate to build the static HTML report in the dist/ folder.
• The dist/ folder is uploaded as an artifact and deployed natively to GitHub Pages using the official actions/deploy-pages action.
• The result is available at your repository’s Pages URL.

Gitlab has similar functionality. Other options are writing the file to a bucket and mount it into a web server container (nginx).

🛠️ Technical Details

Requirements

• Python: tested on versions 3.9, 3.11, 3.13

• Supported dbt Adapters:

  • Snowflake,
  • BigQuery,
  • Redshift,
  • duckDB,
  • Postgres

dbt Compatibility

dbt-core Version	Status
1.8.x	✅ Tested
1.9.x	✅ Tested
1.10.x	✅ Tested

Architecture

dbt-colibri leverages:

• SQLGlot for SQL parsing and column lineage extraction
• dbt artifacts (manifest.json, catalog.json) for metadata
• Static HTML/JS for zero-dependency dashboard deployment

🤝 Contributing

We welcome contributions! Raise an issue or request a feature, if you are open to contribute you can let us now in the issue.

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Development Setup

# Clone the repository
git clone https://github.com/your-org/dbt-colibri.git
cd dbt-colibri

# Install development dependencies
uv sync --dev

# Run tests
pytest

# Format code
ruff format

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

This project builds upon excellent open source work:

• dbt-column-lineage-extractor - Original column lineage extraction logic
• SQLGlot - SQL parsing and transformation
• elementary-data - Inspiration for static HTML report structure

From one dbt user to another — built to make your workflow better.