Get started with the dbt Wizard local CLI
Install dbt Wizard locally and start an agentic dbt development session from your terminal.
Install dbt Wizard as wizard on your PATH using the curl script for your operating system:
- macOS/Linux
- Windows
curl -fsSL https://public.cdn.getdbt.com/dbt-wizard/install/install-wizard.sh | sh
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.
By the end of this guide, you can install dbt Wizard locally, authenticate with your dbt platform credentials if applicable, complete first-run onboarding, and send your first prompt from the terminal.
dbt Wizard is data warehouse agnostic and works with both the dbt Fusion engine and dbt Core — no specific engine is required.
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) |
| Google Gemini | - | ✓ (BYOK) |
| Snowflake Cortex | - | ✓ (BYOK) |
† Anthropic enterprise and subscription licenses (such as Claude Enterprise) aren't supported per Anthropic's terms of service. BYOK requires an Anthropic API key.
- Configure dbt platform integrations in account settings.
- Configure BYOK for the CLI by running
wizard providers configure PROVIDER_NAMEand follow the prompts.
Prerequisites
You'll need:
- An OpenAI subscription, or your own API key or provider credentials for a supported provider using BYOK: OpenAI, Anthropic, AWS Bedrock, Azure, or Snowflake Cortex (preview)
- A dbt project set up locally
Note that the dbt Wizard CLI doesn't yet work with the dbt platform CLI (formerly the dbt Cloud CLI), support coming soon. In the meantime, run the dbt Wizard CLI in a project that uses Fusion or dbt Core.
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/overviewto get a quick summary of your project. - Press
Shift+Tabto cycle through collaboration modes.
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/dbtor a.venvroot (dbt Wizard usesbin/dbtautomatically). - 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.ymltarget to defer to (defaults toprod). 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.ymlpath. - Configure a provider (OpenAI subscription, OpenAI API key, Anthropic, Amazon Bedrock, Azure, Gemini, or Snowflake). Refer to Configure BYOK.
To re-run any of these steps later, refer to Re-trigger onboarding flows.
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
export AWS_BEARER_TOKEN_BEDROCK="ABSK..." # for Amazon Bedrock
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 |
If you want to re-run onboarding — re-authenticate, reset project config, or retrigger the trusted folder prompt — refer to Re-trigger onboarding flows.
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.tomland per-project dbt settings inwizard_config.toml - Use skills locally for giving Wizard reusable instructions for your project
- Use MCP servers to connect dbt Wizard CLI to more tools and context
- Migrate from Claude Code for bringing existing Claude Code project context into dbt Wizard
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?
This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.