tycoon

A pip-installable CLI that wires dlt → DuckDB → dbt → Rill into a working local analytics stack. No Docker, no cloud account required.

Adaptable: bring your own ingestion (Airbyte, Fivetran), warehouse (Snowflake, BigQuery, MotherDuck), dbt project, or BI tool — tycoon init asks before it assumes.

Install

Requires Python >= 3.12.

pip install database-tycoon
# or
uv add database-tycoon

Quickstart

Offline (no signup, runs in CI on every PR)

The csv-import template ships with a sample CSV and a working dbt project, so the full ingest → transform pipeline runs without any external network call. This is the block our CI gate runs against every commit — if it ever breaks, the release is blocked.

tycoon init --template csv-import --name analytics-demo
tycoon data sources run files
tycoon data analyze files
tycoon data transform run

Live API (uses the PokéAPI)

A live walkthrough that hits a real public API — no credentials, no signup. Uses the non-interactive --no-prompt flag so the whole arc is scriptable; drop the flag and the equivalent --base-url / --resources flags if you'd rather walk through the interactive prompts.

tycoon init --template csv-import --name pokeapi-demo
tycoon data sources add rest_api \
  --base-url https://pokeapi.co/api/v2/ \
  --resources pokemon,berry,type \
  --no-prompt
tycoon data sources run pokeapi
tycoon data analyze pokeapi
tycoon data transform run --select 'stg_pokeapi__*'

The --rill switch on data analyze (and tycoon start --only rill) opens a Rill dashboard at http://localhost:9009 with pokemon, berry, and type tables ready to explore.

Already have a pipeline? tycoon init will ask about your ingestion tool, warehouse, dbt project, and BI tool — and configure itself around what you already have.

CLI Reference

tycoon.yml Reference

name: my-project
version: 0.1.0

database:
  raw: data/raw.duckdb              # dlt output (or md: URI for MotherDuck)
  warehouse: data/warehouse.duckdb  # dbt output — read by Rill

dbt_project_dir: dbt_project   # path to dbt project (yours or tycoon-scaffolded)
rill_dir: rill                 # path to Rill dashboard definitions

stack:                         # generated by tycoon init — edit as needed
  ingestion: dlt               # dlt | airbyte | fivetran | meltano | none
  ingestion_managed: true      # false = tycoon won't run `data sources run`
  warehouse: duckdb            # duckdb | motherduck | snowflake | bigquery | other
  transformation_managed: true # false = tycoon won't scaffold or overwrite dbt
  bi: rill                     # rill | metabase | looker | tableau | other | none
  bi_managed: true             # false = tycoon won't start Rill

sources:
  my-github:
    type: github               # matches a catalog source name
    schema: raw_github         # schema name in the raw DuckDB file
    config:
      access_token: ${GITHUB_TOKEN}   # env vars are interpolated
      owner: my-org
      repo: my-repo

Each source produces its own raw DuckDB file: data/raw_<source>.duckdb. All sources write into data/warehouse.duckdb after transformation.

MotherDuck authentication

tycoon doctor recognizes two MotherDuck auth modes for a stack.warehouse: motherduck project:

• MOTHERDUCK_TOKEN env var — use this for CI, Tower, or any non-interactive path. Get one at app.motherduck.com/token.
• Cached OAuth session — run duckdb -c "ATTACH 'md:'" once locally to authenticate via browser; DuckDB caches the token under ~/.duckdb/ and tycoon picks it up from there.

Catalog Sources

These sources are available via tycoon data sources add <name>. They are downloaded on demand via dlt init and not bundled in the package.

Data Directory

Raw DuckDB files follow the naming convention raw_<source>.duckdb (written by ingestion) while warehouse.duckdb is the single transformed database read by Rill. See data/README.md for details.

Rill Dashboards

Rill is a local-first BI tool. Dashboard definitions are YAML files in the rill/ directory. Launch Rill via tycoon start or tycoon start --only rill.

Auto-generate dashboards for a source after ingestion:

tycoon data analyze my-source --rill

This exports each raw table to Parquet, then generates Rill source, metrics view, and explore files — one dashboard per table. The --rill flag is opt-in; dashboard generation is skipped by default since it requires a Rill project directory (rill/) to already exist.

Architecture: sources read from Parquet via Rill's local_file connector into its built-in in-memory OLAP. Dashboards are immediately usable without a dbt run.

Observability (dlt + dbt run history)

Every tycoon data sources run mirrors dlt's load history into .tycoon/metadata.duckdb. Every tycoon data transform run/test/build parses target/run_results.json and records one row per invocation plus one per model/test. Both captures are best-effort — they never break the underlying command.

Peek at history from the terminal:

tycoon data history                  # last 20 runs across dlt + dbt
tycoon data history --tool dbt -n 50 # dbt-only, last 50
tycoon data history show deadbeef    # drill into a specific run (short prefix OK)

Or open the two Rill dashboards (_tycoon_dlt_usage, _tycoon_dbt_usage) that auto-appear alongside your per-source explores — success rate, duration, rows loaded, models built, tests passed/failed, all filterable by schema, table, command, and dbt version.

Query the metadata DB directly for anything the dashboards don't cover:

tycoon data query --db .tycoon/metadata.duckdb \
  "SELECT invocation_id, command, elapsed_s, success
   FROM dbt_runs ORDER BY started_at DESC LIMIT 10"

The metadata DB is disposable — delete .tycoon/metadata.duckdb to reset history.

Contributing

tycoon is open source and still early, which means feedback right now has an outsized effect on where it goes. However you want to jump in:

• Hit a bug or want a feature? Open an issue — there's a short form for each.
• Got a question, or want to show what you're building? Start a discussion. Nothing's too small.
• Want to work on the code? CONTRIBUTING.md covers dev setup, what CI expects, and the repo conventions.

Everyone taking part is expected to follow our Code of Conduct.