Skip to content

VS Code & Cursor Extension

The dbt charts extension turns any editor built on VS Code — VS Code itself, Cursor, and other forks — into a dashboard authoring environment: syntax highlighting for board YAML (including the SQL and Jinja inside it), snippets for every chart and layout type, and a live split-pane preview of the rendered dashboard next to the file you are editing.

Install

If you already have dbt charts installed, one command downloads and installs the extension into your editor:

dct init code      # VS Code
dct init cursor    # Cursor

The interactive dct init wizard also offers this step for whichever editors it finds on your PATH. See dct init for the full command.

Manual download

The extension is distributed as a .vsix file rather than through the VS Code Marketplace. Every release is mirrored to a public download bucket — no authentication required:

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

You can also install the downloaded file from the editor UI: Extensions panel → … menu → Install from VSIX….

To pin a specific version, swap latest for the version number — those URLs are immutable and safe to bake into a setup script:

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

Requirements

  • VS Code 1.85 or later (or a fork of an equivalent version, such as Cursor)
  • The dct CLI for preview, export, and validation — highlighting, snippets, and completion work without it

Which files it recognizes

The extension switches a file into dbt charts mode — highlighting, snippets, and completion — when any of these hold:

Rule Examples
Filename ends in .dataface.yml / .dataface.yaml sales.dataface.yml
File is named dbt_charts.yml your project config
Any .yml, .yaml, or .md file under a charts/ directory inside a project (a folder with a dbt_charts.yml or dbt_project.yml ancestor) charts/sales.yml, charts/partials/_header.yml
Any other .yml / .yaml file whose content has a queries: or charts: block and a rows:, cols:, grid:, or tabs: layout a dashboard file kept outside charts/

The charts/ rule matches on an exact path segment inside a recognized project root, so a directory named my_charts_backup/ — or a charts/ folder in a repo with no project marker — is left alone. The content rule is a fallback for files kept outside charts/ — it applies once the extension is active in the workspace, which any of the first three rules (or opening the preview) takes care of.

Live preview

Press Cmd+Shift+V (macOS) or Ctrl+Shift+V (Windows/Linux) to open the rendered dashboard beside your file, or run dbt charts: Open Preview to the Side from the Command Palette. The preview:

  • Re-renders as you type, debounced — and again on every save
  • Renders real data. It shells out to dct render in your project, so queries hit the same sources your dashboards use in production
  • Has working variable controls. Change a select, date range, or slider in the preview and the dashboard re-renders with that value applied
  • Navigates back to source. Click a chart in the preview to jump to its definition in the YAML

Preview requires the dct CLI. The extension looks for it in a venv/, .venv/, or env/ beside your workspace before falling back to PATH; point dbt_charts.cli.path at it directly if it lives elsewhere. When a render fails, the preview pane shows the same structured error you would get from dct validate, so you can fix the YAML without leaving the editor.

Syntax highlighting

Board YAML is highlighted as a language in its own right, not as generic YAML:

  • YAML structure, with dbt charts's own keywords — chart types, input types, and top-level keys — called out distinctly
  • SQL inside sql: blocks, highlighted as SQL
  • Jinja templating ({{ ... }}, {% ... %}) inside those SQL blocks

The highlighting rules are generated from the same schema the engine compiles against, so new chart types and keys light up as soon as you upgrade.

Completion

Value completion for the fields whose options are a fixed set — theme:, chart type:, and variable input: — works out of the box, with no Python and no other extensions installed. The values come from the schema shipped inside the extension, so you get the real list rather than whatever words happen to be elsewhere in the buffer.

Completion for keys, query references, and chart references is part of the optional language server.

Snippets

Type a prefix and press Tab to expand a working scaffold.

Prefix Expands to
dft:board Complete dashboard skeleton
dft:query SQL query definition
dft:query-filter Query with a Jinja filter() call
dft:query-dbt Query using dbt ref()
dft:chart Generic chart definition
dft:kpi KPI / metric card
dft:table Data table
dft:map Geographic map
dft:var-select Select dropdown variable
dft:var-select-query Select variable with options from a query
dft:var-daterange Date range picker variable
dft:var-slider Number slider variable
dft:rows Vertical row layout
dft:cols Horizontal column layout
dft:grid Grid layout
dft:tabs Tabbed layout
dft:source-duckdb DuckDB source block
dft:source-postgres PostgreSQL source block
jinja:filter Jinja filter() call for a WHERE clause
jinja:ref dbt ref() call
jinja:if Jinja if block

Most prefixes have plain-language aliases too — dashboard, query, kpi, grid, and so on — so the snippet surfaces even if you don't remember the dft: prefix.

Export and validation

Run these from the Command Palette (Cmd/Ctrl+Shift+P) with a board file open:

  • dbt charts: Export as HTML — render to a standalone HTML file
  • dbt charts: Export as PNG — render to an image
  • dbt charts: Validate Dashboard — run a full dct validate pass and report the result

All three call the dct CLI, so the output is identical to running dct render yourself.

AI integration

The extension pairs with the dbt charts MCP server, which gives Cursor's and VS Code's AI assistants tools to inspect your schema, run queries, and render dashboards. Run dbt charts: Setup AI Integration (MCP) from the Command Palette and it wires up the workspace for the editor you're in, writing .cursor/mcp.json in Cursor or .vscode/mcp.json in VS Code. In Cursor, the extension offers this once per workspace when no dbt charts entry is configured yet.

The equivalent from a terminal:

dct init mcp           # auto-detect installed AI clients
dct init mcp cursor    # or target one
dct init mcp vscode

See dct mcp for the server and the tools it exposes.

Optional language server

A Python language server ships inside the extension and adds deeper editing features, checked against the real compiler rather than a static schema:

  • Diagnostics as you type — every error and warning the compiler produces (invalid chart and input types, undefined query references, missing required fields), each with a clickable code that opens its documentation page. Warnings about redundant authored elements (unused charts, redundant labels) appear faded via VS Code's Unnecessary tag rather than as a squiggle.
  • Diagnostics on preview render — the 15 render-time warnings (narrow bar bands, dominant pie segments, zero-row queries, and others that require query results to evaluate) appear in a dedicated dataface-render group in the Problems panel each time you trigger a preview. They are cleared automatically when you edit the file, so stale warnings never overlap with live compiler output.
  • Completion for top-level keys, query references, and chart references
  • Hover documentation for chart types, input types, and Jinja functions
  • Go to Definition — Ctrl/Cmd+Click a query or chart reference to jump to where it's defined
  • Document outline for the variables, queries, and charts sections

It is on by default and starts the first time you open a board file, so a workspace with no board YAML never launches it — the interpreter discovery that makes some systems prompt for filesystem access waits until you are actually editing a dashboard.

It needs a Python interpreter with dbt charts installed. If the server can't start, a dbt charts: no diagnostics indicator appears in the status bar — click it for the reason. Syntax highlighting keeps working either way. Point it at a specific interpreter with:

{
  "dbt_charts.languageServer.pythonPath": "/path/to/your/venv/bin/python"
}

To turn it off entirely:

{
  "dbt_charts.languageServer.enabled": false
}

The interpreter you point at needs dbt charts with the lsp extra installed — that extra is the only source of the pygls version bound the language server requires:

pip install "dbt-charts[lsp]"

Everything else in this page works without it.

Commands

Command Default shortcut
dbt charts: Open Preview —
dbt charts: Open Preview to the Side Cmd/Ctrl+Shift+V
dbt charts: Refresh Preview —
dbt charts: Export as HTML —
dbt charts: Export as PNG —
dbt charts: Validate Dashboard —
dbt charts: Setup AI Integration (MCP) —

Settings

Setting Default What it does
dbt_charts.cli.path dct Path to the dbt charts CLI executable
dbt_charts.preview.autoRefresh true Re-render the preview as the file changes
dbt_charts.preview.refreshDelay 500 Milliseconds to wait after a change before re-rendering
dbt_charts.languageServer.enabled true Run the Python language server (starts when you open your first board file)
dbt_charts.languageServer.pythonPath python Interpreter used to run the language server
dbt_charts.trace.server off Log LSP traffic to the dbt charts output channel

Point dbt_charts.cli.path at your project's virtualenv (for example .venv/bin/dct) when dbt charts is installed per-project rather than globally.

Troubleshooting

Preview says the render command failed, or dct was not found. The extension could not run the CLI. Check that dct --version works in a terminal, and if dbt charts lives in a virtualenv, set dbt_charts.cli.path to that environment's dct.

A dashboard file isn't highlighted. Its path probably doesn't match any of the rules under Which files it recognizes. Move it under charts/, rename it to *.dataface.yml, or set the language mode manually from the status bar.

The language server won't start. Confirm that the interpreter in dbt_charts.languageServer.pythonPath has both dbt charts and pygls installed, then set dbt_charts.trace.server to verbose and check the dbt charts output channel.

The preview renders but charts are empty. That's a data problem, not an editor problem — run dct query against the same source to check what the query returns.