Skip to content

VS Code & Cursor Extension

The Dataface extension turns any editor built on VS Code — VS Code itself, Cursor, and other forks — into a dashboard authoring environment: syntax highlighting for face 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 Dataface installed, one command downloads and installs the extension into your editor:

dft init code      # VS Code
dft init cursor    # Cursor

The interactive dft init wizard also offers this step for whichever editors it finds on your PATH. See dft 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 dataface-<version>.vsix \
  https://storage.googleapis.com/dataface-downloads/dataface-<version>.vsix

Requirements

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

Which files it recognizes

The extension switches a file into Dataface 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 dataface.yml / dataface.yaml your project config
Any .yml, .yaml, or .md file under a faces/ directory faces/sales.yml, faces/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 faces/

The faces/ rule matches on an exact path segment, so a directory named my_faces_archive/ is left alone. The content rule is a fallback for files kept outside faces/ — 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 Dataface: 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 dft 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 dft CLI. The extension looks for it in a venv/, .venv/, or env/ beside your workspace before falling back to PATH; point dataface.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 dft validate, so you can fix the YAML without leaving the editor.

Syntax highlighting

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

  • YAML structure, with Dataface'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 face file open:

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

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

AI integration

The extension pairs with the Dataface MCP server, which gives Cursor's and VS Code's AI assistants tools to inspect your schema, run queries, and render dashboards. Run Dataface: 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 Dataface entry is configured yet.

The equivalent from a terminal:

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

See dft 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 compile() produces (invalid chart and input types, undefined query references, missing required fields, render-time warnings like an overly narrow bar band), each with a clickable code that opens its documentation page
  • 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 face file, so a workspace with no face 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 Dataface installed. If the server can't start, a Dataface: 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:

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

To turn it off entirely:

{
  "dataface.languageServer.enabled": false
}

The interpreter you point at needs Dataface and pygls installed:

pip install dataface pygls

Everything else in this page works without it.

Commands

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

Settings

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

Point dataface.cli.path at your project's virtualenv (for example .venv/bin/dft) when Dataface is installed per-project rather than globally.

Troubleshooting

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

A dashboard file isn't highlighted. Its path probably doesn't match any of the rules under Which files it recognizes. Move it under faces/, 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 dataface.languageServer.pythonPath has both Dataface and pygls installed, then set dataface.trace.server to verbose and check the Dataface output channel.

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