Skip to content

dft serve

Start the local Dataface server. Serves inspect templates and any face files via URL paths — 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. port: field in dataface.yml
  4. Deterministic hash of the project directory

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

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.

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

URL routing

Path Renders
/ Index of available faces
/<face-name>/ The face at faces/<face-name>.yml
/<face-name>/?region=West Same face with region variable set
/inspect/... Inspector templates over your warehouse

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.