dbt Charts for VS Code

The official VS Code extension for dbt Charts - a dbt-native dashboard and visualization layer.

Features

Syntax Highlighting

Full syntax highlighting for dbt Charts YAML files with embedded SQL and Jinja template support.

• YAML structure highlighting
• SQL syntax highlighting in sql: blocks
• Jinja template highlighting ({{ }}, {% %})
• Special highlighting for dbt Charts keywords (chart types, input types, etc.)

IntelliSense & Autocomplete

Value completion for the fields whose options are a fixed set works out of the box — no Python, no other extensions:

• Chart types (line, bar, area, scatter, kpi, table, etc.)
• Variable input types (select, multiselect, date, slider, etc.)
• Theme names

Completion for top-level keys, query references, and chart references comes from the optional language server.

Live Preview

Split-pane live preview of your dashboard, similar to Markdown preview:

• Cmd/Ctrl+Shift+V - Open preview to the side
• Re-renders as you type, and again on save
• Interactive variable controls — change a filter and the preview re-renders
• Click-to-navigate from preview to source
• Requires the dbt-charts CLI: the preview shells out to dct render, so it shows real data from your project's sources

Validation & Diagnostics

Run dbt Charts: Validate Dashboard at any time for a full dct validate pass. With the optional language server enabled, the same errors surface as you type:

• YAML syntax errors
• Invalid chart and input types
• Undefined query references
• Missing required fields

Code Snippets

Quick templates for common patterns:

Type the prefix and press Tab to expand.

AI Integration

dbt Charts: Setup AI Integration (MCP) wires the dbt-charts MCP server into the current workspace, giving your assistant tools to inspect your schema, run queries, and render dashboards. Writes .cursor/mcp.json in Cursor or .vscode/mcp.json in VS Code.

Language Server

A Python language server ships inside the extension and adds the features that need the real compiler. It is on by default, and starts the first time you open a board file — a workspace with no board YAML never launches it, so the interpreter discovery that makes macOS ask for filesystem access only happens once you are actually editing a dashboard. It needs a Python interpreter with the dbt-charts package installed; if it can't start, a dbt Charts: no diagnostics status-bar indicator appears and opens the log on click, while syntax highlighting keeps working. Turn it off with "dbt-charts.languageServer.enabled": false.

It provides:

• Diagnostics as you type
• Completion for top-level keys, query references, and chart references
• Hover documentation for chart types, input types, and Jinja functions
• Ctrl/Cmd+Click a query or chart reference → jump to its definition
• Document outline for the variables, queries, and charts sections

Installation

With the dbt-charts CLI

dct init code      # VS Code
dct init cursor    # Cursor

From the marketplace

The extension is published as dbtLabsInc.dbtcharts on the VS Code Marketplace and as dbtLabsInc/dbtcharts on Open VSX (the registry Cursor and other VS Code forks resolve extensions from). Search "dbt Charts" in your editor's Extensions panel, or:

code --install-extension dbtLabsInc.dbtcharts
# or
cursor --install-extension dbtLabsInc.dbtcharts

To pin a specific version instead of tracking the registry, VS Code accepts a version suffix on the extension ID:

code --install-extension dbtLabsInc.dbtcharts@<version>

Cursor installs the latest published version from Open VSX and does not document a CLI version-pin flag.

Configuration

Configure the extension in VS Code settings:

{
  // Path to the dbt-charts CLI (default: "dct")
  "dbt-charts.cli.path": "dct",

  // Enable auto-refresh preview on change
  "dbt-charts.preview.autoRefresh": true,

  // Delay before refreshing preview (ms)
  "dbt-charts.preview.refreshDelay": 500,

  // Language server: on by default, started on the first board file you open
  // (a board-free workspace never spawns Python, so no macOS TCC prompt)
  "dbt-charts.languageServer.enabled": true,

  // Python path for language server
  "dbt-charts.languageServer.pythonPath": "python"
}

File Associations

The extension treats these as dbt Charts files:

• dbt_charts.yml
• dbt_charts.yaml
• Any *.board.yml file
• Any *.yml, *.yaml, or *.md file under a charts/ directory ("charts" as an exact path segment — matches the dbt-charts CLI's directory convention).
• Any other .yml / .yaml file whose content has a queries: or charts: block plus a rows:, cols:, grid:, or tabs: layout — a fallback that applies once the extension is active in the workspace.

Keyboard Shortcuts

Commands

Access via Command Palette (Cmd/Ctrl+Shift+P):

• dbt Charts: Open Preview - Open dashboard preview
• dbt Charts: Open Preview to the Side - Open preview in split view
• dbt Charts: Refresh Preview - Refresh the preview panel
• dbt Charts: Export as HTML - Export dashboard to HTML
• dbt Charts: Export as PNG - Export dashboard to PNG
• dbt Charts: Validate Dashboard - Run full validation
• dbt Charts: Setup AI Integration (MCP) - Configure the dbt-charts MCP server for this workspace

Requirements

• VS Code 1.91.0 or higher (or an equivalent fork, such as Cursor)
• dbt-charts CLI for preview, export, validation, and MCP setup (uv tool install "dbt-charts" or pip install "dbt-charts")
• For the optional language server: Python 3.10+ with dbt-charts installed (the language server's own protocol dependencies ship inside the extension)

Highlighting, snippets, and value completion work without any of the above.

Troubleshooting

Preview fails to render

If the preview shows a parse error, the error panel describes what's actually wrong with your board's YAML or query — fix that and save. A "CLI Not Found", "Runtime Not Found", or "dbt-charts Not Installed" page specifically means the CLI isn't installed or isn't on PATH. Install with one of:

uv tool install "dbt-charts"
# or
pip install "dbt-charts"

The extension detects which command fits your machine and offers an Install dbt Charts action from the missing-runtime notification that opens a terminal with the right one pre-filled.

If dbt-charts lives in a project virtualenv, point dbt-charts.cli.path at that environment's dct (for example .venv/bin/dct).

Language server not starting

The interpreter in dbt-charts.languageServer.pythonPath needs dbt-charts installed (uv tool installs are isolated CLI environments, not project virtualenvs, so use pip here even if you installed the CLI with uv):

pip install "dbt-charts"

Syntax highlighting not working

Check the file against File Associations above — move it under a charts/ directory inside a project (a folder with a dbt_charts.yml or dbt_project.yml ancestor), rename it to dbt_charts.yml or *.board.yml, or set the language mode manually from the status bar.

Documentation

Full extension documentation and settings reference: https://docs.dbtcharts.com/editor-extension/

License

Apache License 2.0. See the LICENSE file shipped alongside this extension. Copyright (c) 2026 Fivetran, Inc.