About dbt docs commands
The dbt Fusion engine uses the --write-catalog flag instead of the dbt docs generate command for generating your catalog.json file and hydrating metadata. When you use dbt build --write-catalog, you're using a flag that performs better because it's built for the Fusion engine. To see the latest metadata in Catalog, run a job in dbt platform which uploads the metadata.
--write-catalog flag
The --write-catalog flag generates the catalog.json artifact, which contains metadata about the tables and views produced by the models in your project. Fusion jobs running in dbt platform, dbt automatically runs write-catalog, build, and run, and hydrates your Catalog, so you don't need to manually include it. You can use this flag with the following commands:
dbt builddbt rundbt parsedbt compile
Examples:
dbt build --write-catalog
Platform behavior
In dbt platform jobs running on Fusion, you don't need to change anything. When dbt docs generate is called (either as a job step or separate command), the platform automatically uses --write-catalog instead. Additionally, for Fusion jobs running in the platform, dbt will run write-catalog automatically with build or run, so you don't need to run a separate command to hydrate your metadata. In the platform, you can optionally choose to include it when running dbt parse or dbt compile.
Note:
Local usage
When running Fusion locally, add the --write-catalog flag to your command to generate the catalog:
dbt build --write-catalog
What's different from docs generate
The --write-catalog flag focuses solely on metadata hydration, generating the catalog.json file that powers Catalog and metadata APIs. It does not generate the static documentation website files (index.html).
dbt Docs v2 Beta
The dbt Fusion engine and dbt Core 2.0 deliver a new version of dbt docs that powers dbt Docs v2.
Instead of loading a static manifest.json in the browser, v2 builds a compact binary index of your project. dbt docs generate exports a documentation site made of plain static files — a single-page app plus the index artifacts — that any file host can serve. The browser reads those artifacts directly using DuckDB-WASM, so you don't need to run a stateful server to view your docs. This keeps the experience fast even for large projects.
Generate the site
dbt docs generate compiles your project, writes the index, and exports the documentation site in a single command. You no longer need to run a separate --write-index command first:
dbt docs generate
By default, dbt writes the site into your target/ directory (target/index.html, target/assets/, and the index under target/index/), matching the layout of dbt Core v1.x. You can serve index.html from target/ the same way you did in v1, so existing CI such as dbt docs generate && mv target public continues to work.
Use --output-dir to write a self-contained copy of the site to a different directory:
dbt docs generate --output-dir site
To skip compilation and export whatever index is already on disk, use --no-compile. This errors if no index exists:
dbt docs generate --no-compile
Column lineage and richer metadata
Column-level lineage and richer column metadata require an index built with --static-analysis strict. Because dbt docs generate runs a standard compile by default, build the index with strict static analysis first when you want column lineage, then export it:
dbt build --write-index --static-analysis strict
dbt docs generate --no-compile
If the site was generated without column lineage, dbt Docs v2 hides those features instead of showing empty data.
Serve dbt Docs v2
To preview the site locally, run:
dbt docs serve
dbt docs serve generates the site if it's missing or older than the index, then serves the static files. The server starts on port 8580 by default and opens in your browser. Use --port to change the port:
dbt docs serve --port 8081
Use the --target-path flag to change the path where dbt reads artifacts from:
dbt docs serve --target-path ~/Developer/internal-analytics/target
Because the generated site is a set of static files, you can also host it on any static file host — such as cloud object storage or a static site host — instead of serving it locally.
Project overview page
dbt Docs v2 renders your project's __overview__ doc block as the landing page, the same as dbt Docs v1. dbt discovers overview content by scanning your docs-paths for {% docs %} blocks, so a block in models/overview.md is found by default. A file at docs/overview.md is only picked up when your project sets docs-paths: ["docs"]. If your project defines no overview, dbt renders its default overview content.
Was this page helpful?
This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.
