dbt Wizard config reference Beta
dbt Wizard stores configuration in two TOML files under ~/.dbt/wizard/, each controlling a different part of the product.
The two config files
We'd love to hear how dbt Wizard is working for you. Share your feedback by either running the /feedback slash command in your interactive terminal session or by going to the #dbt-wizard channel in the dbt Community Slack.
Thanks so much for your help in improving dbt Wizard and dbt data development!
TOML (Tom's Obvious, Minimal Language) is a config file format. If you've written YAML or JSON before, it'll feel familiar — keys and values are separated by = (with spaces before and after the equals sign), and nested sections use [section.name] headers instead of indentation or curly braces. For example:
model = "claude-sonnet-4-6"
[projects."/Users/you/jaffle-shop"]
trust_level = "trusted"
This config sets the default AI model for all new sessions and applies to all future invocations across all projects. You can override the default AI model for a specific project by setting the model key in the wizard_config.toml file for that project or using the /model picker in the text-based user interface (TUI).
| File | Controls | When to use |
|---|---|---|
~/.dbt/wizard/config.toml | Agent runtime — AI model, MCP servers, approval rules, trusted projects | Change agent-level behavior across all sessions |
~/.dbt/wizard/wizard_config.toml | Per-project settings — dbt executable path, deferral, saved model preference | Change how dbt Wizard works with a specific dbt project |
Note that dbt_project.yml is separate from both and controls how dbt builds your project.
Common tasks
| Goal | Edit | Restart needed? |
|---|---|---|
| Change the default AI model | config.toml → model = "claude-sonnet-4-6" | Yes |
| Point dbt Wizard at a specific dbt binary | wizard_config.toml → path | Yes |
| Add the dbt MCP server | config.toml → [mcp_servers.dbt] | Yes |
| Mark a repo as trusted | config.toml → trust_level = "trusted" under [projects."..."] | Yes |
| Change approval or sandbox defaults | config.toml | Yes |
Config precedence
Settings resolve in this order (highest to lowest):
- CLI flags (
-m,-c) at invocation - In-session model picker (
/model) ~/.dbt/wizard/config.toml~/.dbt/wizard/wizard_config.toml- Built-in defaults
config.toml
Global agent settings for models, approvals, sandboxing, web search, and MCP servers.
~/.dbt/wizard/config.toml controls how the agent session behaves. It's created automatically when dbt Wizard is installed.
Configuration keys
This is the list of configuration keys that can be set in config.toml.
modelapproval_policysandbox_modeweb_search
You can view more by running wizard config --help.
AI model and API
| Key | Type | Default | Description |
|---|---|---|---|
model | string | — | Default AI model for new sessions. Refer to AI model ID format below. Change interactively with /model in the TUI. |
Behavior
| Key | Type | Default | Description |
|---|---|---|---|
approval_policy | string | on-request | When Wizard asks before executing commands. Options: untrusted (ask for non-trusted commands), on-request (dbt Wizard decides), never (run without asking). |
sandbox_mode | string | read-only | Shell sandbox policy. Options: read-only (default), workspace-write (allow writes inside project dir), danger-full-access (no restrictions). |
web_search | string | cached | Web search mode. Options: disabled, cached, or live. |
Project trust
Set trust_level per-project to allow dbt Wizard to use project-local config:
[projects."/absolute/path/to/your-repo"]
trust_level = "trusted"
MCP servers
[mcp_servers.dbt]
command = "DBT_MCP_ENDPOINT"
AI model ID format
AI model IDs in config.toml use the public model ID, such as claude-sonnet-4-6.
To list all available AI model IDs:
wizard debug models
Environment variables
Any key can be set as an environment variable using the DBT_WIZARD_ prefix in SCREAMING_SNAKE_CASE:
export DBT_WIZARD_MODEL=claude-sonnet-4-6
export DBT_WIZARD_APPROVAL_POLICY=never
export OPENAI_API_KEY=sk-... # OpenAI (no prefix needed)
export ANTHROPIC_API_KEY=sk-ant-... # Anthropic (no prefix needed)
OPENAI_API_KEY and ANTHROPIC_API_KEY are read directly without the DBT_WIZARD_ prefix, following each provider's convention.
When it's read
config.toml is read at session start when you run wizard. Changes take effect only after you exit and restart the CLI. Per-invocation -c flags and the in-session /model picker override this file for that session only.
Example
model = "claude-sonnet-4-6"
[projects."/Users/you/jaffle-shop"]
trust_level = "trusted"
[mcp_servers.dbt]
command = "DBT_MCP_ENDPOINT"
wizard_config.toml
Per-project settings Wizard writes during onboarding, including dbt path and deferral settings.
~/.dbt/wizard/wizard_config.toml stores what dbt Wizard knows about each of your dbt projects. dbt Wizard writes to this file automatically during onboarding and when you change project settings. You can also edit it manually.
Configuration keys
| Key | Description |
|---|---|
version | Schema version for this file (currently 1). Don't change this manually. |
global.terms_of_use_accepted_at | Timestamp of when you accepted the dbt Wizard Terms of Use. Written once under the [global] section and applies across all projects. |
onboarded_at | Timestamp of when you onboarded this project in dbt Wizard. |
path | Path to the dbt binary dbt Wizard should use for this project. |
deferral.mode | Who handles deferral for this project. "wizard" means dbt Wizard handles it — you tell it which profiles.yml target to defer to, and it reuses that target's models instead of rebuilding everything. "fusion_cloud" means the dbt platform handles deferral against your connected environment. Refer to Deferral below. |
deferral.target | The target from your profiles.yml that dbt Wizard compiles and defers to when deferral.mode is "wizard" (for example, "dev"). |
Settings are stored per-project under [projects."/absolute/path/to/repo"] blocks:
version = 1
[global]
terms_of_use_accepted_at = "2026-05-28T15:06:54Z"
[projects."/Users/you/jaffle-shop"]
onboarded_at = "2026-05-20T11:09:01.410346"
path = "/Users/you/jaffle-shop/.venv/bin/dbt"
[projects."/Users/you/jaffle-shop".deferral]
mode = "wizard"
target = "dev"
Deferral
Deferral lets dbt Wizard reuse models that are already built elsewhere (for example, in production) instead of rebuilding everything when you're only working on part of a project, saving you time and warehouse cost.
The deferral.mode setting in wizard_config.toml controls who handles deferral. It accepts five values, and dbt Wizard usually sets it for you during onboarding:
deferral.mode value | What it means |
|---|---|
"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 any local state. Set automatically when you're connected to the platform. |
"dbt-state" | dbt state 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.
About favor-state: favor-state is a built-in dbt deferral option, not something you need to configure here — dbt Wizard handles it for you during deferral compiles. You don't need to add favor_state to wizard_config.toml. What matters instead is that dbt Wizard uses a valid deferral mode and state path.
In practice, when dbt Wizard handles deferral it uses your own dev version of a model when you've already built one, and only falls back to the version from the deferred target for models you haven't built yet.
For how this behaves during a session, refer to Deferral and state.
Troubleshooting
Here are some common config mistakes and how to fix them:
| Symptom | Likely cause | Fix |
|---|---|---|
Still on old AI model after editing wizard_config.toml | wizard_config.toml doesn't store the model | Set model in config.toml and restart wizard |
AI model unchanged after editing config.toml | Old session still running | Press Ctrl+C, then run wizard again |
| "Invalid model" error | Wrong AI model ID | Run wizard debug models to see valid AI model IDs |
Re-trigger onboarding flows
If you need to re-run part of the setup — for example, after deleting config entries by mistake or switching to a new project — you can reset individual flows by deleting the relevant file. dbt Wizard will re-prompt you the next time it runs.
To delete a file, run the command in your terminal (macOS/Linux). For example:
rm ~/.dbt/wizard/auth.json
If you get a No such file or directory error, the file doesn't exist — which means that part of the setup hasn't run yet, or has already been reset. You can ignore the error.
| What you want to redo | File to delete |
|---|---|
| Re-run the trusted folder prompt | Remove your project's entry from ~/.dbt/wizard/config.toml under [projects."..."] |
| Re-authenticate with dbt platform | ~/.dbt/wizard/auth.json |
| Re-run dbt project setup | Remove your project's entry from ~/.dbt/wizard/wizard_config.toml under [projects."..."], or delete the file entirely to reset all projects |
| Re-trigger BYOK key configuration | ~/.dbt/wizard/provider* (this matches all provider files) |
config.toml and wizard_config.toml are separate files that control different things. If you want to re-run project setup, edit wizard_config.toml — not config.toml. Editing the wrong file won't re-run the onboarding flow you expect. Refer to The two config files at the top of this page for the difference.
Related docs
Links to BYOK setup, approval behavior, and CLI command reference.
Was this page helpful?
This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.
