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, BI tool, or orchestrator — tycoon init asks before it assumes.
Requires Python >= 3.12.
pip install database-tycoon
# or
uv add database-tycoonOptional extras:
pip install "database-tycoon[dagster]" # Dagster orchestration
pip install "database-tycoon[ask]" # AI natural language queries (Ollama supported)The fastest path to a working dashboard uses the PokéAPI — no credentials, no signup.
# 1. Create a project
mkdir my-project && cd my-project
tycoon init --template csv-import
# 2. Add the PokéAPI as a source (press Enter twice for defaults)
tycoon data sources add rest_api
# 3. Ingest into DuckDB
tycoon data sources run pokeapi
# 4. Scaffold dbt models and generate Rill dashboards
tycoon data analyze pokeapi --rill
# 5. Open Rill
tycoon start --only rillRill opens 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, BI tool, and orchestrator — and configure itself around what you already have.
| 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 Rill, Dagster, Nao, and the web UI |
tycoon stop |
Stop all services |
tycoon ask chat |
Query your data in natural language (Nao) |
tycoon ask context |
Print synced table/schema context as markdown (pipe into any agent) |
tycoon run <tool> |
Passthrough to dbt, dlt, rill, dagster |
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 and Nao
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
orchestrator: dagster # dagster | airflow | prefect | other | none
orchestrator_managed: true # false = tycoon won't start Dagster
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
ask: # optional — requires tycoon[ask]
llm:
provider: ollama # fully local, no API key required
port: 5005Each source produces its own raw DuckDB file: data/raw_<source>.duckdb. All sources write into data/warehouse.duckdb after transformation.
tycoon doctor recognizes two MotherDuck auth modes for a stack.warehouse: motherduck project:
MOTHERDUCK_TOKENenv var — use this for CI, Tower, Dagster, 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.
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 |
Raw DuckDB files follow the naming convention raw_<source>.duckdb (written by ingestion) while warehouse.duckdb is the single transformed database read by Rill and Nao. See data/README.md for details.
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 --rillThis 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.
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.
Installs Dagster, dagster-dbt, and dagster-dlt. Provides a full asset graph covering ingestion and transformation. Run the Dagster UI with:
dagster devThe workspace is defined in workspace.yaml at the project root.
Installs Nao and Ibis for natural language querying of the warehouse. Requires a running LLM — Ollama (local) is supported out of the box with no API key.
tycoon ask init
tycoon ask sync
tycoon ask chattycoon ask init and tycoon ask sync also write an AGENTS.md at the project root pointing coding agents (Claude Code, Cursor, Windsurf, etc.) at the synced context tree under .tycoon/nao/. Commit AGENTS.md so it's available to anyone cloning the repo. Pipe context into any agent directly:
tycoon ask context --table dim_users | claude -p "explain this table"
tycoon ask context --schema mart # all tables in a schema
tycoon ask context --rules-only # just RULES.md
tycoon ask context # list available tables