Ecosystem at a glance

dbt-tools turns dbt artifacts under a target directory into structured, repeatable analysis. Four surfaces share the same artifact contract:

Surface	Role
CLI (dbt-tools)	One-shot shell commands—CI, scripts, operators
MCP (dbt-tools-mcp)	Long-lived server; many tool calls on one parsed run
Web (dbt-tools-web)	Browser investigation UI; startup flags align with MCP (--dbt-target, remote client flags)
Agents (plugins)	Primitive skills that invoke CLI or MCP (Cursor, Codex, Claude Code)

Remote artifact roots (s3://, gs://, including GCS service-account impersonation): Local and remote artifacts · S3 · GCS.

Quick examples

From the repository root, with manifest.json and run_results.json under ./target:

dbt-tools status --dbt-target ./target --json
dbt-tools discover --dbt-target ./target "orders" --limit 5 --json
dbt-tools explain model.my_project.my_model --dbt-target ./target --json

Replace model.my_project.my_model with a unique_id from discover output.

Coding agents: use stable handles such as dbt-tools-cli:check-session and dbt-tools-cli:find-resources—see Skill catalog and Install agent skills.

Where recipes and job workflows live

Recipes (goal-first): recipes/ — start with what you want to accomplish.

Workflows (interface-first, existing pages): grouped in the sidebar under each surface (URLs stay under workflows/):

Job	Doc
CI / health	Check run health (sidebar: Interfaces → CLI → Workflows)
Find / explain	Find a model, Explain a failure
Slow runs / browser	Investigate slow runs, Open in web (sidebar: Web → Workflows)
Coding agent	Wire your coding agent (sidebar: Agents → Workflows)

Full workflow index: Workflows.

Next

• 5-minute quickstart — run your first command
• Choose by goal — route to the right interface for your job
• Choose your interface — CLI, MCP, Web, or agent skills
• Foundations: New to dbt? · dbt artifacts & target/ — artifact literacy for dbt-tools
• Trust & Safety — data boundaries, agent safety, and licensing