|  |     |        |                |  |               
  _` |   _ \   _| ____| _|   _ \   _ \  |   _ \   _ \ \ \ /
\__,_| _.__/ \__|     \__| \___/ \___/ _| _.__/ \___/  _\_\

A powerful CLI toolkit to supercharge your dbt development workflow

Built with the tools and technologies:

dbt-toolbox

A powerful CLI toolkit that supercharges your dbt development workflow with intelligent caching, dependency analysis, and enhanced documentation generation.

🚀 What Makes dbt-toolbox Amazing

Smart Caching & Performance

• Lightning-fast model parsing with intelligent cache invalidation
• Persistent Jinja environment caching for instant macro resolution
• Dependency graph caching for rapid upstream/downstream analysis
• Test-aware caching: re-runs models when test definitions change or tests fail (build only)
• Fuzzy model name matching to catch typos automatically

Enhanced dbt Commands

• dt build - Drop-in replacement for dbt build with enhanced output and performance
• dt run - Drop-in replacement for dbt run with smart execution and caching
• Target-specific options for environment control
• Intelligent pre/post processing hooks

LLM Ready via MCP server

• Contains mcp server to make your LLM powered dbt development even better.
• Tools support the most common dbt-toolbox featuers.

Intelligent Documentation

• dt docs - YAML documentation generator with smart column inheritance
• Automatically inherits descriptions from upstream models and macros
• Tracks column changes (additions, removals, reordering) between runs
• One-click clipboard integration

Dependency Intelligence

• Lightweight DAG implementation for model and macro relationships
• Efficient upstream/downstream traversal
• Node type tracking and statistics
• Perfect for impact analysis and refactoring

Configuration

• Multi-source settings hierarchy (env vars > TOML > dbt profiles > defaults)
• Dynamic dbt profile and target integration
• Source tracking for all configuration values

🛠️ Installation

# Using uv
uv add dbt-toolbox

# Or install with pip
pip install dbt-toolbox

# Install with MCP server support
uv add "dbt-toolbox[mcp]"

⚡ Quick Start

# Initialize and explore your project
dt settings                    # View all configuration

# Enhanced dbt commands with caching
dt build                      # Build with intelligent caching
dt run --model +my_model+     # Support for most dbt selection syntax
dt build --target prod        # Build against production target

# Analyze cache and dependencies
dt analyze                    # Analyze all models
dt analyze --model customers+ # Analyze specific model selection

# Generate documentation YAML
dt docs --model customers     # Generate docs for specific model
dt docs -m orders --clipboard # Copy to clipboard

📋 Core Commands

MCP Server Integration

dbt-toolbox can also run as an MCP (Model Context Protocol) server, enabling integration with external tools and AI assistants like Claude Code.

Key Features:

• Expose dbt-toolbox functionality through standardized MCP protocol
• Same intelligent caching and validation as CLI commands
• Perfect for AI-assisted dbt development workflows

Quick Setup:

# Install with MCP support
uv add "dbt-toolbox[mcp]"

# Available MCP tools:
# - analyze_models: Validate model references and column lineage
# - build_models: Build models with intelligent execution

For detailed MCP server setup and usage, see MCP.md.

🏗️ Key Features

Intelligent Caching System

dbt-toolbox caches parsed models, macros, and Jinja environments in .dbt_toolbox/ directory with smart invalidation based on file changes and project configuration. After upgrading dbt-toolbox, run dt clean to clear the cache.

Smart Execution & Lineage Validation

• Only executes models that actually need rebuilding based on dependency analysis
• Optional lineage validation to catch broken references before execution
• Configurable model validation ignore lists for legacy models
• Cache validity controls for optimal performance

Dependency Graph Analysis

Lightweight DAG implementation provides efficient model relationship tracking:

• Upstream/downstream dependency resolution
• Node type classification (models, macros, sources)
• Impact analysis for refactoring

Enhanced CLI Experience

• Colored output with progress indicators
• Target-specific execution (--target option)
• Command shadowing for seamless dbt integration
• Comprehensive error handling and reporting

Smart Documentation Generation

The dt docs command intelligently inherits column descriptions from:

• Upstream model columns with matching names
• Macro parameters that reference the columns
• Existing schema.yml documentation

⚙️ Configuration

dbt-toolbox supports configuration through multiple sources with the following precedence:

1. Environment Variables (highest priority)
2. TOML Configuration (pyproject.toml)
3. dbt Profiles (for SQL dialect)
4. Auto-detection (for project paths)
5. Defaults (lowest priority)

Key Configuration Options

For an exhaustive list see CLI.md

Configuration Examples

Environment Variables:

export DBT_TOOLBOX_ENFORCE_LINEAGE_VALIDATION=false
export DBT_TOOLBOX_MODELS_IGNORE_VALIDATION="legacy_model,staging_temp"
export DBT_TOOLBOX_CACHE_VALIDITY_MINUTES=720 # Default=1440

TOML Configuration:

[tool.dbt_toolbox]
enforce_lineage_validation = false
models_ignore_validation = ["legacy_model", "staging_temp"]
cache_validity_minutes = 720 # Default=1440

📚 Documentation

• CLI Reference - Detailed command documentation and examples
• MCP Server Guide - MCP server setup and integration
• Contributing Guide - Development setup and guidelines

🧪 Testing Integration

dbt-toolbox includes a testing module for your dbt projects:

from dbt_toolbox.testing import check_column_documentation

def test_model_documentation():
    """Ensure all model columns are documented."""
    result = check_column_documentation()
    if result:
        pytest.fail(result)

⭐ Roadmap

• dt docs: Automatic yaml docs generation.
• Smart model selection: Smart caching and model selection for optimized executions.
• MCP Server: Publish commands via MCP server.
• Expand testing stack: Build out the dbt_toolbox.testing stack.
• dt test Command, with test parsing and caching.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for development setup, coding standards, and contribution guidelines.

📄 License

MIT License - Feel free to use this project in your own work.

🙏 Acknowledgments

Built with modern Python tooling:

• Typer for the CLI framework
• SQLGlot for SQL parsing and optimization
• Jinja2 for template processing
• yamlium for YAML manipulation and generation
• uv for dependency management