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¶
Or the full interactive wizard:
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:
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 pipelinenyc-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:
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:
The name shows up in:
tycoon.yml'sname: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 init --upgrade is that migration:
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:
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.
Related¶
- Reference: tycoon.yml — full schema of what
initwrites tycoon register— attach existing dbt / Rill / warehouse to a project