Skip to content

dft serve

Start the local dashboard server. Renders your dashboards in the browser — face file paths map to URLs (faces/sales.yml → /sales/). Query parameters become variables.

dft serve [OPTIONS]

How it finds your project

dft serve auto-discovers the project root by walking up from the current directory looking for dataface.yml or dbt_project.yml. When a dbt project is found, the SQL dialect is inferred from the active profile target.

How it picks a port

Resolution order:

  1. --port flag
  2. DFT_PORT env var
  3. server.port in dataface.yml
  4. Deterministic hash of the project directory

If the chosen port is occupied, the next available port is used automatically.

Server config

Serve-only project settings live under server: in dataface.yml.

server:
  port: 3000
  nav: true
  debug: true

Set server.nav: false to hide the Dataface nav bar. Set server.debug: false to disable Starlette's debug pages.

Options

Flag Description
--port INT Port number. Auto-resolved if not set.
--host TEXT Host address. Default: localhost.
--project-dir PATH Project directory for resolving face file paths.
--connection TEXT Database connection string.
--dialect TEXT SQL dialect (auto-detected from dbt, or duckdb).
--target TEXT dbt target name. Default: DBT_TARGET env, then profile default.
--no-cache Skip the query-result cache entirely (every request re-runs queries).
--cache PATH Persist the query cache to this DuckDB file (created if absent). Default: in-memory, discarded when the server exits. Also settable via DFT_CACHE_PATH. Mutually exclusive with --no-cache.

Examples

# Start with auto-detected project + port
dft serve

# Pin a port
dft serve --port 3000

# Bind on all interfaces (e.g. for Docker)
dft serve --host 0.0.0.0

# Point at a DuckDB file directly, no dbt project required
dft serve --connection ./data.db --dialect duckdb

# Use the `prod` dbt target
dft serve --target prod

# Persist the query cache across restarts
dft serve --cache cache.duckdb

Caching

The query-result cache is in-memory by default — it lives only for the duration of the server process and is discarded when it exits. This means two dft serve processes on the same project can run side by side without conflict; each gets its own cache.

To persist the cache across server restarts, pass --cache <path>:

dft serve --cache cache.duckdb

The file is created automatically if it doesn't exist yet. --cache also reads from the DFT_CACHE_PATH environment variable. A persistent cache file supports only one writer at a time (DuckDB's single-writer limit) — don't point two concurrently running servers at the same file; a second server will fail to start with a lock error. Pass --no-cache to skip the cache entirely. --cache and --no-cache are mutually exclusive.

URL routing

Path Renders
/ faces/index.yml if present, otherwise a listing of available faces
/<face-name>/ The face at faces/<face-name>.yml
/<folder>/ faces/<folder>/index.yml if present, otherwise a listing of the folder
/<face-name>/?region=West Same face with region variable set

When to use what

If you want… Use
Live, interactive previews while editing YAML dft serve
Static export (SVG, HTML, PNG, PDF) dft render
Interactive YAML editor + AI Copilot dft playground

Stopping the server

Press CTRL+C in the terminal.