Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 41 ยท Getting Started

The dbt Command Line

A tour of the dbt commands you use every day: run, test, build, compile, show, ls, seed, snapshot, docs, retry, clean and the flags that work across them.

dbt is driven from the terminal. A small set of commands covers nearly everything, and most of them share the same flags. This lesson is a guided tour, with a stand-in at the end that shows how build orders work. All commands are read-only here; they need a project and a warehouse.

The commands you will use daily

Command What it does
dbt run Builds models (creates views and tables)
dbt test Runs data tests and unit tests
dbt build Runs seeds, models, snapshots and tests together, in DAG order
dbt compile Renders SQL into target/compiled without running it
dbt show Runs a model or query and prints a preview of the rows
dbt seed Loads CSV files from seeds/
dbt snapshot Runs snapshots to record history
dbt docs generate / dbt docs serve Builds and serves the documentation site
dbt ls Lists resources that match a selection
dbt clean Deletes folders listed in clean-targets (like target/)
dbt deps Installs packages from packages.yml
dbt debug Checks setup and connection
dbt retry Re-runs from the point of failure of the last command
dbt run-operation Calls a macro from the command line
dbt parse Parses the project and writes manifest.json

run, test and build

dbt run only builds models. dbt test only tests. Doing them separately has a flaw: a model with bad data is built and passed downstream before its test runs.

dbt build fixes that. It walks the DAG and, for each node, builds it and then runs that node's tests before moving to dependents. If a test fails, everything downstream is skipped. Most teams use build in CI and in production jobs.

Terminal
dbt build
dbt build --select stg_orders+       # a model and everything after it
dbt build --exclude tag:slow

compile and show

dbt compile is the quickest way to see the SQL dbt would run, which matters when you write heavy Jinja. dbt show goes further: it runs the query and prints rows, so you can preview without materializing anything.

Terminal
dbt compile --select customer_orders
dbt show --select customer_orders --limit 10
dbt show --inline "select count(*) as n from {{ ref('stg_customers') }}"

The second form with --inline runs an ad-hoc query that can use ref(). That is a fast way to explore data without creating a scratch file.

Flags shared by most commands

Terminal
dbt run --select stg_orders              # choose resources
dbt run --exclude stg_payments           # remove some from the selection
dbt run --target prod                    # pick an environment
dbt run --vars '{start_date: "2025-01-01"}'
dbt run --threads 8                      # parallelism
dbt run --full-refresh                   # rebuild incremental models from scratch
dbt run --fail-fast                      # stop at the first error
dbt run --defer --state prod-artifacts   # use prod objects for upstream models
dbt --warn-error run                     # turn warnings into errors
dbt --debug run                          # verbose logs

Global flags that apply to dbt itself, such as --debug or --log-format json, come before the command name. Command flags such as --select come after it.

Listing instead of running

dbt ls prints the resources a selection matches, which makes it a safe dry run before a large operation:

Terminal
dbt ls --select +fct_orders
dbt ls --resource-type test
dbt ls --select tag:finance --output json

retry and clean

When a long dbt build stops at one failing model, fix the problem and use dbt retry. It reads run_results.json from the last run and only re-executes the models that failed or were skipped:

Terminal
dbt build
# ... a model fails, you fix its SQL ...
dbt retry

dbt clean removes target/ and dbt_packages/ (the folders in clean-targets of dbt_project.yml). Run dbt deps afterwards to reinstall packages.

A stand-in for build order

To see why build is safer than run then test, here is a small simulation (plain Python, not dbt). Each model has a test; one test is rigged to fail. Watch which models are skipped:

Python Stand-in: build stops downstream of a failed test

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

stg_customers and dim_customers still finish because they do not depend on the broken model. Only the descendants of stg_orders are skipped. That is exactly how dbt build protects downstream tables from bad data.

Reading exit codes in scripts

Every dbt command exits with 0 on success and non-zero on failure, so you can chain them in shell scripts and CI:

Terminal
dbt deps && dbt build --target prod || exit 1

Use --fail-fast in CI when you want feedback quickly.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does dbt build do that dbt run followed by dbt test does not?

    build interleaves builds and tests in DAG order so a failing test stops downstream nodes.
  2. 2. Which command prints a preview of rows without creating a table?

    dbt show runs the query and prints a preview of the result.
  3. 3. After a failure in the middle of a long build, which command re-runs only what failed or was skipped?

    dbt retry reads run_results.json and continues from the point of failure.
  4. 4. Where do global flags like --debug go?

    Global flags come before the command name, for example dbt --debug run.

Summary

  • run builds, test tests, build does both in dependency order and stops downstream of failures.
  • compile and show let you inspect SQL and rows without materializing anything.
  • --select, --exclude, --target, --vars and --full-refresh work across most commands.
  • ls previews a selection; retry continues after a failure; clean and deps manage folders and packages.

Next: How dbt Works: Architecture, Core, Cloud and Fusion