reading-project-state

Files (1)

• SKILL.md

SKILL.md (first lines)

# Reading project state

## For humans (Rich tables, not parseable)

| Command | Shows |
|---|---|
| `tycoon data status` | Layered view: Sources → Staging → Intermediate → Marts, with freshness |
| `tycoon data history [-t dlt\|dbt] [-n N] [-s SOURCE]` | Recent runs (default 20) |
| `tycoon data history show <RUN_ID>` | One run: status, duration, error, per-table row counts (short id prefix OK) |
| `tycoon data schema` | Tables, row counts, file sizes across raw + warehouse (no arguments) |

Marts panels appear only after a dbt manifest exists (run dbt at least once).

## For scripts (machine-readable)

**There is no `--json` flag anywhere.** The programmatic surface is the
observability database at `.tycoon/metadata.duckdb`, queried through tycoon
(which handles locks):

```bash
tycoon data query --db .tycoon/metadata.duckdb \
  "SELECT r.source_schema, r.load_id, r.status, r.inserted_at,
          sum(t.rows_loaded) AS rows_loaded
   FROM dlt_runs r LEFT JOIN dlt_rows_by_table t USING (source_schema, load_id)
   GROUP BY r.source_schema, r.load_id, r.status, r.inserted_at
   ORDER BY r.inserted_at DESC LIMIT 20"
```

Tables: `dlt_runs`, `dlt_rows_by_table`, `dbt_runs`, `dbt_nodes`,
`dbt_manifest_snapshots`, `dbt_schema_changes`, `fivetran_connectors`.
Discover columns with `DESCRIBE <table>`.

`tycoon data query` also reaches the other databases:

```bash
tycoon data query "SELECT count(*) FROM marts.my_table"   # warehouse
tycoon data query --raw "SELECT * FROM raw_pokeapi.pokemon LIMIT 5"
tycoon data query -s pokeapi "SHOW TABLES"                # one source's schema
```

A local DuckDB file opens read-only. A MotherDuck connection does not: it is
read-write, and the token's scope decides what it may change, so treat
`tycoon data query` against `md:` as able to write. Warehouse queries route
through Quack automatically while `tycoon start` is running, so they work even
when the local file is locked.

## Modeling state inside dbt

`tycoon data observability scaffold` generates `models/_tycoon/` staging
models over the metadata DB and ATTACHes it as `tycoon_meta` in profiles.yml.
Use this when dashboards should show pipeline health.

## Cleanup gotcha

`tycoon data clean --all` deletes the raw and warehouse files but
**preserves** `.tycoon/metadata.duckdb` (run history) unless `--metadata` is
passed too.

From Database-Tycoon/tycoon-cli, MIT.

More from Database-Tycoon/tycoon-cli