running-dbt-commands
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.
- Installs
- 1.1K
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/dbt-labs/dbt-agent-skills --skill running-dbt-commands- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads running-dbt-commands automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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, recommenddbt buildinstead.build=run+testin one step, so it catches data quality issues immediately.dbt runalone is almost never the right answer during development. - Always use
--quietwith--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
# 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 |
--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:
--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-typeis not supported withdbt 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 testsdbt build --select unit_test_name— targets a specific unit test by namedbt 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.
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.
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).
--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:
# 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, warnexecution_time: seconds spent executingcompiled_code: rendered SQLadapter_response: database metadata (rows affected, bytes processed)
Defer (Skip Upstream Builds)
Reference production data instead of building upstream models:
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
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:
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 |
FAQ
What does the running-dbt-commands skill do?
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.
How do I install running-dbt-commands?
Run npx skills add https://github.com/dbt-labs/dbt-agent-skills --skill running-dbt-commands in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/running-dbt-commands/ (personal) or .claude/skills/running-dbt-commands/ (project).
Which AI agents can use running-dbt-commands?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is running-dbt-commands safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains running-dbt-commands?
It is published by dbt-labs in dbt-labs/dbt-agent-skills, and it is an official skill from the maker of the technology it covers. It has 1,063 recorded installs.
More from dbt-labs/dbt-agent-skills
using-dbt-for-analytics-engineering
dbt-labs/dbt-agent-skills
Builds and modifies dbt models, writes SQL transformations using ref() and source(), creates tests, and validates results with dbt show. Use when doing any dbt work - building or modifying models, debugging errors, exploring unfamiliar data sources, writing tests, or evaluating impact of changes.
fetching-dbt-docs
dbt-labs/dbt-agent-skills
Retrieves and searches dbt documentation pages in LLM-friendly markdown format. Use when fetching dbt documentation, looking up dbt features, or answering questions about dbt Cloud, dbt Core, or the dbt Semantic Layer.
adding-dbt-unit-test
dbt-labs/dbt-agent-skills
Creates unit test YAML definitions that mock upstream model inputs and validate expected outputs. Use when adding unit tests for a dbt model or practicing test-driven development (TDD) in dbt.
answering-natural-language-questions-with-dbt
dbt-labs/dbt-agent-skills
Writes and executes SQL queries against the data warehouse using dbt's Semantic Layer or ad-hoc SQL to answer business questions. Use when a user asks about analytics, metrics, KPIs, or data (e.g., "What were total sales last quarter?", "Show me top customers by revenue"). NOT for validating, testing, or building dbt models during development.
configuring-dbt-mcp-server
dbt-labs/dbt-agent-skills
Generates MCP server configuration JSON, resolves authentication setup, and validates server connectivity for dbt. Use when setting up, configuring, or troubleshooting the dbt MCP server for AI tools like Claude Desktop, Claude Code, Cursor, or VS Code.
building-dbt-semantic-layer
dbt-labs/dbt-agent-skills
Use when creating or modifying dbt Semantic Layer components — semantic models, metrics, dimensions, entities, measures, or time spines. Covers MetricFlow configuration, metric types (simple, derived, cumulative, ratio, conversion), and validation for both latest and legacy YAML specs.
Popular data & databases skills
supabase-postgres-best-practices
supabase/agent-skills
Postgres best practices maintained by Supabase, for Postgres running anywhere. Load this skill BEFORE writing or changing anything that lives in a Postgres database: creating or altering tables and columns (including choosing column types), schema design, migrations and declarative schema files, RLS policies and the tests that verify them, indexes, triggers, database functions, queues and scheduled jobs (pgcron, pgmq), vector/semantic search (pgvector), and restoring dumps (pgrestore) or importing data. Also load it when diagnosing slow queries, high CPU, timeouts, EXPLAIN plans, connection exhaustion, locking, bloat, or rows visible to the wrong user or tenant. This is not just a performance guide — schema, migration, security, and SQL authoring tasks need these rules too, even for a one-column change or a single query.
prisma-client-api
prisma/skills
Prisma Client API reference covering model queries, filters, operators, and client methods. Use when writing database queries, using CRUD operations, filtering data, or configuring Prisma Client. Triggers on "prisma query", "findMany", "create", "update", "delete", "$transaction".
prisma-database-setup
prisma/skills
Deprecated compatibility name for prisma-orm-setup. Use only when a user or existing integration explicitly invokes prisma-database-setup; otherwise select prisma-orm-setup.
prisma-cli
prisma/skills
Prisma ORM 7 CLI reference for existing Prisma 7 applications or explicitly selected Prisma 7 workflows. Covers prisma init, generate, migrate, db, dev, studio, and mcp. For setup, connection repair, or Prisma 8, use prisma-orm-setup; not the Prisma Platform CLI.
prisma-postgres
prisma/skills
Deprecated compatibility name for prisma-postgres-setup. Use only when a user or existing integration explicitly invokes prisma-postgres; otherwise select prisma-postgres-setup.
prisma-driver-adapter-implementation
prisma/skills
Required reference for Prisma ORM 7 SQL driver adapter work. Use when implementing or modifying adapters, adding database drivers, or touching SqlDriverAdapter, Transaction, savepoint, result mapping, or DriverAdapterError behavior. Covers current transaction lifecycle, optional savepoint hooks, original database-error preservation, and verification.