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 Validate face YAML files for errors and warnings
check Fast YAML schema + cross-reference validation, no DB, no execute
explain Describe a face file's queries / charts / variables, or look up an error code

Data discovery

Command Purpose
schema Browse the data hierarchy: source → schema → table → column
schema-search Full-text + filter search across the schema corpus
search Search dashboards by keyword with ranked results
context Question-aware schema retrieval over the Super Schema artifact

Query inspection

Command Purpose
query Run a named query from a face and show columns + sample rows
validate-query Validate a SQL query for structural issues (fanout, missing joins, etc.)
describe-query Return the column schema for a SQL string without executing it

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
new Scaffold new face files from packaged skill examples
docs Browse Dataface YAML reference docs offline
skills List packaged agent skills or show one by name

AI integration

Command Purpose
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 schema --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

--json

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

dft schema --source mydb --schema main --json | jq '.sources.mydb.schemas.main.tables | keys'
dft check faces/sales.yml --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.yml --var region=West --var category=Electronics
dft query revenue --in faces/sales.yml --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_PORT Default port for dft serve (overridden by --port)
DATAFACE_PLAYGROUND_BASE_DIR Default base for dft playground
OPENAI_API_KEY API key for dft chat and dft playground AI Copilot

Workflow examples

Author → validate → preview

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

# 2. Fast structural validation (no DB hit)
dft check faces/sales.yml

# 3. Full validation including warehouse references
dft validate faces/sales.yml

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

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

# 6. Serve interactively
dft serve

Explore an unfamiliar warehouse

# 1. What's configured?
dft schema

# 2. What tables exist?
dft schema --source warehouse --schema analytics

# 3. Profile a specific table
dft schema --source warehouse --schema analytics --table orders

# 4. Find every column that looks like a timestamp
dft schema-search ".*_at$" --regex --json --fields location,matched_field

# 5. 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

# Configure Cursor, Claude Code, ChatGPT (auto-detected)
dft init mcp

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