dbt CLI for coding agents

When a coding agent has shell access to a dbt project, it can run the same dbt command-line interface that a developer uses to inspect and validate analytics code. dbt turns SQL models and configuration into a dependency graph, then uses that graph to select, test, or build data models. A dependency graph shows which models rely on other models.

A coding agent runs the same dbt commands as a developer. dbt Labs also offers its own AI agent, dbt Wizard, which is in beta. This guide covers the plain dbt commands. Choose which commands to allow: dbt parse and dbt ls inspect local project files, while dbt build runs SQL against a data warehouse, a database used for analytics, and can change its data. The dbt command reference documents these commands.

Set up the project

You can install two versions of dbt locally, dbt v2 and dbt v1. The installation guide installs dbt v2 by default:

python -m pip install dbt
dbt --version

dbt v2 has built-in connections for a set of warehouses, like Snowflake and BigQuery, so it needs no separate adapter. An adapter is a package that connects dbt to a particular warehouse. dbt v1 uses one adapter per warehouse. PostgreSQL is not on the dbt v2 list, and the Postgres setup page describes dbt v1 with its adapter:

python -m pip install dbt-postgres

Check which dbt version and adapter the project already uses, and install that one in the project’s Python environment.

The project also needs a profile: configuration that tells dbt which warehouse to connect to and how to authenticate. The profile commonly lives in ~/.dbt/profiles.yml; the project’s dbt_project.yml names the profile it uses. Follow the connection profile documentation and the setup page for the relevant warehouse. Keep credentials in environment variables or a protected local configuration, and tell the agent how to run the commands without putting secret values in its prompt.

dbt parse and dbt ls inspect local files without connecting to a warehouse. dbt debug checks the project and its configured connection by contacting the warehouse. Use it to verify connectivity, not for a local-only check.

Inspect a model without building it

An agent can parse the project and list a selected model before proposing code changes. In the example below, replace stg_orders with a model name that exists in the project:

dbt parse
dbt ls --select "stg_orders"

dbt parse reads the project and writes generated files under target/, including a manifest that describes the project’s resources and dependencies. It does not build models in the warehouse. dbt ls prints the resources that match the selector; here, the selector names one model. It reads the connection profile but does not connect to the database or run queries. The parse reference and the selection syntax cover the rest.

For a limited agent task, dbt parse checks the project configuration and code structure, while dbt ls shows which resources match the selector. The agent can use them to confirm that a model exists, inspect the project structure, and report its dependencies before editing. Neither command runs the model’s SQL in the warehouse to transform data or proves that the SQL returns correct data.

A realistic prompt would be:

Inspect the dbt model named stg_orders. Run dbt parse and dbt ls --select "stg_orders". Do not edit files or run commands that query or change warehouse data. Report whether parsing succeeded and what resources dbt selected.

The command output and success or failure status give the agent evidence to report. If a command fails, ask the agent to quote the actual error rather than report a successful result.

Separate local checks from warehouse changes

dbt parse and dbt ls are good first checks when the agent should work locally. Commands such as dbt test execute SQL against the warehouse, and dbt build can create or update warehouse objects as well as run tests. These commands connect to the warehouse, and what they do depends on the project configuration and the agent’s warehouse permissions. Ask the agent to run them only when the task explicitly includes checking or changing warehouse data.

Let the agent inspect and edit code, then review its proposed changes before allowing it to run commands that connect to or change the warehouse. A successful parse confirms only that dbt could read the project. It does not confirm database access, test results, or that the transformed data is correct.