Skip to content

tycoon.yml reference

Every key in the project's config file, with defaults and worked examples.

Minimal example

name: my-project
version: 0.1.0
database:
  raw: data/raw.duckdb
  warehouse: data/warehouse.duckdb
sources: {}

Anything not declared falls back to the defaults below.

Top-level keys

Key Type Default Notes
name string my-project Used in dlt pipeline names
version string 0.1.0 Project's own version, free-form
schema_version int unset Managed by tycoon — see schema_version below. Don't edit by hand.
database block see below Where data lives
sources map[name → source] {} Registered ingestion sources
dbt_project_dir string dbt_project Path to dbt project root
dbt_profiles_dir string unset Override the profiles.yml directory. See dbt profiles below.
dbt_profile string unset Profile name within profiles.yml. Defaults to the profile: field in dbt_project.yml.
dbt_target string unset Target within the profile (dev / prod / ...). Defaults to the profile's own target:, then dev.
rill_dir string rill Path to Rill project dir
sync block unset tycoon data sync defaults
stack block see below Tool-by-tool stack toggle

schema_version

schema_version: 2

An integer marking which revision of the tycoon.yml format the file was written against. Tycoon manages this field — tycoon init stamps it on new projects, and tycoon init --upgrade advances it when migrating an older file. You never need to set or edit it.

Not to be confused with version, which is yours: a free-form label for your project that tycoon never touches.

version schema_version
Owned by you tycoon
Type free-form string integer
Meaning your project's version the tycoon.yml format revision

Files without schema_version (or with an older one) still load — data commands print a warning pointing at tycoon init --upgrade, which migrates the file in place while preserving comments and blank lines. A schema_version newer than the installed tycoon supports is an error: commands exit and ask you to upgrade tycoon-cli rather than risk misreading a future format.

database

database:
  raw: data/raw.duckdb              # where dlt writes
  warehouse: data/warehouse.duckdb  # where dbt writes (or md:catalog)
Key Type Default Notes
raw string data/raw.duckdb Where dlt loads source data: a local DuckDB file, or md:<name> (or motherduck:<name>) for a MotherDuck database. The MotherDuck database must exist first, and MOTHERDUCK_TOKEN must be exported.
warehouse string data/warehouse.duckdb Local file or md:<catalog> for MotherDuck.

For Snowflake / BigQuery / Redshift warehouses, the warehouse field isn't load-bearing — dbt resolves the connection from dbt_project/profiles.yml. Use stack.warehouse: snowflake (etc.) to tell tycoon what kind of warehouse it's looking at.

sources

A map keyed by source name. Each source is a block declaring its type and config:

sources:
  files:
    type: filesystem
    schema: raw_files
    config:
      bucket_url: data/input
      file_glob: "*.csv"

  github:
    type: rest_api
    schema: raw_github
    config:
      base_url: https://api.github.com
      datasets: [repos, issues, pulls]
Key Type Default Notes
type string (required) Source type: filesystem, rest_api, sql_database, or any catalog source
schema string raw_<name> Target schema name in the raw DB
config dict {} Type-specific config passed through to dlt
tables list[string] unset Optional table-name list (for sql_database and similar)
dbt_package string unset Optional dbt package to install when this source is registered

A filesystem source's path (or bucket_url) can be a directory or a single local file, given as a plain path or a file:// URL. For a directory, file_glob picks the files under it (the flat shape defaults to **/*). For a single file, leave file_glob unset: tycoon reads the file's directory and matches just that file name. Setting both a file path and a file_glob is an error.

Source types not in tycoon data sources catalog need to be installed via tycoon data sources add <type> first (it runs dlt init under the hood and stages the source files under the resolved sources dir, project-local once the project has its own .venv, otherwise the shared ~/.tycoon/sources/).

sync

Configures defaults for tycoon data sync (cloud → local snapshots). Optional.

sync:
  to: data/local_snapshot.duckdb
  mode: replace
  sources:
    - from: md:my_catalog
      schemas: ['mart']
      tables: ['dim_*', 'fct_*']
    - from: md:another_catalog
      schemas: ['*']
Key Type Default Notes
to string data/local_snapshot.duckdb Default destination DuckDB file
mode string replace replace / append / skip-existing
sources list[block] [] One block per remote source. Each carries its own filter globs.

sync.sources[]

- from: md:my_catalog
  schemas: ['mart', 'staging']
  tables: ['*']
Key Type Default Notes
from string (required) DuckDB-attachable URL: md:<catalog> for MotherDuck, /path/to/other.duckdb for a local file
schemas list[string] ["*"] fnmatch globs — which schemas to include
tables list[string] ["*"] fnmatch globs — which tables within selected schemas

stack

Tells tycoon which tools you use. Drives tycoon doctor checks, tycoon start services, and template scaffolding.

stack:
  ingestion: dlt
  ingestion_managed: true
  warehouse: duckdb               # or motherduck, snowflake, bigquery, redshift, other
  transformation: dbt
  transformation_managed: true    # tycoon scaffolds + manages this
  bi: rill                        # or metabase, looker, tableau, other, none
  bi_managed: true
Key Type Default Notes
ingestion enum dlt dlt, airbyte, fivetran, meltano, none
warehouse enum duckdb duckdb, motherduck, snowflake, bigquery, redshift, other
transformation enum dbt dbt, none
bi enum rill rill, metabase, looker, tableau, other, none
<tool>_managed bool true If true, tycoon scaffolds + maintains this tool's project. If false, tycoon just records the path and stays out of the way.

Setting any tool to none skips its scaffolding and tycoon doctor checks. Setting _managed: false is for "I have my own dbt project already, just point at it" workflows — used by tycoon register dbt and friends.

Environment variable interpolation

Any string value can reference an environment variable with ${VAR} syntax:

sources:
  github:
    type: rest_api
    schema: raw_github
    config:
      base_url: https://api.github.com
      access_token: ${GITHUB_TOKEN}

Tycoon expands these at config-load time. Unexpanded ${VAR} in any field that gets passed to dlt produces a clear warning before the API call ("Config key 'access_token' contains an unexpanded env var: ${GITHUB_TOKEN}").

dbt profiles

Tycoon resolves a dbt profile every time it shells out to dbt build / dbt test / dbt docs / dbt run. Resolution order matches dbt's own CLI so anything that works for dbt --profiles-dir foo works for tycoon ... --profiles-dir foo:

  1. CLI flag — --profiles-dir, --profile, --target on tycoon data transform run/test/build/docs and tycoon profiles list/show/doctor.
  2. tycoon.yml — dbt_profiles_dir, dbt_profile, dbt_target.
  3. <dbt_project_dir>/profiles.yml (dbt 1.5+ co-located file).
  4. $DBT_PROFILES_DIR env var.
  5. ~/.dbt/profiles.yml (dbt's default).

You generally don't need to touch any of the tycoon.yml fields — co-located + ~/.dbt covers most setups. Set dbt_profiles_dir only when your profile lives somewhere unusual (e.g. you keep it under version control in a separate config/ directory).

Inspect what tycoon will use:

tycoon profiles list      # every profile + targets + adapters; flags the active one
tycoon profiles show      # pretty-print the active profile, secrets redacted
tycoon profiles doctor    # verify resolution + adapter matches stack.warehouse

tycoon doctor includes the profiles doctor check too, so you'll catch a duckdb-vs-snowflake adapter mismatch before a dbt build does.

transform

transform:
  auto_scaffold: true             # default
  auto_osi_scaffold: false        # default — opt in once you're happy with OSI scaffolds
Key Type Default Notes
auto_scaffold bool true After tycoon data sources run <name>, automatically run tycoon data analyze if no staging models exist for that source yet.
auto_osi_scaffold bool false After a successful tycoon data transform run/build, auto-emit dbt_project/semantic/osi.yaml via tycoon semantics scaffold. Best-effort — never breaks the underlying transform on failure. See the tycoon semantics docs.

Things that aren't in tycoon.yml

  • Secrets — keep them in .env or your shell environment, then reference via ${VAR} interpolation. Tycoon never asks you to put raw tokens in tycoon.yml.
  • Per-machine paths — anything that varies between dev machines belongs outside the file. The defaults assume ./data, ./dbt_project, ./rill relative to the project root, which works on every machine.
  • Run history — that lives in .tycoon/metadata.duckdb (auto-gitignored in scaffolded projects).