dbt-forge docs

dbt-forge is a Python CLI that scaffolds new dbt projects, extends existing ones with models, tests, and CI pipelines, validates project health, and keeps generated files up to date as templates improve.

Use init to create a project. Use add to extend it. Use lint for architectural checks. Use impact for blast radius analysis. Use cost for warehouse spend insights. Use contracts generate for data contracts. Use changelog generate to track breaking changes. Use doctor to validate best practices. Use status for a project overview. Use update to re-apply templates.

Start here

Getting started

Install the CLI, scaffold a dbt project, inspect the generated structure, and run the next commands.

CLI reference

Use the init, add, lint, impact, cost, contracts, changelog, doctor, status, update, and preset reference pages for command syntax, flags, and generated files.

Project structure

See the directories and files created by the scaffold and what each part of the dbt project is for.

Development

Work on the Python CLI in cli/ and the public website in website/.

Problem-led guides

dbt project template

Learn what a practical dbt project template should include and how dbt-forge scaffolds it.

How to scaffold a dbt project

Follow the fastest path from installation to a repeatable dbt project scaffold with init.

Migrate SQL to dbt

Convert legacy SQL scripts into dbt models with ref() and source() using migrate.

dbt project best practices

Review naming, structure, tests, packages, and health checks for a maintainable dbt project.

How to use these docs

• Start with Getting started for the quickest path from install to a working dbt project.
• Use dbt project template when you want to evaluate what should go into a reusable dbt project scaffold.
• Use How to scaffold a dbt project when you want a step-by-step implementation guide.
• Use Migrate SQL to dbt when you are converting legacy SQL scripts into dbt.
• Use dbt project best practices when you want a checklist for maintainable projects.
• Use dbt Mesh project setup when you are planning a multi-project dbt Mesh scaffold.
• Use init when you are creating a new dbt project.
• Use add when you are extending an existing dbt project with new components.
• Use lint when you want to check for architectural issues (fan-out, complexity, drift).
• Use impact when you want to see which downstream models are affected by a change.
• Use cost when you want to find expensive queries and get materialization suggestions.
• Use contracts when you want to generate dbt data contracts from warehouse column types.
• Use changelog when you want to detect breaking schema changes between git refs.
• Use doctor when you want to validate project health and best practices.
• Use status when you want a quick overview of model counts, test coverage, and packages.
• Use update when you want to re-apply dbt-forge templates after upgrading.
• Use preset when you want to enforce team standards across projects.
• Use Project structure when you need to understand the generated layout before editing it.