Skip to content

tycoon init

Scaffold a new tycoon project from a built-in template.

Synopsis

tycoon init [OPTIONS]

Options:
  -t, --template TEXT      Template name to scaffold from
  -n, --name TEXT          Project name (default: current directory name)
  --list-templates         List available templates and exit
  -p, --param TEXT         Template parameter in 'name=value' form (repeatable)
  --upgrade                Migrate tycoon.yml to the current schema version and exit
  --no-venv                Scaffold without building the project's own .venv
  -h, --help               Show this message and exit

Quick start

mkdir my-project && cd my-project
tycoon init --template csv-import --name my-project

Or the full interactive wizard:

tycoon init

The wizard asks about each component (ingestion, warehouse, dbt, Rill) with sensible defaults. Pick none for any component you don't use.

What gets created

In the current directory:

my-project/
├── tycoon.yml              # the config you'll touch most
├── data/                   # DuckDB files + parquet exports
├── dbt_project/            # dbt models (if scaffolded)
├── rill/                   # Rill dashboards (if scaffolded)
├── pyproject.toml          # declares tycoon + its dbt/dlt/duckdb stack
├── uv.lock                 # pins the exact resolved versions
├── .python-version         # pins the interpreter
├── .venv/                  # the project's own isolated environment
└── .gitignore

Right after scaffolding, init builds the project's own .venv via tycoon setup's underlying flow: a pyproject.toml declaring database-tycoon, synced with uv sync. This is what makes a freshly added source actually runnable on the first try, its dependencies install into this environment, not wherever tycoon happens to be running.

If the directory already has its own pyproject.toml, .python-version, or .venv, this step is skipped entirely, with a message naming which one, so init never rewrites an existing Python project's environment. Run tycoon setup yourself if you want tycoon to manage it anyway.

Pass --no-venv to skip this step unconditionally and scaffold without an environment:

tycoon init --template csv-import --no-venv

The exact tree depends on the template. See Reference: Templates for what each template ships.

Templates

tycoon init --list-templates shows them. The two featured built-in:

  • csv-import — fully offline, smoke-test the full pipeline
  • nyc-transit — live ingestion from NYC public APIs

See Reference: Templates for the full list.

Template parameters

Some templates declare parameters in their template.yml. Pass them with --param:

tycoon init --template <name> --param key=value --param other=value

If you omit a parameter the template requires, init prompts interactively.

Placeholders use {{ name }} / {{ owner }} syntax in any .yml, .yaml, .sql, .md, or .txt file the template ships. dbt's own {{ ref(...) }} Jinja passes through untouched.

Picking a project name

The default is the current directory name. Override with --name:

tycoon init --template csv-import --name my-analytics

The name shows up in:

  • tycoon.yml's name: field
  • dlt pipeline names (my-analytics-files-pipeline)

After init

tycoon doctor                        # health check
tycoon data sources run files        # ingest first source
tycoon data transform run            # run dbt
tycoon data analyze files --rill     # generate dashboards
tycoon start --only rill             # serve dashboards

See Your first project for a 10-minute walkthrough.

Upgrading an existing project: --upgrade

When tycoon's tycoon.yml schema gains new fields, existing projects keep working — but commands will warn:

tycoon.yml is at schema version 1, current is 2. Run 'tycoon init --upgrade' to migrate.

tycoon init --upgrade is that migration:

cd my-project
tycoon init --upgrade

It edits tycoon.yml in place — adding any missing blocks with their defaults (currently metadata:) and stamping schema_version to the current value. Your comments, blank lines, and the project's own version: field are left untouched. It is idempotent: run it twice and the second run reports the file is already up to date and writes nothing.

If tycoon.yml declares a schema_version newer than the installed tycoon supports, --upgrade (and any data command) exits with an error asking you to upgrade tycoon-cli instead — it never downgrades a file.

Re-running init

tycoon init refuses to overwrite an existing tycoon.yml. To reset a project:

rm -rf my-project && mkdir my-project && cd my-project
tycoon init --template csv-import

Adding components you skipped

If you picked "Skip" on the dbt or Rill prompts during the wizard, you can add them later non-destructively without re-running init:

tycoon register dbt --create     # bootstrap a sibling dbt project
tycoon register rill ./rill      # or register an existing one

See tycoon register for the full --create behavior.