Configuration

FDL uses a 3-layer configuration system, following the same approach as git config. Settings are managed at the project, workspace, and user level.

Config Layers

Layer	File	Scope	Git tracked
Project	fdl.toml	Team-shared settings	Yes
Workspace	.fdl/config	Local environment overrides	No
User	~/.fdl/config	Personal global settings	No

Resolution order (highest priority first):

1. Environment variables (FDL_*)
2. Workspace (.fdl/config)
3. User (~/.fdl/config)
4. Project (fdl.toml)

Note

If XDG_CONFIG_HOME is set, the user config is located at $XDG_CONFIG_HOME/fdl/config.

fdl.toml

Located at the project root and tracked in Git. Auto-generated by fdl init.

name = "my-dataset"

[remotes]
origin = "s3://my-bucket"

Key	Description
name	Datasource name
catalog	Catalog format (only when sqlite is specified)
remotes.<name>	Named Remote URL or path

.fdl/config

Workspace-local config inside the .fdl/ directory, excluded by .gitignore.

[remotes]
local = "/tmp/fdl-storage"

[storage]
public_url = "https://data.example.com"

Write with fdl config --local:

fdl config --local remotes.local /tmp/fdl-storage
fdl config --local storage.public_url https://data.example.com

~/.fdl/config

User-global config. Store settings shared across projects, such as S3 credentials.

[storage]
public_url = "https://data.queria.io"

[s3]
endpoint = "https://abc123.r2.cloudflarestorage.com"
access_key_id = "your-access-key"
secret_access_key = "your-secret-key"

Write with fdl config (no flags):

fdl config s3.endpoint https://abc123.r2.cloudflarestorage.com
fdl config s3.access_key_id your-access-key
fdl config s3.secret_access_key your-secret-key

Named Remotes

Push/pull targets must be specified as Named Remotes. Direct URLs or paths are not accepted.

# Good: use a Named Remote
fdl push origin

# Bad: direct URL → error
fdl push s3://my-bucket

Remotes can be defined in any of the 3 layers. When the same name exists in multiple layers, the higher-priority layer wins:

# Team-shared (fdl.toml)
fdl config --local remotes.origin s3://team-bucket

# Personal (～/.fdl/config)
fdl config remotes.staging s3://staging-bucket

Environment variable expansion is supported inside remote URLs:

[remotes]
origin = "s3://$BUCKET_NAME"

Environment Variables

Environment variables take the highest priority over all config layers. Designed for CI/CD environments.

Storage

Variable	Description	Config key
FDL_PUBLIC_URL	Public base URL for datasets	storage.public_url
FDL_STORAGE	Base storage path	—
FDL_DATA_PATH	Data files path	—
FDL_ATTACH_PATH	DuckLake attach path	—

S3

Variable	Description	Config key
FDL_S3_ENDPOINT	S3 endpoint URL	s3.endpoint
FDL_S3_ACCESS_KEY_ID	S3 access key	s3.access_key_id
FDL_S3_SECRET_ACCESS_KEY	S3 secret key	s3.secret_access_key
FDL_S3_ENDPOINT_HOST	S3 endpoint without scheme (auto-derived)	—

FDL_S3_ENDPOINT_HOST is derived from FDL_S3_ENDPOINT by stripping the https:// prefix. Used for DuckDB's s3_endpoint setting.

Automatic Injection with fdl run

fdl run automatically injects the above variables into the subprocess. Existing environment variables are never overwritten.

# These are equivalent:
fdl run -- dbt run

# Manual setup:
FDL_STORAGE=.fdl FDL_DATA_PATH=.fdl/ducklake.duckdb.files \
  FDL_ATTACH_PATH=ducklake:.fdl/ducklake.duckdb \
  dbt run