running-dbt-commands

Running dbt Commands

Preferences

1. Use MCP tools if available (dbt_build, dbt_run, dbt_show, etc.) - they handle paths, timeouts, and formatting automatically
2. 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.
3. Always use --quiet with --warn-error-options '{"error": ["NoNodesForSelectionCriteria"]}' to reduce output while catching selector typos
4. Always use --select - never run the entire project without explicit user approval

Quick Reference

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

dbt CLI Flavors

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

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:

Resource type filter:

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.

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.

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

Variables

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

Analyzing Run Results

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

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:

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

Static Analysis (Fusion Only)

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

Common Mistakes