OpenParable
Skip to content
← Back to skills

Run Dbt Commands

Testing & Quality
run-dbt-commands

Run Dbt Commands is an Agent Skill for testing & quality published in the duneanalytics/spellbook repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Run dbt CLI commands (compile, ls, test, run, etc.) in the spellbook repo. Use when the user asks to compile, list, test, or run dbt models, or when you need to validate SQL by compiling a model.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/duneanalytics/spellbook/blob/HEAD/.claude/skills/run-dbt-commands/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/run-dbt-commands, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Run dbt Commands

Prerequisites

dbt commands require project dependencies synced with uv. Before running any dbt command:

  1. Sync the project environment from the repo root:
uv sync --locked
  1. Navigate to the correct sub-project directory before running dbt commands:
cd dbt_subprojects/<project_name>/

Determining the Correct Sub-Project

The repo has six sub-projects under dbt_subprojects/:

Sub-projectContents
daily_spellbookDefault for most spells (daily refresh)
hourly_spellbookHigh-frequency spells (Dune team managed)
dexDEX trading data (dex.trades, aggregators)
nftNFT models
solanaSolana-specific models
tokensToken metadata, transfers, balances

How to pick: Look at where the model file lives. A model at dbt_subprojects/solana/models/... requires cd dbt_subprojects/solana/. If the user specifies a model name without a path, search for the .sql file to determine its sub-project.

Running Commands

All dbt commands must be run from inside a sub-project directory (dbt_subprojects/<project_name>/).

Using uv run from the Shell tool

The Shell tool starts a fresh shell. Use uv run to execute dbt commands in the project's locked environment:

uv run dbt compile -s model_name --project-dir dbt_subprojects/<project_name>/

Or navigate first, then use uv run:

cd dbt_subprojects/<project_name>/ && uv run dbt compile -s model_name

Important: Always use uv run when executing via the Shell tool. Do NOT use bare dbt commands unless you've manually activated .venv.

Common commands

uv run dbt deps                        # install dbt package dependencies (run once per sub-project)
uv run dbt compile                     # compile all models to target/
uv run dbt compile -s model_name       # compile a single model
uv run dbt ls -s model_name            # list/check model selection
uv run dbt test -s model_name          # run tests for a model

First time in a sub-project

Run uv run dbt deps once before dbt compile or other commands to pull dbt package dependencies. Subsequent runs in the same sub-project don't need dbt deps again unless packages.yml changed.

Compiled output

After dbt compile, the rendered SQL is at:

dbt_subprojects/<project_name>/target/compiled/<project_name>/models/.../model_name.sql

Workflow Example

# From repo root — compile a specific model in daily_spellbook
cd dbt_subprojects/daily_spellbook/ && uv run dbt compile -s stablecoins_balances

Or using --project-dir without changing directory:

uv run dbt compile -s stablecoins_balances --project-dir dbt_subprojects/daily_spellbook/

Troubleshooting

  • "dbt: command not found" — Run uv sync --locked and use uv run dbt ....
  • Permission errors on log files — Request required_permissions: ["all"] on the Shell tool call so dbt can write to its logs directory.
  • Compilation errors about missing refs — You may be in the wrong sub-project. Check where the model file lives.
  • "Could not find profile" — Make sure you're targeting a sub-project directory, not the repo root.