Running dbt Commands

Preferences

Use MCP tools if available (dbt_build, dbt_run, dbt_show, etc.) - they handle paths, timeouts, and formatting automatically
Always use build — even when users say "run" - When a user asks to "run" a model, recommend dbt build instead. build = run + test in one step, so it catches data quality issues immediately. dbt run alone is almost never the right answer during development.
Always use --quiet with --warn-error-options '{"error": ["NoNodesForSelectionCriteria"]}' to reduce output while catching selector typos
Always use --select - never run the entire project without explicit user approval

Quick Reference

bash

# Standard command pattern
dbt build --select my_model --quiet --warn-error-options '{"error": ["NoNodesForSelectionCriteria"]}'

# Preview model output
dbt show --select my_model --limit 10

# Run inline SQL query
dbt show --inline "select * from {{ ref('orders') }}" --limit 5

# With variables (JSON format for multiple)
dbt build --select my_model --vars '{"key": "value"}'

# Full refresh for incremental models
dbt build --select my_model --full-refresh

# List resources before running
dbt list --select my_model+ --resource-type model

dbt CLI Flavors

Three CLIs exist. Ask the user which one if unsure.

Flavor	Location	Notes
dbt Core	Python venv	`pip show dbt-core` or `uv pip show dbt-core`
dbt Fusion	`~/.local/bin/dbt` or `dbtf`	Faster and has stronger SQL comprehension
dbt Cloud CLI	`~/.local/bin/dbt`	Go-based, runs on platform

Common setup: Core in venv + Fusion at ~/.local/bin. Running dbt uses Core. Use dbtf or ~/.local/bin/dbt for Fusion.

Selectors

Always provide a selector. Graph operators:

Operator	Meaning	Example
`model+`	Model and all downstream	`stg_orders+`
`+model`	Model and all upstream	`+dim_customers`
`+model+`	Both directions	`+orders+`
`model+N`	Model and N levels downstream	`stg_orders+1`

bash

--select my_model              # Single model
--select staging.*             # Path pattern
--select fqn:*stg_*            # FQN pattern
--select model_a model_b       # Union (space)
--select tag:x,config.mat:y    # Intersection (comma)
--exclude my_model             # Exclude from selection

Resource type filter:

bash

--resource-type model
--resource-type test --resource-type unit_test

Valid types: model, test, unit_test, snapshot, seed, source, exposure, metric, semantic_model, saved_query, analysis

Fusion: --resource-type is not supported with dbt test (dbt-fusion#1628). To run unit tests in Fusion:

dbt build --select model_name — builds the model first, then runs all tests including unit tests

dbt build --select unit_test_name — targets a specific unit test by name

dbt list --resource-type unit_test — lists unit test names for use in selectors

List

Use dbt list to preview what will be selected before running. Helpful for validating complex selectors.

bash

dbt list --select my_model+              # Preview selection
dbt list --select my_model+ --resource-type model  # Only models
dbt list --output json                   # JSON output
dbt list --select my_model --output json --output-keys unique_id name resource_type config

Available output keys for --output json: unique_id, name, resource_type, package_name, original_file_path, path, alias, description, columns, meta, tags, config, depends_on, patch_path, schema, database, relation_name, raw_code, compiled_code, language, docs, group, access, version, fqn, refs, sources, metrics

Show

Preview data with dbt show. Use --inline for arbitrary SQL queries.

bash

dbt show --select my_model --limit 10
dbt show --inline "select * from {{ ref('orders') }} where status = 'pending'" --limit 5

Important: Use --limit flag, not SQL LIMIT clause.

Variables

Pass as STRING, not dict. No special characters (\, \n).

bash

--vars 'my_var: value'                              # Single
--vars '{"k1": "v1", "k2": 42, "k3": true}'         # Multiple (JSON)

Analyzing Run Results

After a dbt command, check target/run_results.json for detailed execution info:

bash

# Quick status check
cat target/run_results.json | jq '.results[] | {node: .unique_id, status: .status, time: .execution_time}'

# Find failures
cat target/run_results.json | jq '.results[] | select(.status != "success")'

Key fields:

status: success, error, fail, skipped, warn
execution_time: seconds spent executing
compiled_code: rendered SQL
adapter_response: database metadata (rows affected, bytes processed)

Defer (Skip Upstream Builds)

Reference production data instead of building upstream models:

bash

dbt build --select my_model --defer --state prod-artifacts

Flags:

--defer - enable deferral to state manifest
--state <path> - path to manifest from previous run (e.g., production artifacts)
--favor-state - prefer node definitions from state even if they exist locally

bash

dbt build --select my_model --defer --state prod-artifacts --favor-state

Static Analysis (Fusion Only)

Override SQL analysis for models with dynamic SQL or unrecognized UDFs:

bash

dbt run --static-analysis=off
dbt run --static-analysis=unsafe

Common Mistakes

Mistake	Fix
Using `test` after model change	Use `build` - test doesn't refresh the model
Running without `--select`	Always specify what to run
Using `--quiet` without warn-error	Add `--warn-error-options '{"error": ["NoNodesForSelectionCriteria"]}'`
Running `dbt` expecting Fusion when we are in a venv	Use `dbtf` or `~/.local/bin/dbt`
Schema errors after changing files in Fusion	Run `dbt clean` to clear the stale schema cache, then re-run
Adding LIMIT to SQL in `dbt_show`	Use `limit` parameter instead
Vars with special characters	Pass as simple string, no `\` or `\n`