CLI Reference¶

Complete reference for the dft command-line interface.

Overview¶

The dft CLI provides commands to validate, compile, serve, and build Dataface dashboards. All commands work with your existing dbt project and Semantic Layer configuration.

Getting Help¶

View help for any command:

dft --help
dft validate --help
dft compile --help
dft serve --help

Version¶

Check your Dataface version:

dft --version

Commands¶

`validate`¶

Validate dashboard YAML files for errors and warnings.

Usage:

dft validate [PATH] [OPTIONS]

Arguments:

PATH (optional): Path to dashboard file or directory (default: dashboards/)

Options:

--project-dir PATH: dbt project directory (default: current directory)
--strict: Fail on warnings (exit code 1 if any warnings found)

Examples:

# Validate all dashboards in default directory
dft validate

# Validate a specific dashboard file
dft validate dashboards/sales.yml

# Validate all dashboards in a directory
dft validate dashboards/

# Validate with strict mode (fail on warnings)
dft validate --strict

# Validate with custom project directory
dft validate --project-dir /path/to/dbt/project

Exit Codes:

0: Success (no errors, and no warnings if --strict is used)
1: Errors found, or warnings found with --strict flag

Use Cases:

CI/CD Pipelines: Validate dashboards before deployment
Pre-commit Hooks: Catch errors before committing
Development: Check dashboard syntax while editing

Example Output:

❌ dashboards/sales.yml:
  Error: Unknown metric 'total_sales' in query 'q_revenue'
  Error: Missing required field 'type' in chart 'revenue_chart'

⚠️  dashboards/customers.yml:
  Warning: Chart 'customer_table' has no title

`compile`¶

Compile a dashboard YAML file to normalized JSON or YAML.

Usage:

dft compile DASHBOARD [OPTIONS]

Arguments:

DASHBOARD (required): Path to dashboard YAML file

Options:

--output PATH: Output file path (default: stdout)
--format FORMAT: Output format: json or yaml (default: json)
--project-dir PATH: dbt project directory (default: current directory)

Examples:

# Compile to JSON (stdout)
dft compile dashboards/sales.yml

# Compile to JSON file
dft compile dashboards/sales.yml --output sales.json

# Compile to YAML file
dft compile dashboards/sales.yml --format yaml --output sales.yaml

# Compile with custom project directory
dft compile dashboards/sales.yml --project-dir /path/to/dbt/project

Use Cases:

Debugging: Inspect normalized dashboard structure
Pre-compilation: Generate compiled dashboards for faster runtime loading
Integration: Generate normalized JSON for other tools
Validation: Verify compilation succeeds before serving

Example Output:

{
  "dashboard": {
    "name": "sales",
    "title": "Sales Dashboard",
    "queries": {
      "q_revenue": {
        "metrics": ["total_revenue"],
        "dimensions": ["month"]
      }
    },
    "sections": [
      {
        "title": "Overview",
        "layout": "row",
        "charts": {
          "revenue_chart": {
            "type": "bar",
            "query": "q_revenue",
            "x": "month",
            "y": "total_revenue"
          }
        }
      }
    ]
  }
}

`serve`¶

Start an interactive preview server for a dashboard.

Usage:

dft serve DASHBOARD [OPTIONS]

Arguments:

DASHBOARD (required): Path to dashboard YAML file

Options:

--port PORT: Port number (default: 8080)
--host HOST: Host address (default: localhost)
--project-dir PATH: dbt project directory (default: current directory)
--reload: Enable auto-reload on file changes

Examples:

# Start server on default port (8080)
dft serve dashboards/sales.yml

# Start server on custom port
dft serve dashboards/sales.yml --port 3000

# Start server accessible from network
dft serve dashboards/sales.yml --host 0.0.0.0

# Start server with auto-reload
dft serve dashboards/sales.yml --reload

# Combine options
dft serve dashboards/sales.yml --port 3000 --host 0.0.0.0 --reload

Use Cases:

Development: Preview dashboards while editing
Testing: Test dashboard interactivity and queries
Demo: Share dashboards with team members
Debugging: Inspect query results and chart rendering

Server Features:

Live query execution using your dbt Semantic Layer
Interactive chart rendering
Variable/filter support
Auto-reload on file changes (with --reload flag)

Accessing the Dashboard:

After starting the server, open your browser to:

http://localhost:8080

(Replace localhost and 8080 with your --host and --port values)

Stopping the Server:

Press CTRL+C in the terminal to stop the server.

`render`¶

Render a dashboard to various output formats (SVG, HTML, PNG, PDF, or terminal).

Usage:

dft render DASHBOARD [OPTIONS]

Arguments:

DASHBOARD (required): Path to dashboard YAML file

Options:

--output PATH: Output file path (default: renders/ folder with dashboard name)
--format FORMAT: Output format: svg, html, png, pdf, or terminal (default: svg)
--project-dir PATH: Project directory for resolving relative paths

Examples:

# Render to SVG (default)
dft render dashboards/sales.yml

# Render to HTML
dft render dashboards/sales.yml --format html

# Render to PNG
dft render dashboards/sales.yml --format png

# Render to PDF
dft render dashboards/sales.yml --format pdf

# Render to terminal (prints directly to stdout)
dft render dashboards/sales.yml --format terminal

# Render with custom output path
dft render dashboards/sales.yml --output sales.svg

# Render with custom project directory
dft render dashboards/sales.yml --project-dir /path/to/dbt/project

Output Formats:

svg (default): Scalable vector graphics, perfect for embedding and presentations
html: Interactive HTML page with embedded SVG charts
png: Raster image format, good for screenshots and thumbnails
pdf: PDF document, ideal for reports and printing
terminal: Terminal output with ASCII/Unicode charts, prints directly to stdout

Use Cases:

Static Export: Generate shareable dashboard files
Documentation: Include dashboard images in documentation
Quick Preview: Use terminal format for fast CLI previews
CI/CD: Generate dashboard outputs in build pipelines
Reports: Export to PDF for formal reports

Terminal Format:

The terminal format renders dashboards directly to stdout with: - ASCII/Unicode charts using Plotext - Formatted tables using Rich - Color-coded output - Auto-detected terminal size

Example terminal output:

$ dft render dashboards/sales.yml --format terminal
================================================================================
 Sales Dashboard
================================================================================

Daily Revenue Trend
      ┌────────────────────────────────────────────────────────────┐
2400.0┤    ▗                ▟                                 ▗    │
2141.7┤   ▄▀▖              ▞ ▚               ▞▖              ▄▀▖   │
...

Note: Terminal format does not create a file - it prints directly to stdout. Use shell redirection to save to a file:

dft render dashboards/sales.yml --format terminal > dashboard.txt

`build`¶

Build a dashboard to static output files.

Status: ⚠️ Not yet implemented (coming in Phase 4)

Planned Usage:

dft build DASHBOARD [OPTIONS]

Planned Options:

--mode MODE: Output mode: live, html, pdf, svg, png, json (default: html)
--output PATH: Output directory or file
--bake-data: Bake data into static output (for HTML mode)
--project-dir PATH: dbt project directory

Planned Examples:

# Build to HTML
dft build dashboards/sales.yml --mode html

# Build to PDF
dft build dashboards/sales.yml --mode pdf

# Build with baked-in data
dft build dashboards/sales.yml --mode html --bake-data

# Build to custom output directory
dft build dashboards/sales.yml --output ./dist/

`playground`¶

Start an interactive playground with YAML editor and live preview.

Status: ⚠️ Not yet implemented (see plans/guides/EXAMPLES_AND_PLAYGROUND.md)

Planned Usage:

dft playground [OPTIONS]

Planned Options:

--port PORT: Port number (default: 8080)
--data PATH: Path to sample data (DuckDB file)

Planned Examples:

# Start playground
dft playground

# Start playground on custom port
dft playground --port 3000

# Start playground with sample data
dft playground --data ./my_data.db

Common Options¶

`--project-dir`¶

Specify the dbt project directory. If not provided, defaults to the current working directory.

dft validate --project-dir /path/to/dbt/project
dft compile dashboards/sales.yml --project-dir /path/to/dbt/project
dft serve dashboards/sales.yml --project-dir /path/to/dbt/project

When to Use:

Running commands from outside the dbt project directory
Working with multiple dbt projects
CI/CD pipelines where project path may vary

Workflow Examples¶

Development Workflow¶

# 1. Create/edit dashboard YAML file
vim dashboards/sales.yml

# 2. Validate syntax
dft validate dashboards/sales.yml

# 3. Compile to check for errors
dft compile dashboards/sales.yml

# 4. Start preview server
dft serve dashboards/sales.yml --reload

# 5. Open browser to http://localhost:8080
# 6. Make changes and see them auto-reload

CI/CD Pipeline¶

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

# If validation passes, compile dashboards for deployment
for dashboard in dashboards/*.yml; do
  dft compile "$dashboard" --output "compiled/$(basename $dashboard .yml).json"
done

Debugging Workflow¶

# 1. Validate to see all errors
dft validate dashboards/sales.yml

# 2. Compile to see normalized structure
dft compile dashboards/sales.yml --format yaml > sales_normalized.yml

# 3. Compare original and normalized versions
diff dashboards/sales.yml sales_normalized.yml

# 4. Serve to test interactively
dft serve dashboards/sales.yml

Exit Codes¶

All commands follow standard Unix exit codes:

0: Success
1: Error (validation failed, compilation error, etc.)

This makes the CLI suitable for use in scripts and CI/CD pipelines:

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

Environment Variables¶

Dataface respects dbt environment variables:

DBT_PROFILES_DIR: Custom profiles directory (default: ~/.dbt)
DBT_PROJECT_DIR: Default project directory
DBT_PROFILE: Default profile name

Set these if you need custom dbt configuration:

export DBT_PROJECT_DIR=/path/to/dbt/project
dft validate dashboards/

Troubleshooting¶

Command Not Found¶

Error: dft: command not found

Solution: Ensure Dataface is installed and in your PATH:

pip install dataface
# Or if using a virtual environment:
source venv/bin/activate
pip install dataface

Dashboard File Not Found¶

Error: Error: Dashboard file not found: dashboards/sales.yml

Solution: Check the file path and ensure you're in the correct directory:

# Check if file exists
ls -la dashboards/sales.yml

# Use absolute path if needed
dft serve /absolute/path/to/dashboards/sales.yml

Port Already in Use¶

Error: Error: Port 8080 is already in use

Solution: Use a different port:

dft serve dashboards/sales.yml --port 3000

dbt Project Not Found¶

Error: Error: dbt project not found

Solution: Specify the project directory:

dft validate --project-dir /path/to/dbt/project

Getting Started¶

Installation Guide - Installation and setup
Getting Started Guide - Creating your first dashboard
YAML Style Guide - Best practices for writing dashboard YAML

Troubleshooting & Best Practices¶

Troubleshooting Guide - Common issues and solutions (includes CLI troubleshooting)
Best Practices Guide - Dashboard design best practices

Advanced Features¶

Data Diagnostics Guide - Using dft diagnose to profile data

CLI Reference¶

Overview¶

Getting Help¶

Version¶

Commands¶

`validate`¶

`compile`¶

`serve`¶

`render`¶

`build`¶

`playground`¶

Common Options¶

`--project-dir`¶

Workflow Examples¶

Development Workflow¶

CI/CD Pipeline¶

Debugging Workflow¶

Exit Codes¶

Environment Variables¶

Troubleshooting¶

Command Not Found¶

Dashboard File Not Found¶

Port Already in Use¶

dbt Project Not Found¶

Getting Started¶

Troubleshooting & Best Practices¶

Advanced Features¶

See Also¶

Core Concepts¶

Reference Documentation¶

CLI Reference¶

Overview¶

Getting Help¶

Version¶

Commands¶

validate¶

compile¶

serve¶

render¶

build¶

playground¶

Common Options¶

--project-dir¶

Workflow Examples¶

Development Workflow¶

CI/CD Pipeline¶

Debugging Workflow¶

Exit Codes¶

Environment Variables¶

Troubleshooting¶

Command Not Found¶

Dashboard File Not Found¶

Port Already in Use¶

dbt Project Not Found¶

Related Documentation¶

Getting Started¶

Troubleshooting & Best Practices¶

Advanced Features¶

See Also¶

Core Concepts¶

Reference Documentation¶

`validate`¶

`compile`¶

`serve`¶

`render`¶

`build`¶

`playground`¶

`--project-dir`¶