Installation & Setup¶

Get dbt charts installed and configured in your environment.

Prerequisites¶

Before installing dbt charts, ensure you have:

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

dbt charts works with plain SQL, so dbt is optional. If you already run dbt, dbt charts 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 dbt charts¶

# with uv (recommended) — installs dct as a standalone CLI tool
uv tool install dbt-charts

# with pip
pip install dbt-charts

uv tool install is not the same as uv pip install dbt-charts. uv tool install creates an isolated environment for the dct CLI and puts a shim on your PATH (via ~/.local/bin), independent of any project virtualenv — the closest uv equivalent to a global pip install. uv pip install dbt-charts instead installs dbt charts into the currently active virtualenv, the way pip install does — reach for that only when you want to import dbt_charts from your own project code, not when you just want the dct command available everywhere.

To use dct mcp serve (the MCP server for external AI agents), dbt charts needs the optional mcp extras. If you run it without them installed, dbt charts will detect the missing packages and offer to install them interactively. For non-interactive setups (CI, scripts), set DCT_NO_AUTO_INSTALL=1 to suppress the prompt and get a clear error with the exact install command instead.

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

Verify Installation¶

dct --version

You should see the dbt charts version number.

Install the Editor Extension¶

If you author dashboards in VS Code or Cursor, install the dbt charts extension — it adds board YAML highlighting, snippets, and a live preview of the rendered dashboard beside your file:

dct init code      # VS Code
dct init cursor    # Cursor

See the VS Code & Cursor Extension page for everything it provides and how to install it without the CLI.

Upgrading¶

dbt charts 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 dbt-charts
# or, with uv:
uv pip install -U dbt-charts

Confirm which install is active:

dct --version

2. Refresh project artifacts¶

After upgrading the package:

dct init skills

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

Targeted installs:

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

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

Configuration¶

Connect a Data Source¶

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

# dbt_charts.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:

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

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

Create Charts Directory¶

Create a directory for your dashboards (called "charts" in dbt charts):

mkdir charts

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

Project Configuration (Optional)¶

dbt charts supports project-wide configuration via a dbt_charts.yml file in your project root.

What belongs in dbt_charts.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 boards that do not specify one). The model rejects other unknown keys, so stray presentation keys (frame:, style:) raise a clear error.

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

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

Execution settings¶

The execution: block controls query parallelism and timeouts:

# dbt_charts.yml
execution:
  max_workers: 8
  max_query_duration_seconds: 300

max_workers — maximum parallel query workers per render. Effective only for external warehouse executors (BigQuery, Snowflake, Postgres, etc.) — DuckDB and SQLite serialize access internally regardless of this setting. Also settable per-run via --max-workers on dct render / dct serve, or the DCT_MAX_WORKERS env var.
max_query_duration_seconds — the safety ceiling on how long a single query may run, enforced as a server-side statement timeout on network warehouses. DuckDB and SQLite are local file databases with no server to enforce a timeout, so this has no effect on them. Override per source with sources.<name>.max_query_duration_seconds:

# dbt_charts.yml
sources:
  analytics:
    type: snowflake
    max_query_duration_seconds: 60

Server settings¶

server.markdown_metadata_table renders non-board frontmatter keys in .md files as a metadata table at the top of the page. Off by default, so AGENTS.md, README, and other prose files served through dbt charts don't suddenly acquire header tables:

# dbt_charts.yml
server:
  markdown_metadata_table: true

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

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

Configuration Discovery: - dbt charts searches for dbt_charts.yml starting from the current working directory and walks up to the filesystem root. - If you're working in a dbt project, dbt charts also detects dbt_project.yml as a project root indicator. - If no dbt_charts.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 dbt charts to an Existing dbt Project¶

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

cd my-dbt-project

# 1. Install dbt charts (see the Installation section above)

# 2. Bootstrap the project — creates charts/, dbt_charts.yml, and workflow skills
dct init

# 3. Preview the starter dashboard
dct serve

dct init creates a charts/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)
├── dbt_charts.yml           # Optional: engine knobs (sources, server port, etc.)
├── .agents/skills/          # Workflow skills for Cursor, Codex, and Copilot
├── charts/                  # dbt charts 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: - charts/ is the canonical directory for all dashboard YAML files. The dct CLI defaults to this directory. - Partials live in charts/partials/ and are prefixed with _ (e.g., _header.yml). They're reusable fragments imported by other dashboards. - Subdirectories are fine — charts/sales/overview.yml maps to the URL /charts/sales/overview/ when served. - dbt_charts.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 charts/meta.yaml instead.

dbt charts reads your dbt project automatically. When you run dct serve or dct validate inside a dbt project directory, dbt charts 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 charts/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:
```
dct validate charts/test.yml
```
Preview the dashboard:
```
dct serve
```
Open your browser to the URL printed by dct 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 dct validate to check for errors

AI / MCP Setup for IDEs¶

dbt charts 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
dct init mcp

# Or configure a specific client
dct init mcp cursor     # Cursor
dct init mcp vscode     # VS Code / GitHub Copilot
dct init mcp claude     # Claude Desktop
dct init mcp codex      # OpenAI Codex CLI
dct 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_board tool) - Search existing dashboards (search_boards tool)

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

Manual Setup¶

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

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

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

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

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

If your dbt charts 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. dct 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¶

dct 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: dct validate
Check dbt configuration: dbt debug
Review the YAML Schema Reference