`dft render`¶

Render a dashboard to SVG, HTML, PNG, PDF, JSON, YAML, or terminal output.

dft render [OPTIONS] FACE

Use "-" as the FACE argument to read YAML from stdin — useful for AI agents and shell pipelines that don't want to write a temp file.

Arguments¶

Argument	Description
`FACE`	Path to face YAML file, or `"-"` to read YAML from stdin. (required)

Options¶

Flag	Description
`--output PATH`	Output file path. Default: face name with extension. Use `"-"` to write to stdout.
`--format TEXT`	Output format: `svg`, `html`, `png`, `pdf`, `terminal`, `json`, `text`, `yaml`. Default: `svg`.
`--project-dir PATH`	Project directory for resolving relative paths.
`--var KEY=VALUE`	Variable value (repeatable).
`--no-cache`	Bypass all query caches and re-run from scratch.
`--cache PATH`	Persist the query cache to this DuckDB file (created if absent). Default: in-memory, discarded when the process exits. Also settable via `DFT_CACHE_PATH`. Mutually exclusive with `--no-cache`.
`--json-errors`	Emit errors as JSON to stdout instead of Rich panels. Success-path output is still controlled by `--format`.

Output formats¶

Format	Purpose
`svg` (default)	Scalable vector graphics — embedding, presentations
`html`	Interactive HTML page with embedded charts
`png`	Raster image — screenshots, thumbnails
`pdf`	PDF document — reports, printing
`terminal`	ASCII/Unicode charts printed to stdout
`json`	Post-execution resolved layout + data
`text`	Plain text rendering
`yaml`	Compiled face YAML

Examples¶

Static export¶

dft render faces/sales.yml                         # → faces/sales.svg
dft render faces/sales.yml --format html
dft render faces/sales.yml --format png
dft render faces/sales.yml --format pdf
dft render faces/sales.yml --output sales.svg

Variables¶

dft render faces/sales.yml \
  --var region=West \
  --var category=Electronics

Terminal preview¶

dft render faces/sales.yml --format terminal

================================================================================
 Sales Dashboard
================================================================================

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

Terminal format writes directly to stdout. Use shell redirection to save:

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

Reading YAML from stdin¶

dft render - --format terminal --project-dir . <<'EOF'
charts:
  revenue:
    query:
      type: csv
      file: data/sales.csv
    type: bar
    x: region
    y: revenue
rows:
  - revenue
EOF

echo 'charts: {c: {query: {type: csv, file: data.csv}}}
rows: [c]' | dft render - --format terminal

cat generated_dashboard.yml | dft render - --output - > output.svg

--project-dir controls where relative file paths (CSVs, etc.) are resolved from when reading stdin. Defaults to cwd.

CI artifact generation¶

for face in faces/*.yml; do
  dft render "$face" \
    --format html \
    --output "dist/$(basename "$face" .yml).html"
done

Inspect resolved layout for debugging¶

dft render faces/sales.yml --format json > sales_resolved.json

Origin-absolute links in exports¶

By default, links inside rendered HTML and SVG files are root-relative (/org/proj/d/slug/). That works when the file is served from the same host, but breaks when it is opened as a standalone file (file://) or embedded cross-origin.

Set public_url in your dataface.yml to make export links fully-qualified:

public_url: "https://dashboards.example.com"

With that setting, dft render produces https://dashboards.example.com/d/slug/ instead of /d/slug/. Leave it unset (the default, empty string) for local use.

Caching¶

The query-result cache is in-memory by default — it lives only for the duration of the dft render process and is discarded when it exits. Pass --no-cache to skip caching entirely and force re-execution from scratch.

To persist the cache across separate dft render invocations (e.g. a script that regenerates dashboards repeatedly), pass --cache <path>:

dft render faces/sales.yml --cache cache.duckdb
dft render faces/sales.yml --cache cache.duckdb   # reuses cached query results

The file is created automatically if it doesn't exist yet. --cache also reads from the DFT_CACHE_PATH environment variable, so a script can export DFT_CACHE_PATH=cache.duckdb once instead of repeating the flag. A persistent cache file supports only one writer at a time — don't point two concurrently running dft render/dft serve processes at the same file. --cache and --no-cache are mutually exclusive.

Error output¶

For programmatic consumers (agents, CI), --json-errors emits machine-readable errors to stdout instead of formatted Rich panels:

dft render faces/sales.yml --json-errors --format svg

The success-path output (the SVG, HTML, etc.) is still controlled by --format; only error paths change shape.

dft serve — interactive preview with auto-reload
dft validate — fast pre-render validation
dft query — inspect one named query without rendering the whole face

dft render¶