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

Command	Description
tycoon init	Scaffold a new project
tycoon data sources catalog	Browse available source integrations
tycoon data sources add <type>	Register a new data source
tycoon data sources list	List sources configured in this project
tycoon data sources list show <name>	Show detailed config for a source
tycoon data sources run <name>	Run ingestion for a named source
tycoon data sources run-all	Run ingestion for all sources
tycoon data transform run	Run dbt transformations
tycoon data analyze <source>	Scaffold dbt staging models; add --rill to also generate dashboards
tycoon data db query <sql>	Run a SQL query against the warehouse
tycoon data run-all	Ingest all sources then run dbt build
tycoon data status	Show freshness, row counts, and capture counts for each source
tycoon data history	List recent dlt + dbt runs from the observability metadata DB
tycoon data history show <id>	Per-run detail (per-table rows for dlt, per-node status for dbt)
tycoon start	Start the Rill dashboards and the Quack warehouse server
tycoon stop	Stop all services
tycoon run <tool>	Passthrough to dbt, dlt, rill

---

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.

Source	Category	Key Tables
github	Developer	commits, issues, pull_requests, repositories
slack	Communication	channels, messages, users
stripe	Finance	customers, invoices, products, subscriptions
hubspot	CRM	companies, contacts, deals, tickets
notion	Knowledge	databases, pages, users

---

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.