running-dbt-commands — Claude Code skill for dbt CLI commands

---
name: running-dbt-commands
description: Formats and executes dbt CLI commands, selects the correct dbt executable, and structures command parameters. Use when running models, tests, builds, compiles, or show queries via dbt CLI. Use when unsure which dbt executable to use or how to format command parameters.
user-invocable: false
metadata:
  author: dbt-labs
---

# 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

```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](https://github.com/dbt-labs/dbt-fusion/issues/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` |