CLI Reference¶

Complete reference for the face command-line interface.

Overview¶

The face 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:

face --help
face validate --help
face compile --help
face serve --help

Version¶

Check your Dataface version:

face --version

Commands¶

`validate`¶

Validate dashboard YAML files for errors and warnings.

Usage:

face 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
face validate

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

# Validate all dashboards in a directory
face validate dashboards/

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

# Validate with custom project directory
face 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:

face 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)
face compile dashboards/sales.yml

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

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

# Compile with custom project directory
face 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:

face 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)
face serve dashboards/sales.yml

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

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

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

# Combine options
face 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:

face 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)
face render dashboards/sales.yml

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

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

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

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

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

# Render with custom project directory
face 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:

$ face 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:

face 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:

face 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
face build dashboards/sales.yml --mode html

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

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

# Build to custom output directory
face 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:

face playground [OPTIONS]

Planned Options:

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

Planned Examples:

# Start playground
face playground

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

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

Common Options¶

`--project-dir`¶

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

face validate --project-dir /path/to/dbt/project
face compile dashboards/sales.yml --project-dir /path/to/dbt/project
face 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
face validate dashboards/sales.yml

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

# 4. Start preview server
face 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
face validate dashboards/ --strict

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

Debugging Workflow¶

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

# 2. Compile to see normalized structure
face 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
face 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 face 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
face validate dashboards/

Troubleshooting¶

Command Not Found¶

Error: face: command not found

Solution: Ensure Dataface is installed and in your PATH:

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

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
face serve /absolute/path/to/dashboards/sales.yml

Port Already in Use¶

Error: Error: Port 8080 is already in use

Solution: Use a different port:

face serve dashboards/sales.yml --port 3000

dbt Project Not Found¶

Error: Error: dbt project not found

Solution: Specify the project directory:

face 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 face 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`¶