03 - dbt: CLI Reference

16 min read

dbt: CLI Reference

Quote

“Make it work, make it right, make it fast.”

Source: Kent Beck

Core Commands Overview

CommandWhat it does
dbt runMaterialise models
dbt testExecute schema and singular tests
dbt buildrun + test + seed + snapshot in DAG order
dbt compileRender Jinja → SQL, write to target/compiled/
dbt debugValidate connection and config
dbt depsInstall packages from packages.yml
dbt seedLoad CSV seeds into the warehouse
dbt snapshotExecute snapshot blocks
dbt docs generateBuild the documentation manifest
dbt docs serveServe docs on localhost:8080
dbt source freshnessCheck source table staleness
dbt lsList nodes matching a selector
dbt cleanDelete target/ and dbt_packages/
dbt retryRe-run the last failed invocation

dbt run

Materialise one or more models into the warehouse.

These dbt run examples show how selector scope, state artifacts, and execution flags change the blast radius of a warehouse write.

# Run everything
dbt run
 
# Run a single model
dbt run --select stg_market_data__daily_prices
 
# Run a model and all its downstream dependants
dbt run --select stg_market_data__daily_prices+
 
# Run a model and all its upstream parents
dbt run --select +fct_index_performance
 
# Run a model with both parents and children
dbt run --select +fct_index_performance+
 
# Run all models in a directory
dbt run --select staging/market_data
 
# Run models with a specific tag
dbt run --select tag:daily
 
# Run only models modified since the last production run (state-aware)
dbt run --select state:modified+ --state ./prod_artifacts
 
# Exclude a subtree
dbt run --select marts/ --exclude fct_composite_scores
 
# Pass runtime variables
dbt run --select fct_index_performance --vars '{"lookback_days": 7}'
 
# Target a non-default environment
dbt run --target prod
 
# Parallelism
dbt run --threads 8
 
# Stop immediately on first failure (CI-friendly)
dbt run --fail-fast
 
# Full refresh of an incremental model (rebuild from scratch)
dbt run --select fct_index_performance --full-refresh

dbt test

These dbt test examples narrow execution by layer, model, and test type so data-quality checks stay targeted and cheap.

# Test everything
dbt test
 
# Test only models in the performance mart
dbt test --select marts/performance
 
# Test a single model
dbt test --select fct_index_performance
 
# Test only schema (YAML-defined) tests
dbt test --select test_type:generic
 
# Test only singular (custom SQL) tests
dbt test --select test_type:singular
 
# Run tests tagged "critical"
dbt test --select tag:critical
 
# Store failed rows in the warehouse for inspection
dbt test --store-failures
 
# Continue even after failures (collect all results)
dbt test --no-fail-fast

dbt build

dbt build is the recommended command for CI/CD. It runs seeds, snapshots, models, and tests in DAG-topological order, so a model is tested before its downstream models execute.

These dbt build examples cover full runs, slim CI selection, and broad rebuild scenarios that should be used deliberately.

# Full build
dbt build
 
# Build only the ESG subgraph
dbt build --select +fct_composite_scores
 
# Build only changed nodes and downstream (slim CI pattern)
dbt build --select state:modified+ --defer --state ./prod_artifacts
 
# Validate the selected graph without reading full source volumes
dbt build --empty --select +fct_index_performance
 
# Build with full refresh for incremental models
dbt build --full-refresh --select tag:incremental

Build vs run plus test

dbt build guarantees that if stg_esg__scores tests fail, the downstream int_esg_normalized will never execute. dbt run && dbt test runs all models first, so failures propagate into downstream data before you discover them.

Use --empty for cheap graph validation

Current dbt docs expose dbt build --empty as a schema-only dry run. It still compiles and executes selected models against the warehouse, but it limits refs and sources to zero rows so you can validate dependency wiring and relation creation logic without paying for full input scans.

dbt compile

Renders Jinja templates to plain SQL without executing anything. Useful for debugging macro output.

These compile examples render model SQL into the target artifacts directory so you can inspect the exact statement dbt plans to run.

# Compile everything
dbt compile
 
# Compile one model and inspect the output
dbt compile --select int_daily_returns
# Output written to: target/compiled/financial_platform/models/intermediate/market_data/int_daily_returns.sql

dbt debug

Validates that dbt can connect to the warehouse and that dbt_project.yml parses correctly.

dbt debug checks profile resolution, target selection, adapter connectivity, and project parsing before you spend time on a real build.

dbt debug
# Checks: profiles.yml location, profile/target names, adapter connection,
#         dbt_project.yml validity, package versions

dbt deps

Installs packages declared in packages.yml.

Run dbt deps before compilation when package versions or macros may have changed between environments.

dbt deps

This packages.yml example pins dependency ranges so installs stay within a reviewed compatibility window instead of drifting to arbitrary major versions.

# packages.yml
packages:
  - package: dbt-labs/dbt_utils
    version: [">=1.1.0", "<2.0.0"]
  - package: calogica/dbt_expectations
    version: [">=0.10.0", "<1.0.0"]
  - package: dbt-labs/audit_helper
    version: [">=0.11.0", "<1.0.0"]

dbt seed

Loads CSV files from the seeds/ directory into the warehouse.

These seed commands cover routine loads and the rebuild path you need after a schema change or corrected reference file.

# Load all seeds
dbt seed
 
# Load a specific seed
dbt seed --select ref_gics_sectors
 
# Force drop-and-recreate (useful after schema change)
dbt seed --full-refresh

Typical seeds for a financial platform:

SeedPurpose
ref_gics_sectors.csvGICS sector / industry hierarchy
ref_currency_codes.csvISO 4217 currency codes and FX flags
ref_index_metadata.csvIndex names, base dates, provider codes
ref_trading_calendar.csvExchange trading days (holiday overrides)

dbt snapshot

Executes snapshot definitions to capture SCD Type 2 history.

These snapshot commands run either the full snapshot set or a named temporal capture when you need to isolate one history-bearing resource.

# Run all snapshots
dbt snapshot
 
# Run a specific snapshot
dbt snapshot --select snap_index_constituents

This snapshot definition tracks row history by timestamp and invalidates hard deletes so point-in-time analyses can distinguish active from retired records.

-- snapshots/snap_index_constituents.sql
{% snapshot snap_index_constituents %}
 
{{ config(
    target_schema = 'snapshots',
    unique_key    = 'constituent_key',
    strategy      = 'timestamp',
    updated_at    = 'updated_at',
    invalidate_hard_deletes = true
) }}
 
select
    {{ dbt_utils.generate_surrogate_key(['index_id', 'security_id']) }} as constituent_key,
    index_id,
    security_id,
    weight,
    effective_date,
    updated_at
from {{ ref('stg_market_data__index_constituents') }}
 
{% endsnapshot %}

dbt docs

These docs commands generate the catalog artifacts first and then optionally serve the site locally for model and lineage review.

# Generate the docs site (writes to target/catalog.json + manifest.json)
dbt docs generate
 
# Serve locally (default port 8080)
dbt docs serve
 
# Serve on a custom port
dbt docs serve --port 9090

Documentation is pulled from description: fields in .yml files and rendered with lineage graphs. Every model, source, column, and test is searchable.

dbt source freshness

Checks whether source tables have been updated within the configured freshness window.

These freshness commands cover default monitoring, scoped source checks, and artifact output for downstream alerting systems.

# Check all sources
dbt source freshness
 
# Check sources in the market_data source group only
dbt source freshness --select source:market_data
 
# Write results to a JSON file (useful for alerting pipelines)
dbt source freshness --output target/sources.json

Exit codes: 0 = pass, 1 = warn, 2 = error. Wire 2 into your alerting system.

dbt ls (list)

List DAG nodes without executing anything.

dbt ls is the safest way to confirm selector scope before you run a command that writes warehouse state.

# List all models
dbt ls --resource-type model
 
# List models in the marts layer
dbt ls --select marts/
 
# List all tests for a specific model
dbt ls --select stg_market_data__daily_prices --resource-type test
 
# List models that would be affected by a state:modified selector
dbt ls --select state:modified+ --state ./prod_artifacts
 
# Output as JSON for scripting
dbt ls --output json --select tag:daily

dbt clean

Deletes compiled artifacts and installed packages. Run before a fresh dbt deps.

dbt clean removes generated artifacts so you can force a dependency reinstall or clear stale compiled output.

dbt clean
# Deletes: target/, dbt_packages/

dbt retry

Re-runs the last failed invocation using the same selection and flags. Useful in CI when a transient network error causes a single model failure.

dbt retry only helps after a prior run has already executed nodes and written run results for dbt to replay from the point of failure.

dbt retry

Internally, dbt reads target/run_results.json and re-queues all nodes that did not have status success.

Retry can be a no-op

If the failed command stopped before any nodes executed, dbt retry has nothing useful to replay and will not rebuild the graph for you. Fix the root cause, inspect target/run_results.json if needed, and rerun the scoped command explicitly when the previous failure happened before execution started.

Node Selection Reference

Selector Syntax

SyntaxMeaning
model_nameExact model name
+model_nameModel + all ancestors
model_name+Model + all descendants
+model_name+Model + ancestors + descendants
model_name+2Model + 2 levels downstream
path/to/dirAll models under that directory
tag:tagnameModels with that tag
source:source_nameSource nodes
source:source_name.table_nameSpecific source table
config.materialized:incrementalModels with a config property
state:modifiedNodes changed vs —state artifacts
state:modified+Changed nodes + their downstream
state:newNodes that didn’t exist in —state
exposure:exposure_nameAll models feeding an exposure
metric:metric_nameAll models feeding a metric

Set Operators

These selector combinations show how dbt unions, intersects, and subtracts resource sets before execution.

# Union: run both subgraphs
dbt run --select staging/market_data staging/esg
 
# Intersection: models that match both selectors
dbt run --select "tag:daily,config.materialized:incremental"
 
# Difference (exclude)
dbt run --select marts/ --exclude fct_composite_scores+

Key Flags Reference

FlagCommandsPurpose
--select / -sallNode selector
--excludeallSubtract nodes from selection
--full-refreshrun, buildDrop and recreate incrementals
--varsrun, test, buildPass {key: value} dict as JSON string
--target / -tallOverride profile target
--threadsrun, test, buildParallelism (overrides profile)
--fail-fastrun, test, buildHalt on first failure
--store-failurestest, buildPersist failed rows to warehouse
--deferrun, buildUse prod artifacts for unselected parents
--staterun, build, lsPath to production artifacts directory
--no-partial-parseallForce full re-parse of project
--profiles-dirallOverride default ~/.dbt location
--project-dirallOverride project root directory

—defer and Slim CI Pattern

--defer lets developers run only their changed models in a dev environment, resolving unselected upstream ref() calls against the production schema instead of rebuilding everything.

This slim-CI pattern combines state comparison, deferral, and an explicit target so changed nodes reuse trusted upstream production objects.

# 1. In CI: download prod manifest
dbt run --target prod --select ... # or download from artifact storage
 
# 2. In feature branch CI job:
dbt build \
  --select state:modified+ \
  --defer \
  --state ./prod_artifacts \
  --target dev

This means a developer who only changes int_esg_normalized does not need to rebuild all of stg_esg__scores — dbt will resolve that ref against the production view.

Reading CLI Output

This sample log shows the sequence dbt prints as it discovers nodes, executes them, and summarizes the final pass, warning, error, and skip counts.

Running with dbt=1.8.0
Found 42 models, 18 tests, 4 seeds, 2 snapshots, 5 sources
 
Concurrency: 8 threads (target='dev')
 
1 of 42 START sql view model silver.stg_market_data__daily_prices ......... [RUN]
1 of 42 OK created sql view model silver.stg_market_data__daily_prices ..... [OK in 1.23s]
...
14 of 42 START sql incremental model gold.fct_index_performance ............ [RUN]
14 of 42 OK created sql incremental model gold.fct_index_performance ........ [OK in 8.47s]
...
Finished running 42 models in 0 hours 2 minutes and 11.38 seconds (131.38s).
 
Completed successfully.
 
Done. PASS=42 WARN=0 ERROR=0 SKIP=0 TOTAL=42
StatusMeaning
OKModel materialised successfully
ERRORSQL execution failed
SKIPSkipped because an upstream node failed
WARNTest severity=warn threshold crossed
PASSTest passed
FAILTest failed (severity=error)

Skip propagation

A single ERROR in a staging model will SKIP all downstream intermediates and marts. Always check the first error in the log because it is usually the root cause.

Isolate the root cause before rerunning

Scroll to the first ERROR entry in the log. Subsequent SKIP lines are consequences, not causes. Fix the root model, then use dbt retry to re-run only the failed and skipped nodes without rebuilding the whole graph. In CI, use dbt run --fail-fast to stop immediately and surface the root error clearly.

Graph View

Backlinks