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
Want to see dbt Wizard in action? Check out the demo video.
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. |
global.dbt_compile_on_startup | Whether to compile the development project at startup. Defaults to true. |
global.prod_parse_on_startup | Whether to parse the production environment and refresh deferral state at startup. Defaults to true. |
global.prod_parse_args | Arguments for the production parse. Defaults to ["parse", "--target", "prod"]. |
global.prod_state_ttl_hours | Number of hours a production state snapshot remains fresh. Defaults to 24. |
global.prod_state_dir | Directory for production state snapshots. Defaults to target/prod-state in the project. |
global.compile_extra_args | Extra arguments to append when dbt Wizard compiles any project without a project-specific override. |
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. |
compile_extra_args | Extra arguments to append when dbt Wizard compiles this project. |
prod_parse_args | Project-specific arguments for the production parse command. |
deferral.mode | Who handles deferral for this project. 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, "prod"). |
deferral.state | Path to a state directory when deferral.mode is "manual". |
deferral.favor_state | Whether deferred relations take precedence. Defaults to true. |
profile_override.path | Path to an alternative profiles.yml file for this project. |
profile_override.profile | Profile name to use from the selected profiles file. |
profile_override.target | Target to use from the selected profile. |
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"
dbt_compile_on_startup = true
prod_parse_on_startup = true
prod_state_ttl_hours = 24
[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 = "prod"
favor_state = true
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 six 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. |
"cloud_cli" | The dbt CLI manages credentials and deferral through the dbt platform, so dbt Wizard skips its production compile and deferral flag injection. |
"dbt_state" | dbt State or run cache handles deferral, so dbt Wizard skips its own production compile. |
"manual" | You provide the deferral manifest directory with state. |
"disabled" | Deferral is disabled for the project. |
For more about dbt State, refer to About dbt State.
Set state to a directory containing a compatible manifest.json when mode = "manual":
[projects."/Users/you/jaffle-shop".deferral]
mode = "manual"
state = "/Users/you/dbt-state/production"
favor_state = true
About favor-state: favor_state is configurable and defaults to true. When it is true, dbt Wizard passes --favor-state so deferred relations take precedence. Set it to false to use a relation that already exists in development and fall back to deferred state when it doesn't.
You can also configure production snapshot and compile behavior with global prod_parse_on_startup, prod_parse_args, prod_state_ttl_hours, prod_state_dir, and compile_extra_args settings. Per-project compile_extra_args and prod_parse_args values let you override the global behavior for one project. Use a profile_override block to select a different profiles file, profile, or target for compilation.
For configuration examples and a verification workflow, refer to Developing with production deferral.
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.
