Installation & Setup¶

Get Dataface installed and configured in your environment.

Prerequisites¶

Before installing Dataface, ensure you have:

Python 3.10+ installed
A database Dataface can query — Postgres, Snowflake, BigQuery, DuckDB, SQLite, or a local CSV/Parquet file

Dataface works with plain SQL, so dbt is optional. If you already run dbt, Dataface can read your profiles.yml connection and — if you have a Semantic Layer — query MetricFlow metrics and dimensions. But you don't need dbt or a Semantic Layer to build dashboards.

Installation¶

Install Dataface¶

pip install dataface
# or, with uv:
uv pip install dataface

To use dft chat (the AI agent), Dataface needs the optional chat extras. If you run dft chat without them installed, Dataface will detect the missing packages and offer to install them interactively. For non-interactive setups (CI, scripts), set DFT_NO_AUTO_INSTALL=1 to suppress the prompt and get a clear error with the exact install command instead. The easiest way to pre-install chat support is dft init --chat-extra during project setup.

To use dft playground (the interactive YAML editor), Dataface needs the optional playground extra (dataface[playground]). dataface-playground is not yet on public PyPI — it ships via the private Dataface registry. If you run dft playground without it installed, Dataface will detect the missing packages and offer to install them interactively. Use dft init --with-playground during project setup to attempt the install; if the package is unavailable (e.g. public PyPI only), dft init skips playground with a warning and completes successfully.

Verify Installation¶

dft --version

You should see the Dataface version number.

Upgrading¶

Dataface separates package upgrade (the Python wheel) from project refresh (workflow skill files copied into your repo). This matches how dbt, gh, and npx skills handle upgrades — pip bumps the tool; a separate command refreshes project-local artifacts.

1. Upgrade the package¶

pip install -U dataface
# or, with uv:
uv pip install -U dataface

Confirm which install is active:

dft --version

2. Refresh project artifacts¶

After upgrading the package:

dft init skills

Re-syncs skill directories. Retired skill names are removed; current skills are overwritten in place.

Targeted installs:

dft init skills agents          # .agents/skills/ (Cursor, Codex, Copilot)
dft init skills claude          # Claude Code skills directory
dft init skills --dir PATH      # custom path

Re-run after pip install -U dataface to pull in skills added by the new release.

Configuration¶

Connect a Data Source¶

Name the database Dataface reads from in dataface.yml. A local DuckDB file needs no credentials, so it's the quickest way to start:

# dataface.yml
sources:
  analytics:
    type: duckdb
    path: ./data/analytics.duckdb

Direct source types (postgres, snowflake, bigquery, redshift, mysql, sqlite) use the same credential fields as dbt profiles. See Sources for every type and its connection settings.

Using dbt? Set type: dbt_profile to reuse your existing profiles.yml connection instead of repeating credentials:

# dataface.yml
sources:
  analytics:
    type: dbt_profile
    profile: my_dbt_project
    target: dev

With a dbt profile source, Dataface can also query your Semantic Layer metrics and dimensions — see MetricFlow.

Create Faces Directory¶

Create a directory for your dashboards (called "faces" in Dataface):

mkdir faces

Place your dashboard YAML files in this directory. The faces/ directory is the canonical location for all Dataface dashboard files. The CLI defaults to this directory for validate, serve, and render commands.

Project Configuration (Optional)¶

Dataface supports project-wide configuration via a dataface.yml file in your project root.

What belongs in dataface.yml: engine knobs — data sources, server port, execution settings. theme: is also allowed here as a serve-time default-theme knob (it sets the fallback theme for faces that do not specify one). The model rejects other unknown keys, so stray presentation keys (board:, style:) raise a clear error.

# dataface.yml — engine knobs only
server:
  port: 8080

sources:
  my_db:
    type: duckdb
    path: data.duckdb

What belongs in faces/meta.yaml: board layout and other presentation defaults. meta.yaml is a partial face that applies as a cascade base to every face in its directory.

# faces/meta.yaml — presentation defaults
style:
  board:
    width: 1440.0     # Override default board width (default: 1200.0)
    card_padding: 20.0

Configuration Discovery: - Dataface searches for dataface.yml starting from the current working directory and walks up to the filesystem root. - If you're working in a dbt project, Dataface also detects dbt_project.yml as a project root indicator. - If no dataface.yml is found, built-in defaults are used.

These settings apply to all dashboards in your project unless overridden in individual dashboard YAML files.

Adding Dataface to an Existing dbt Project¶

If you already have a dbt project, adding Dataface takes three steps:

cd my-dbt-project

# 1. Install Dataface (see the Installation section above)

# 2. Bootstrap the project — creates faces/, dataface.yml, and workflow skills
dft init

# 3. Preview the starter dashboard
dft serve

dft init creates a faces/guide.yml guide dashboard that works without a database connection. It also installs workflow skills for local AI assistants unless you pass --no-skills. Open the URL it prints to see the guide live.

Your dbt project should now look like this:

my-dbt-project/
├── dbt_project.yml          # dbt config (existing)
├── models/                  # dbt models (existing)
├── profiles.yml             # dbt profiles (existing)
├── dataface.yml             # Optional: engine knobs (sources, server port, etc.)
├── .agents/skills/          # Workflow skills for Cursor, Codex, and Copilot
├── faces/                   # Dataface dashboards
│   ├── guide.yml            # Starter guide — queries, charts, layout, KPIs
│   ├── sales_dashboard.yml
│   └── partials/            # Reusable dashboard fragments (prefixed with _)
│       └── _header.yml
└── assets/                  # Optional: images, CSV data files
    ├── images/
    └── data/

Key conventions: - faces/ is the canonical directory for all dashboard YAML files. The dft CLI defaults to this directory. - Partials live in faces/partials/ and are prefixed with _ (e.g., _header.yml). They're reusable fragments imported by other dashboards. - Subdirectories are fine — faces/sales/overview.yml maps to the URL /faces/sales/overview/ when served. - dataface.yml is optional — it sets engine knobs (sources, server port, execution config). Place it next to dbt_project.yml. Board layout and other presentation defaults belong in faces/meta.yaml instead.

Dataface reads your dbt project automatically. When you run dft serve or dft validate inside a dbt project directory, Dataface discovers dbt_project.yml and connects to your database via profiles.yml. Your queries can hit models with plain SQL, and — if you've configured a Semantic Layer — query MetricFlow metrics and dimensions.

Verification¶

Test Installation¶

Create a simple dashboard file faces/test.yml:

title: "Test Dashboard"

source: analytics

queries:
  test:
    sql: |
      SELECT
        date_trunc('month', ordered_at) AS month,
        SUM(amount) AS revenue
      FROM orders
      GROUP BY 1
      ORDER BY 1

charts:
  test_chart:
    title: "Revenue by Month"
    query: test
    type: bar
    x: month
    y: revenue

rows:
  - test_chart

Validate the dashboard:
```
dft validate faces/test.yml
```
Preview the dashboard:
```
dft serve
```
Open your browser to the URL printed by dft serve on startup

If you see the dashboard, installation is successful!

Troubleshooting Common Issues¶

dbt Not Found¶

Error: dbt: command not found

Solution: Install dbt-core:

pip install dbt-core

MetricFlow Not Available¶

Error: MetricFlow not found or semantic layer errors

Solution: Install MetricFlow as a separate package:

pip install dbt-metricflow

Database Connection Issues¶

Error: Cannot connect to database

Solution: - Check your profiles.yml configuration - Verify database credentials - Test dbt connection: dbt debug

YAML Syntax Errors¶

Error: YAML parsing errors

Solution: - Check YAML indentation (use spaces, not tabs) - Validate YAML syntax with a YAML validator - Use dft validate to check for errors

AI / MCP Setup for IDEs¶

Dataface includes an MCP (Model Context Protocol) server that gives AI coding assistants access to your data schema, queries, and dashboard tools. To configure your IDE:

# Auto-detect installed AI clients and configure all of them
dft init mcp

# Or configure a specific client
dft init mcp cursor     # Cursor
dft init mcp vscode     # VS Code / GitHub Copilot
dft init mcp claude     # Claude Desktop
dft init mcp codex      # OpenAI Codex CLI
dft init mcp claude-code # Claude Code (.mcp.json)

This writes the appropriate MCP config file for each client (e.g., .cursor/mcp.json, .vscode/mcp.json). After running this, your AI assistant can: - Execute queries against your database (execute_query tool) — including INFORMATION_SCHEMA queries to browse tables and columns - Render dashboards from YAML (render_dashboard tool) - Search existing dashboards (search_dashboards tool)

Tip: Run dft init mcp after cloning any repo that uses Dataface — it auto-detects which AI clients you have installed.

Manual Setup¶

If you prefer to configure manually, add the Dataface MCP server to your client's config.

For JSON-based clients (Cursor, VS Code, Claude Desktop, Claude Code, Copilot):

{
  "mcpServers": {
    "dataface": {
      "command": "dft",
      "args": ["mcp", "serve"]
    }
  }
}

For Codex (TOML — .codex/config.toml):

[mcp_servers.dataface]
command = "dft"
args = ["mcp", "serve"]

If your Dataface or dbt project lives in a subdirectory of the workspace your AI client opens, append "--project-dir", "/abs/path/to/your/project" to args so the server starts in the right place. dft init mcp adds this for you when you pass --project-dir <path> or when it detects that the workspace and project roots diverge.

Config file locations: - Cursor: .cursor/mcp.json - VS Code / Copilot: .vscode/mcp.json (use "servers" instead of "mcpServers") - Claude Desktop: ~/.config/claude/config.json - Claude Code: .mcp.json (project root) - Codex CLI: .codex/config.toml (TOML; project must be trusted by Codex). For global setup, write to ~/.codex/config.toml instead.

Starting the MCP Server Manually¶

dft mcp serve

This starts the MCP server in stdio mode (for IDE integration). It also starts an embedded HTTP server on port 8765 for dashboard preview rendering.

Next Steps¶

Getting Started Guide - Create your first dashboard
CLI Reference - Complete CLI command reference (validate, render, serve, schema, and more)
Queries Guide - Learn about queries
Examples - See example dashboards

Troubleshooting Guide - Common installation and setup issues
Best Practices Guide - Dashboard design best practices

Getting Help¶

If you encounter issues:

Check the Troubleshooting Guide
Check your dashboard: dft validate
Check dbt configuration: dbt debug
Review the YAML Schema Reference