Guides

dbt-check CLI Guide

Run npx clarilayer dbt-check to find docs-vs-warehouse drift in your dbt project locally, and review what you choose to keep in ClariLayer.

Your dbt project carries two descriptions of your data: the YAML docs you wrote and the warehouse dbt actually built. They drift apart quietly — a column gets renamed in a migration, a model stops being materialized, a description survives three refactors untouched. npx clarilayer dbt-check reads the two artifacts dbt already builds and reports where your documentation and your warehouse disagree. It runs against local files and finishes in one command; the check itself needs no context key — only the optional save step (--save, in v0.2.0 and later) authenticates.

What it checks

Four drift classes, then coverage:

Phantom columns — the headline check: a column documented in your YAML that does not exist in the built relation. uace_cd documented, warehouse has uace_code — the doc reads fine in review and quietly grounds every reader wrong.
Missing from the catalog — a non-ephemeral model that appears in the manifest but is absent from the warehouse catalog: the project documents a relation this catalog does not contain.
Type-family mismatches — the documented type and the cataloged type disagree at the type-family level. The check is conservative: spelling variants within the same family are left alone rather than flagged as noise.
Hollow descriptions — a documented column whose description is empty or whitespace: a docs slot that exists but says nothing.
Coverage stats — last, the blunt numbers: how many of your models and columns carry documentation at all.

Quickstart

From the dbt project root:

dbt docs generate
npx clarilayer dbt-check

dbt docs generate writes target/manifest.json (what you documented) and target/catalog.json (what the warehouse reports as built). dbt-check reads those two local files and prints the drift report in your terminal. The artifacts stay local — the check reads them where they are and uploads nothing.

Reading the report

The terminal report is ordered by severity, the same order as the list above: phantom columns and models missing from the catalog lead, type-family mismatches follow, hollow descriptions after that, and coverage stats close the report.

When a phantom column is a near miss of a real one, the report includes a rename suggestion: uace_cd looks like the warehouse's uace_code, so the likely fix is a one-line YAML edit, not an investigation. Suggestions are exactly that — suggestions; the report never rewrites your project.

The terminal view is a summary capped at the top findings per class (--top, default 10). Two flags change the output shape:

--md <file> writes the full report — every finding, not just the top slice — as shareable Markdown, ready to drop into a PR description or a team channel.
--json emits a machine-readable report on stdout. Stdout is pure JSON and all human-readable output goes to stderr, so piping stdout into jq or a script works without cleanup.

Exit codes report whether the check ran, not whether drift exists: 0 means the check completed — findings or not — and 2 means it could not run cleanly (a usage error, an unreadable or over-limit artifact, or a report file that could not be written). A script that needs to detect drift should read the --json output and inspect the findings themselves — for example, findings.length.

Flags

--project-dir <path> — run against a dbt project other than the current directory.
--target-path <path> — read artifacts from a custom target directory instead of target/.
--md <file> — write the full Markdown report to a file.
--top <n> — findings shown per class in the terminal report (default 10).
--json — machine-readable JSON on stdout, human output on stderr.
--max-artifact-mb <n> — size guard: refuse to parse artifacts larger than this many megabytes (default 300).

Saving findings (v0.2.0)

A drift report you read once is a to-do list; the same findings saved as context keep grounding your agent after the terminal closes. In v0.2.0 and later, --save stages up to 24 findings plus a run summary into your ClariLayer Context Inbox as proposals, over the same propose_batch path an agent harvest uses. Nothing is auto-saved: each proposal waits in the Inbox for you to accept or reject it. What you accept is stored as an asserted schema note carrying the drift details — the phantom column, the suggested rename, the mismatched type families — so your agent recalls the known drift the next time it touches that model.

--save — stage the findings and the run summary as Context Inbox proposals.
--save-top <n> — cap how many findings are staged.
--key cl_… — the context key that authenticates the save; or set CLARILAYER_CONTEXT_KEY in the environment instead. Mint a key at /connect-ai.
--dry-run — print the exact payload --save would send, and send nothing.

The privacy boundary

Your raw manifest.json and catalog.json never leave your machine — the check reads them locally and uploads neither artifact. What --save sends is not the artifacts but bounded finding metadata derived from them — the affected model and column names, the actual warehouse type behind a mismatch, a rename candidate — and only for the findings you explicitly stage. --dry-run shows you that exact payload before anything is sent at all.

Drift findings, not verification

Everything this CLI reports is a drift finding: a place where two artifacts you already own disagree with each other. A finding does not "verify" anything, and neither does saving one — ClariLayer never marks an entry "verified". Live entry statuses are asserted and caveat only: a saved finding enters your store as an asserted schema note, and caveat is earned through the product's reconcile verb checking a saved definition against supported source evidence — not through this CLI. See Verified vs Asserted for the full trust model.