dbt Local Development Guide (Fusion / dbt 2.0)

Purpose

Guide AI agents through installing and configuring dbt on local machines using the dbt Fusion engine (dbt 2.0). Fusion is a single standalone Rust binary — there is no Python requirement, no conda, and no separate dbt-snowflake adapter package to install. The agent runs a diagnostic script, installs Fusion via the official installer, and guides the user through Snowflake configuration.

When to Use This Skill

Activate this skill when users ask about:

• Installing the dbt Fusion engine (dbt 2.0)
• Configuring profiles.yml for Snowflake
• Setting up authentication (PAT, SSO, key pair, OAuth)
• Installing and managing dbt packages
• Troubleshooting connection issues
• Initializing new dbt projects
• Verifying installation and configuration
• Upgrading dbt versions

Official dbt Documentation: Install dbt · dbt Projects on Snowflake

AI Agent Workflow

IMPORTANT: This skill uses non-interactive scripts. The AI agent must:

1. Run the diagnostic script to check the environment
2. Install the Fusion engine if dbt is missing or not on version 2.0.x
3. Verify the installation
4. Guide the user through next steps

Step 1: Check Environment

AI Agent Action: Run the check script to see whether dbt Fusion is already installed:

macOS/Linux:

cd .claude/skills/dbt-core/scripts/
./check-environment.sh

Windows:

cd .claude\skills\dbt-core\scripts\
check-environment.bat

What It Checks:

• Whether dbt is on PATH
• Whether dbt --version reports the Fusion engine (2.0.x)
• snowflake-cli availability (optional, separate tool)
• curl availability (required by the installer)

Output: Structured summary with a recommendation for next steps.

Step 2: Install the dbt Fusion Engine

If dbt is not installed (or is not the Fusion 2.0.x engine), run the installer. Fusion installs to a per-user location and does not require sudo/admin.

macOS/Linux — installs to $HOME/.local/bin, updates PATH, and sets a dbtf alias:

cd .claude/skills/dbt-core/scripts/
./install-dbt.sh

Equivalent one-liner:

curl -fsSL https://public.cdn.getdbt.com/fs/install/install.sh | sh -s -- --update

Windows PowerShell — installs to %USERPROFILE%\.local\bin and updates the user PATH (no admin required):

cd .claude\skills\dbt-core\scripts\
.\install-dbt.ps1

Equivalent one-liner:

irm https://public.cdn.getdbt.com/fs/install/install.ps1 | iex

Step 3: Verify

Open a new terminal (so PATH changes take effect) and confirm the Fusion engine is active:

dbt --version
# Expect: dbt-fusion 2.0.0-preview.x

Step 4: Next Steps

AI Agent Action: Once dbt is installed and verified, guide the user to configure their Snowflake connection (see the profiles.yml configuration section below).

Available Scripts

All scripts are in the scripts/ folder and are non-interactive for AI agent execution:

Diagnostic Script

• check-environment.sh/.bat - Environment check that:

- Confirms dbt is on PATH - Reports the dbt version and verifies it is the Fusion engine (2.0.x) - Checks for the optional snowflake-cli tool and curl - Provides a recommendation for next steps

Installation Scripts

• install-dbt.sh - Install the dbt Fusion engine on macOS/Linux, then print dbt --version
• install-dbt.ps1 - Install the dbt Fusion engine on Windows (no admin), then print

dbt --version

Supporting Files (also in scripts/ folder)

• requirements.txt - Optional supporting Python tools (snowflake-cli, Snowpark, Streamlit, etc.).

dbt itself is not installed here — it comes from the Fusion installer.

Manual Installation

Fusion is a standalone binary installed by the official installer (see Step 2 above). Fusion does not require Python. If you specifically want the Python distribution of dbt 2.0 instead of the standalone binary, pip install --pre dbt is an optional alternative.

• Official dbt Docs:

Core Installation

Snowflake Configuration & Authentication

Configure your Snowflake connection in ~/.dbt/profiles.yml. The profiles.yml documentation covers all authentication methods:

• PAT (Programmatic Access Token) — generate with the Snowflake CLI (recommended)
• SSO authentication with authenticator: externalbrowser
• Key pair authentication
• OAuth authentication
• Multi-environment configurations (dev, prod) via targets
• Account identifier formats (preferred account name and legacy locator formats)

To configure:

1. Create ~/.dbt/profiles.yml with your Snowflake account details
2. Choose and configure your authentication method
3. Test with dbt debug

Official dbt Docs: Snowflake setup · profiles.yml

Package Installation

Add a packages.yml to your project root, then run dbt deps.

Official dbt Docs: Package Management

Verify Installation

Run the diagnostic script to verify the Fusion engine is installed:

# macOS/Linux
cd scripts/
./check-environment.sh

# Windows
cd scripts\
check-environment.bat

The script confirms dbt is on PATH and reports the Fusion (2.0.x) version. To verify the Snowflake connection, use dbt debug.

Troubleshooting

Connection issues: Run dbt debug and check:

• Environment variables set (DBTENVSECRETSNOWFLAKEPAT)
• ~/.dbt/profiles.yml exists and is configured correctly
• Snowflake connectivity: snow sql -q "SELECT CURRENT_USER()"

Package issues: rm -rf dbt_packages/ && dbt deps --upgrade

dbt not found after install: open a new terminal so the updated PATH takes effect, or ensure $HOME/.local/bin (macOS/Linux) / %USERPROFILE%\.local\bin (Windows) is on PATH.

Python compatibility: Not applicable — Fusion is a standalone binary and does not require Python.

Official Docs: Network Issues

Project Initialization

# Non-interactive (recommended for AI agents)
dbt init my_project_name --skip-profile-setup

# Configure ~/.dbt/profiles.yml separately (see Snowflake Configuration above)
# Configure your project with dbt_project.yml (see below)

Project structure: models/, tests/, macros/, seeds/, snapshots/

dbt_project.yml Configuration

Configure your project in dbt_project.yml. Common patterns include:

• Basic project setup (name, version, profile connection)
• Project paths (models, tests, macros, seeds, snapshots)
• Global hooks (on-run-start, on-run-end)
• Global variables for project-wide settings
• Model configurations with materialization defaults
• Medallion architecture pattern (bronze/silver/gold layers)
• Snapshot configurations for SCD Type 2
• Test configurations with failure storage

To configure:

1. Set name to match your project name
2. Set profile to match your profiles.yml profile name
3. Choose your architecture pattern (basic or medallion)
4. Customize materializations and schemas
5. Run dbt debug to verify configuration

Official dbt Docs: dbtproject.yml

# Install packages
dbt deps

# Verify connection
dbt debug

# Load seed data (if any)
dbt seed

# Build specific model
dbt build --select model_name

# Build with dependencies
dbt build --select +model_name+

# Build entire project
dbt build

# Build against production target
dbt build --target prod

# Test production
dbt test --target prod

# Generate documentation
dbt docs generate --target prod

# Update the Fusion engine in place
dbt system update