Skip to content

CLI Reference

The dct command-line interface is the primary surface for working with dbt charts. Every dashboard operation — validating board YAML, browsing your warehouse, rendering charts, running the local server, configuring AI assistants — runs through dct.

This section documents every command, its flags, and the typical workflows that combine them.

Getting help

dct --help               # Top-level command list
dct <command> --help     # Per-command flags and examples
dct --version            # Print version + install path

If output looks stale or unexpected, dct --version is the first thing to check.

Command catalog

Authoring & validation

Command Purpose
validate Fast YAML schema + cross-reference validation, no DB, no execute
migrate Rewrite supported older YAML syntax to the current grammar
describe Describe a dashboard's queries / charts / variables

Data discovery

Command Purpose
search Search dashboards by keyword with ranked results

Query inspection

Command Purpose
query Execute a named board query or raw SQL; add --validate to lint, --describe for column schema

Rendering & serving

Command Purpose
render Render a board to SVG, HTML, PNG, PDF, JSON, YAML, or terminal
serve Start the local dbt charts server with live board routes
playground Interactive playground with YAML editor and live preview

Project setup & scaffolding

Command Purpose
init Bootstrap a dbt charts project, plus AI / editor integrations
docs Browse dbt charts YAML reference docs offline, or look up a render-warning code
skills List packaged agent skills or show one by name

AI integration

Command Purpose
CLI and MCP for AI assistants When to use the CLI vs MCP for AI assistants
mcp MCP (Model Context Protocol) server commands for AI assistant integration

Common options

Most commands accept the same project-resolution and output-formatting flags.

--project-dir PATH

Project root for resolving relative paths. If not provided, dct walks up from the current directory looking for dbt_charts.yml or dbt_project.yml.

dct validate --project-dir /path/to/dbt/project
dct query warehouse "SELECT 1" --project-dir /path/to/project

Use this when:

  • Running dct from outside the project directory
  • Working with multiple projects from one shell
  • CI/CD pipelines where project path varies

Can also be set via the DCT_PROJECT_DIR environment variable; the flag wins when both are set.

export DCT_PROJECT_DIR=/path/to/project
dct validate                           # equivalent to --project-dir /path/to/project
dct render charts/sales.yaml --project-dir /other/project  # flag wins

--json

Most read-shaped commands (search, describe, docs, skills, query, validate) support --json for stable, agent-consumable output.

dct query mydb "SELECT table_name FROM INFORMATION_SCHEMA.TABLES" --json | jq '.rows'
dct validate charts/sales.yaml --json

The JSON shape is contract-stable; pipe into jq for any cross-cutting query the curated verbs don't anticipate.

--var KEY=VALUE

For commands that compile or execute a board (render, query, sometimes serve), variable values can be supplied repeatedly:

dct render charts/sales.yaml --var region=West --var category=Electronics
dct query charts/sales.yaml revenue --var region=West

Exit codes

All commands follow standard Unix exit codes:

  • 0 — success
  • 1 — error (validation failed, compilation error, file not found, etc.)
  • 2 — bad CLI arguments (Typer / Click convention)

Suitable for use in scripts and CI/CD pipelines:

#!/bin/bash
if dct validate charts/ --strict; then
  echo "All dashboards valid"
else
  echo "Validation failed"
  exit 1
fi

Environment variables

dbt charts respects dbt environment variables:

Variable Purpose
DBT_PROFILES_DIR Custom profiles directory (default: ~/.dbt)
DBT_TARGET Default target for dct serve

dbt charts-specific variables:

Variable Purpose
DCT_PROJECT_DIR Default project directory for all commands that accept --project-dir (overridden by the flag)
DCT_PORT Default port for dct serve (overridden by --port)
DCT_DEFAULT_THEME Runtime override for the dct serve default theme — all boards without an explicit theme: inherit the resolved value. Resolution at startup: env var > the project's dbt_charts.yml top-level theme: key > shipped default (editorial — editorial voice on the stark structural root). Set at serve startup; restarts are required to pick up changes. Examples: stark (stripped-back / utilitarian), neon (dark), cream, vivid. The VS Code inspector sets the env var automatically per session. To pin a project's default theme in source control, set theme: <name> in dbt_charts.yml.
DCT_PLAYGROUND_BASE_DIR Default base for dct playground
DCT_PLAYGROUND_URL Base URL for the "Open in Playground" link the docs site attaches to every dbt-charts-example fence. Default: https://play.dataface.com. Rarely changed outside of local docs development.
DCT_DOCS_URL Base URL for the public docs site, used by dct docs (web link on the topic index) and by the docs links carried on structured errors. Default: https://docs.dataface.com.
DCT_MAX_WORKERS Default --max-workers for dct render and dct serve (max parallel query workers; default 8 from config). Overridden by the flag. No effect on DuckDB, which serializes access regardless.
DCT_CACHE_PATH Default --cache path for dct render, dct serve, and dct mcp serve — persists the query-result cache to a DuckDB file instead of discarding it in-memory on exit. Overridden by the flag; mutually exclusive with --no-cache.
OPENAI_API_KEY API key for the dct playground AI Copilot
DATAFACE_LLM_READ_TIMEOUT_SECONDS Max seconds between streamed chunks on an LLM call before the connection is treated as stalled. Default: 60.
DATAFACE_LLM_CONNECT_TIMEOUT_SECONDS Max seconds to establish the connection on an LLM call. Default: 10.

Workflow examples

Author → check → preview

# 1. Edit a board
vim charts/sales.yaml

# 2. Fast structural validation (no DB hit)
dct validate charts/sales.yaml

# 3. Full validation including warehouse references
dct render charts/sales.yaml --format json

# 4. Inspect a single query
dct query charts/sales.yaml revenue --limit 10

# 5. Render to terminal for quick check
dct render charts/sales.yaml --format terminal

# 6. Serve interactively
dct serve

Explore an unfamiliar warehouse

# 1. What schemas and tables exist?
dct query analytics "SELECT table_schema, table_name FROM INFORMATION_SCHEMA.TABLES"

# 2. What columns does a table have?
dct query analytics "SELECT column_name, data_type FROM INFORMATION_SCHEMA.COLUMNS WHERE table_name = 'orders'"

# 3. Find every column that looks like a timestamp
dct query analytics "SELECT table_name, column_name FROM INFORMATION_SCHEMA.COLUMNS WHERE column_name LIKE '%\_at' ESCAPE '\'"

# 4. Search dashboards that already use it
dct search "orders"

CI pipeline

# Validate all dashboards before deployment
dct validate charts/ --strict

# Render dashboards as deployable artifacts
for board in charts/*.yml; do
  dct render "$board" --format html --output "dist/$(basename "$board" .yml).html"
done

Wire up an AI assistant

# CLI-first: install skills to agent directories (see ai-cli-and-mcp.md)
dct init skills              # .agents/skills/ for Cursor/Codex + Claude Code skills dir

# Optional: also configure MCP for MCP-aware clients
dct init mcp                 # auto-detect Cursor, VS Code, Claude Code, Codex, …

# Or run the MCP server directly for any MCP-aware client
dct mcp serve