dbt Wizard quickstart

Use dbt Wizard in your terminal or in the dbt platform.

By the end of this guide, you can install or invoke dbt Wizard in your terminal (depending on your dbt version), authenticate with your dbt platform credentials if applicable, and send your first prompt.

Be warned, the wizard has been known to

.

Supported AI providers

dbt Wizard

dbt Wizard supports different AI providers depending on where you use it.

Provider	dbt Wizard in dbt platform	dbt Wizard CLI
OpenAI	✓ (managed or BYOK)	✓ (OpenAI subscription or BYOK)
Anthropic	✓ (BYOK)	✓ (BYOK)
Azure AI Foundry / Azure OpenAI	✓ (BYOK)	✓ (BYOK)
AWS Bedrock	-	✓ (BYOK)
Snowflake Cortex	-	✓ (BYOK)

• Configure dbt platform integrations in account settings. BYOK is available for Enterprise and Enterprise+ plans.
• Configure BYOK for the CLI. For OpenAI subscription support in the CLI, run wizard providers configure openai_subscription and follow the prompts.

dbt platform Preview

Available in public preview.

dbt Wizard is in public preview as an AI agent layer across the managed dbt platform. Some customers may still have access to dbt Copilot until the updated AI agent layer is generally available. Contact dbt Support with any questions.

dbt platform prerequisites

You'll need:

• A dbt platform account on a Starter, Enterprise, or Enterprise+ plan
• An account admin to enable dbt Wizard for your account
• Access to Studio IDE (public preview) or the dbt Wizard home tab (beta)
• (Optional) If you're using dbt Wizard in the home tab, enable experimental features for your account

Get started in the dbt platform

1. From the dbt platform sidebar menu, open Studio IDE or the dbt Wizard home app.

2. In the Studio IDE, open a project and try a prompt:

   Understand your project:

   summarize what this project does

   Find coverage gaps:

   which models in this project have no tests?

   Enhance coverage:

   add not_null and unique tests to the primary key of stg_customers

   Ship changes:

   commit the changes to the branch and create a pull request

dbt Wizard will read your project's lineage, tests, and metadata and propose changes as a diff. You approve, reject, or redirect before anything is written.

dbt platform next steps

• dbt Wizard in Studio IDE — in-depth guide including agent mode, resource generation, inline SQL, and interactive prompts
• Use cases and examples — realistic analytics engineering scenarios
• Skills — give Wizard reusable instructions for your project

Terminal Beta

Available in public beta.

Terminal prerequisites

You'll need:

• An OpenAI subscription, or your own API key or cloud credentials for a supported provider using BYOK: OpenAI, Anthropic, AWS Bedrock, Azure, or Snowflake Cortex (preview)
• A dbt project set up locally

New to the terminal?

If you've never used the terminal before, check out the terminal guide. Some tips include:

• Enter / to see the available commands or try out /overview to get a quick summary of your project.
• Press Shift+Tab to cycle through collaboration modes.

Get started in your terminal

Install dbt Wizard as wizard on your PATH using the curl script for your operating system:

macOS/Linux

curl -fsSL https://public.cdn.getdbt.com/dbt-wizard/install/install-wizard.sh | sh

Windows

Run the following in PowerShell:

irm https://public.cdn.getdbt.com/dbt-wizard/install/install-wizard.ps1 | iex

Then verify the install and start a session:

wizard --version   # confirm the install
wizard             # start an interactive session

After running wizard --version, you should see something like dbt-wizard VERSION. Run wizard --help to see all available commands and flags. dbt Wizard installs default config files — refer to the config reference for more details.

Complete first-run onboarding

The first time you start dbt Wizard in a project, it walks you through a short setup and saves your answers to wizard_config.toml, providers.json, and provider-auth.json, so you only do this once per project. You'll be asked to:

• Review and accept the Terms of Use.
• If you have a dbt platform account, sign in through the browser authentication link when prompted and follow the steps in the browser.
• Trust the directory so dbt Wizard can read your project.
• Confirm the path to your dbt executable or virtual environment — point it at /path/to/bin/dbt or a .venv root (dbt Wizard uses bin/dbt automatically).
• Add any extra compile flags to append to the startup dbt compile -s state:modified+, or leave empty to skip.
• Configure deferral — choose Wizard (dbt Wizard manages it), Manual, or Disabled. If you choose Wizard, enter the profiles.yml target to defer to (defaults to prod). On the dbt Fusion engine connected to the dbt platform, dbt Wizard instead offers to let the platform handle deferral.
• Confirm your detected dbt profile and target, or customize the profile, target, or profiles.yml path.
• Configure a provider (OpenAI subscription, OpenAI API key, Anthropic, Amazon Bedrock, Azure, or Snowflake). If you use an OpenAI subscription, dbt Wizard configures it with wizard providers configure openai_subscription. For other providers, paste your API key or cloud credentials, then choose a model. Refer to Configure BYOK.

To re-run any of these steps later, refer to Re-trigger onboarding flows.

Set your API key without the prompt

During onboarding, dbt Wizard prompts you to configure a provider interactively. To skip the API key prompt — for headless runs like wizard exec or to reuse your key across sessions — set it as an environment variable before starting wizard instead:

export OPENAI_API_KEY="sk-..."      # or ANTHROPIC_API_KEY, etc.

For AWS Bedrock and Snowflake Cortex, refer to Configure BYOK.

After onboarding, dbt Wizard shows a welcome screen with two sections:

• STATUS — the dbt Wizard version, the active AI model (change it with /model), and your project directory.
• OVERVIEW — a snapshot of your project from the metadata engine: build status and a count of passing (✓), warning (⚠), and failing (✗) checks.

Enter / to see the available slash commands, or try /overview for a summary of your project. CLI commands use the wizard prefix, so you can also run subcommands such as wizard exec, wizard review, and wizard resume.

Once you're set up, ask your first question in your terminal. Try some prompts to see how dbt Wizard works:

Understand your project:

summarize what this project does

Find coverage gaps:

which models in this project have no tests?

Enhance coverage:

add not_null and unique tests to the primary key of stg_customers

Ship changes:

commit the changes to the branch and create a pull request

dbt Wizard will read your project's lineage, tests, and metadata and propose changes as a diff. You approve, reject, or redirect before anything is written.

For refactor or change requests, dbt Wizard automatically assesses downstream impact first by reporting affected models, metrics, and tests with a severity rating before proposing any changes.

When dbt Wizard manages deferral, you point it at a target in your profiles.yml and it compiles and defers to that target automatically, so it can validate against already-built upstream models without rebuilding everything. Refer to Deferral and state and About dbt State for details.

Useful terminal commands

Use the following commands to get started:

Command	Description	Example
wizard "[prompt]"	Start an interactive session seeded with a prompt. Once you activate the session, you don't need to pass your prompt in quotes.	wizard "summarize what this project does"
wizard exec "[prompt]"	Run a single prompt non-interactively and exit	wizard exec "list all models with no tests"
wizard review --uncommitted	Non-interactive code review of uncommitted changes	wizard review --uncommitted
wizard review --base BRANCH	Review diff against a base branch	wizard review --base main
wizard resume	Resume a previous session	wizard resume --last
wizard apply	Apply the latest Wizard diff to your working directory	wizard apply TASK_ID
wizard login / logout	Authenticate with your dbt platform account	wizard login
wizard mcp	Manage MCP server connections	wizard mcp add dbt
wizard update	Update Wizard to the latest version	wizard update

Need to re-run setup?

If you want to re-run onboarding — re-authenticate, reset project config, or retrigger the trusted folder prompt — refer to Re-trigger onboarding flows.

Terminal next steps

• Use cases and examples for realistic analytics engineering scenarios
• Install and update reference for full install, update, and uninstall details
• Configure BYOK for managing your API key and choosing an AI model
• Configuration reference for setting persistent defaults in config.toml and per-project dbt settings in wizard_config.toml
• Skills for giving Wizard reusable instructions for your project
• Migrate from Claude Code for bringing existing Claude Code project context into dbt Wizard

dbt platform and terminal

dbt Wizard is in public preview as an AI agent layer across the managed dbt platform. Some customers may still have access to dbt Copilot until the updated AI agent layer is generally available. Contact dbt Support with any questions.

Use dbt Wizard in both environments

dbt Wizard supports both local and remote development. Use this path if you work in the dbt platform and also develop locally in a dbt project.

To get started:

1. Follow the dbt platform tab to confirm dbt Wizard is enabled and available in your account.
2. Follow the Terminal tab to install the dbt Wizard CLI and start a local session.
3. Try a prompt in either environment, depending on where you want to work. Some example prompts are:

   Understand your project:

   summarize what this project does

   Find coverage gaps:

   which models in this project have no tests?

   Enhance coverage:

   add not_null and unique tests to the primary key of stg_customers

   Ship changes:

   commit the changes to the branch and create a pull request

For example, you might use dbt Wizard in the dbt platform when you want a managed, chat-first or Studio-based workflow, and use the dbt Wizard CLI when you want to stay in your local terminal.

Next steps for both environments

• Get started in the dbt platform
• Get started in your terminal
• Configure BYOK
• CLI reference
• Use cases and examples

Share your feedback!

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!

Was this page helpful?

Privacy policyCreate a GitHub issue

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.