Skip to content

CLI Reference

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

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

Getting help

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

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

Command catalog

Authoring & validation

Command Purpose
validate Fast YAML schema + cross-reference validation, no DB, no execute
describe Describe a dashboard's queries / charts / variables, or look up an error code

Data discovery

Command Purpose
search Search dashboards by keyword with ranked results

Query inspection

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

Rendering & serving

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

Project setup & scaffolding

Command Purpose
init Bootstrap a Dataface project, plus AI / editor integrations
docs Browse Dataface YAML reference docs offline
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
chat Chat with a terminal AI agent
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, dft walks up from the current directory looking for dataface.yml, dataface.yaml, or dbt_project.yml.

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

Use this when:

  • Running dft 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 DFT_PROJECT_DIR environment variable; the flag wins when both are set.

export DFT_PROJECT_DIR=/path/to/project
dft validate                           # equivalent to --project-dir /path/to/project
dft render faces/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.

dft query mydb "SELECT table_name FROM INFORMATION_SCHEMA.TABLES" --json | jq '.rows'
dft validate faces/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 face (render, query, sometimes serve), variable values can be supplied repeatedly:

dft render faces/sales.yaml --var region=West --var category=Electronics
dft query faces/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 dft validate faces/ --strict; then
  echo "All dashboards valid"
else
  echo "Validation failed"
  exit 1
fi

Environment variables

Dataface respects dbt environment variables:

Variable Purpose
DBT_PROFILES_DIR Custom profiles directory (default: ~/.dbt)
DBT_PROJECT_DIR Default project directory
DBT_PROFILE Default profile name
DBT_TARGET Default target for dft serve

Dataface-specific variables:

Variable Purpose
DFT_PROJECT_DIR Default project directory for all commands that accept --project-dir (overridden by the flag)
DFT_PORT Default port for dft serve (overridden by --port)
DFT_DEFAULT_THEME Runtime override for the dft serve default theme — all faces without an explicit theme: inherit the resolved value. Resolution at startup: env var > the project's dataface.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), dark, cream, carbong100. 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 dataface.yml.
DFT_PLAYGROUND_BASE_DIR Default base for dft playground
DFT_DOCS_URL Base URL for the public docs site. Used by dft docs (web link on the topic index) and the playground gallery (docs: face links). Default: https://docs.it-dataface.com
OPENAI_API_KEY API key for dft chat and dft playground AI Copilot

Workflow examples

Author → check → preview

# 1. Edit a face
vim faces/sales.yaml

# 2. Fast structural validation (no DB hit)
dft validate faces/sales.yaml

# 3. Full validation including warehouse references
dft render faces/sales.yaml --format json

# 4. Inspect a single query
dft query faces/sales.yaml revenue --limit 10

# 5. Render to terminal for quick check
dft render faces/sales.yaml --format terminal

# 6. Serve interactively
dft serve

Explore an unfamiliar warehouse

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

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

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

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

CI pipeline

# Validate all dashboards before deployment
dft validate faces/ --strict

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

Wire up an AI assistant

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

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

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