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 VSIX

Every release is mirrored to a public GCS bucket:

curl -L -o dataface-latest.vsix \
  https://storage.googleapis.com/dataface-downloads/dataface-latest.vsix

code --install-extension dataface-latest.vsix
# or
cursor --install-extension dataface-latest.vsix

For a version-pinned install (immutable URL — safe to bookmark):

curl -L -o dbtcharts-<version>.vsix \
  https://storage.googleapis.com/dataface-downloads/dbtcharts-<version>.vsix

In VS Code / Cursor you can also use Extensions panel → … menu → Install from VSIX….

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.85.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

The dbt-charts CLI is not installed or not 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.