How dbt Wizard works
dbt Wizard helps teams develop, troubleshoot, harden, and ship trusted dbt projects faster and with less risk.
Built for governed data development in dbt, dbt Wizard understands the full project, routes to the right dbt tools, and validates work with awareness of warehouse operations, including dev builds, compute costs, run time, and post-build inspection. Use dbt Wizard to investigate failed runs, debug model issues, assess downstream impact, make changes, validate results, and ship trusted data work in one place.
Unlike general coding agents, dbt Wizard is aware of warehouse operations. It understands that validation can mean compiling code, building to a dev schema, considering compute and run time, and proposing what to inspect after the build completes.
Most of how dbt Wizard works is the same in the dbt platform and in the terminal CLI. The following sections explain shared behavior first, then call out what differs in each environment.
Native metadata engine
dbt Wizard ships with a metadata engine — a pre-built, structured index of your entire project that's ready before your first prompt.
Think of it like a map of your whole city: dbt Wizard knows how everything connects before it starts, rather than walking every street to figure out the layout.
That index gives dbt Wizard four capabilities that aren't possible from file-reading alone:
| Capability | Description |
|---|---|
| Impact analysis | When you ask "what breaks if I change this column?", dbt Wizard returns the exact set of downstream models, metrics, tests, and exposures affected — instantly, from the index. Column-level lineage is tracked, so dbt Wizard knows not just which models reference a table, but which ones reference that specific column. |
| Health checks | dbt Wizard knows which models have tests, which don't, which have stale data, which have failing contracts, and which had recent run failures — as a structured dataset. You can ask "what's unhealthy in this part of my DAG?" and get a precise answer without running anything. |
| Data profiling | dbt Wizard can profile your data — row counts, column distributions, null rates — and use that context when deciding how to build or refactor a model. It can reason about your data without materializing models or running expensive queries. |
| Validation planning | dbt Wizard uses project metadata to identify affected resources and choose relevant checks. In the CLI, you control the depth of structured validation before commands run. |
dbt Wizard builds and updates this index from dbt artifacts. In the dbt platform, project state comes from your connected development environment. In the terminal, run dbt parse, dbt compile, or dbt build before a session so dbt Wizard has your latest local project state.
The dbt version dbt Wizard displays comes from your project's manifest (target/manifest.json), not the dbt executable on your PATH. If you generated the manifest with a different binary, dbt Wizard reports that version until you recompile. Run dbt compile (or dbt parse/dbt build) with your intended dbt to refresh the manifest and the displayed version.
Validation mechanics
Validation can combine static checks, dbt commands, development builds, downstream impact analysis, and development-to-production comparisons. The checks that run depend on the surface, available tools, project state, permissions, and the validation depth you approve.
In dbt Wizard CLI, choose light, medium, heavy, or skipped validation. Medium validation is the default:
- Light validation focuses on syntax, linting where supported, tests, and code review without materializing the changed models.
- Medium validation adds development materialization and downstream checks.
- Heavy validation adds explicit expectations and development-to-production comparisons when the required relations are available.
dbt Wizard reports failures and checks it couldn't complete. A passing check doesn't remove the need to review business logic, and a skipped check should remain visible in your review. For a complete procedure and the approval points for warehouse commands, refer to Validate dbt changes with dbt Wizard.
Tools and capabilities
dbt Wizard takes action through a defined set of tools — from reading files to running dbt commands — so you can see exactly what it's doing and why.
| Tool | Purpose | Where available |
|---|---|---|
| File read/write | Read files and propose edits as diffs | Platform and CLI |
| Project queries | Query lineage, tests, metadata, metrics, and run results | Platform and CLI |
| dbt commands | Run commands like dbt compile, dbt build, and dbt test | Platform and CLI |
| Bash | Execute shell commands in your project directory | CLI only |
| Web search | Look up dbt docs and troubleshooting information | Platform and CLI |
| MCP | Access connected MCP servers | CLI (add servers); platform includes built-in docs and platform context |
dbt Wizard never runs destructive commands (such as dbt build --full-refresh, dbt run --full-refresh, or git reset --hard) without approval.
Skills and memories
dbt Wizard supports reusable skills and memories that help it apply your team's conventions across sessions.
| Feature | Description |
|---|---|
| Skills | Standardize repeatable workflows and best practices. For example, a skill can tell dbt Wizard how your team structures staging models, writes tests, or documents columns. |
| Memories | Store project-specific context that should carry between sessions. For example, dbt Wizard can remember that your project uses customer_id as the standard customer key or that finance models require extra review. |
dbt Wizard automatically loads skills from your project and local directories in both the platform and the CLI. In the platform, start a new chat after adding or changing skills so they are picked up.
Refer to the Skills page for more details.
In the dbt platform
Use dbt Wizard in the dbt platform from the home app or Studio IDE. An admin must enable dbt Wizard for your account first.
Approval and review
By default, dbt Wizard keeps you in control before it changes your project or runs commands.
In the platform:
- dbt Wizard shows file edits as diffs for you to accept or reject before anything is persisted
- dbt commands ask for confirmation before running
- In the home app and Studio IDE, toggle Ask for approval or Edit files automatically to choose how much freedom the agent has per session
There is no bash sandbox in the platform — shell access is not exposed the way it is in the CLI.
Sessions and conversations
In the platform, a session is a saved conversation in the dbt Wizard panel or home app:
- Ask follow-up questions without restating full context
- Continue an earlier investigation, refactor, or validation task
- Review prior prompts, responses, and proposed changes in the conversation list
Start a new session with Start new dbt Wizard chat in the panel. Chat history is retained for 90 days. Refreshing the same browser tab keeps your active session; opening a new tab starts empty.
For Studio-specific behavior and availability, refer to dbt Wizard in Studio IDE.
In the terminal (CLI)
Use the dbt Wizard CLI for local development.
Connections and authentication (MCP)
dbt Wizard can connect to MCP servers from the CLI, including the dbt MCP server, for access to platform APIs, Semantic Layer metadata, and cross-project context. For the complete setup (like supported server types, configuration keys, authentication, and examples), refer to Use MCP servers with the dbt Wizard CLI.
To connect to an MCP server, run the following commands, replacing MCP_NAME with a name of your choice and YOUR_MCP_URL with the URL of the MCP server:
wizard mcp add MCP_NAME --url https://YOUR_MCP_URL
wizard mcp login MCP_NAME
You can see more options by running wizard mcp --help.
For example, to connect to the dbt MCP server, replace DBT_MCP_ENDPOINT with your endpoint and run:
wizard mcp add dbt --url DBT_MCP_ENDPOINT
You should see output similar to Added global MCP server 'dbt'. Then authenticate:
wizard mcp login dbt
The dbt MCP server reads its connection settings — such as DBT_HOST, DBT_TOKEN, DBT_PROJECT_DIR, DBT_PATH, DBT_PROD_ENV_ID, and DBT_ACCOUNT_ID — from environment variables, typically a .env file in your dbt project root.
If dbt Wizard can't reach the server, confirm these values are set, then restart wizard so it picks up the changes.
For the full list of variables and an example .env file, refer to Set up self-hosted MCP and the Environment variables reference.
Deferral and state
When you work on part of a project, dbt Wizard uses deferral so it can reuse models that are already built elsewhere (for example, in production) instead of rebuilding everything. This saves time and warehouse cost.
How deferral is handled depends on the mode set up in wizard_config.toml for your project:
deferral.mode value | Behavior |
|---|---|
"wizard" | dbt Wizard handles deferral for you. You tell dbt Wizard which target from your profiles.yml to defer to (it tries to detect one automatically when you first set up the project). dbt Wizard then compiles that target and reuses its models for any upstream models you haven't built yourself. |
"fusion_cloud" | The dbt platform handles deferral against your connected environment, so dbt Wizard doesn't manage local state. |
"cloud_cli" | The dbt CLI handles credentials and deferral through the dbt platform, so dbt Wizard doesn't manage local state or inject deferral flags. |
"dbt_state" | dbt State or run cache handles deferral, so dbt Wizard skips its own production compile. |
"manual" | You maintain the deferral manifest path manually. |
"disabled" | Deferral is disabled for the project. |
For more about dbt State, refer to About dbt State.
The per-project favor_state setting defaults to true. With favor-state on, deferred relations take precedence. Set favor_state = false when you want dbt to use relations you have already built in development and fall back to the deferred environment for relations that aren't available there.
dbt Wizard stores the deferral mode for each project in wizard_config.toml under deferral.mode. For a complete setup and verification procedure, refer to Developing with production deferral.
Approval and sandboxing
By default, the CLI keeps you in control before it changes your project or runs commands.
In the terminal:
- dbt Wizard shows file changes as diffs so you can review them
- Commands that need permission under the active approval policy request confirmation before running
- The active sandbox profile limits where shell commands can read and write. dbt Wizard shows the active profile when the session starts.
Choose the sandbox profile and approval behavior that match the task:
# Restrict shell commands to read-only access.
wizard --sandbox read-only
# Never prompt for approval during this session.
# Useful for trusted tasks where you want Wizard to iterate without stopping.
wizard --ask-for-approval never
# Allow shell commands to write inside your workspace directory.
# Useful for commands that generate files.
wizard --sandbox workspace-write
Use relaxed settings when you want dbt Wizard to move faster on a scoped task you trust, such as a large refactor, generating documentation, or applying repetitive test updates. The tradeoff is that dbt Wizard has more freedom to act before you review each step, so use these settings in a clean working tree or feature branch.
Approval settings apply to the current session. They are not scoped per action type in the command line flags shown above; for example, --ask-for-approval never relaxes prompts broadly for that session. To set defaults that persist across sessions or apply only to a specific project, use the configuration file.
You can view more options by running:
wizard --help
Sessions
In the CLI, a session is a saved conversation and task history from a previous run on your machine. Sessions help you return to earlier work, continue a multi-step task, or review what the agent did in a past interaction.
Within a session, you can:
- Ask follow-up questions without restating the full context
- Continue work on an earlier investigation, refactor, or validation task
- Review prior prompts, responses, tool calls, and proposed changes
Resume a previous session with:
wizard resume # choose from a list of saved sessions
wizard resume --last # resume the most recent session
Each CLI session is saved locally. This is separate from platform conversations, which are stored in your dbt platform account.
Related docs
- dbt Wizard overview
- dbt Wizard in the dbt platform
- Use dbt Wizard locally
- dbt Wizard command reference
- How to use dbt Wizard in your dbt project for recommended workflows
Was this page helpful?
This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.
