> ## Documentation Index > Fetch the complete documentation index at: https://schemabrain.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Developer commands > Lower-traffic CLI surfaces — eval, mine-queries, fixture-path, and import. Useful for CI, retrieval quality measurement, and dbt onboarding. # Developer commands Four lower-traffic subcommands that don't share a daily-use story but earn their place: * [`schemabrain eval`](#eval) — score the retriever against a golden set. * [`schemabrain mine-queries`](#mine-queries) — harvest observed SQL from `pg_stat_statements`. * [`schemabrain fixture-path`](#fixture-path) — print the absolute path to a bundled fixture. * [`schemabrain import dbt`](#import-dbt) — import semantic definitions from a dbt manifest. *** ## eval Score a retriever implementation against a golden set; prints recall\@1 / @3 / @10. ```bash theme={null} schemabrain eval --url-env DATABASE_URL --store-path ./schemabrain.db ``` | Flag | Default | Purpose | | --------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | | `--source URL` | (none) | Source URL — used to resolve which tables in the store to score against. Deprecated when the URL contains a password. | | `--url-env VARNAME` | (none) | Env var holding the source URL. Preferred. | | `--store-path PATH` | `./schemabrain.db` | Path to the local SQLite store. | | `--golden PATH` | Bundled e-commerce starter set | Path to a golden-set JSON file. For your own schema, author a matching JSON. | | `--retriever {embedding,keyword}` | `embedding` | `embedding` uses stored column embeddings + cosine (requires `index` without `--no-embed`). `keyword` uses the keyword-overlap baseline. | | `--limit N` | (built-in default) | Top-K cap passed to the retriever. | ### Authoring a golden set Each row in the JSON file is a `{query, expected_table}` pair. The eval prints how often the retriever's top-K results contained the expected table: * **recall\@1** — was it the top result? * **recall\@3** — was it in the top 3? * **recall\@10** — was it in the top 10? For onboarding a new schema, run `eval` against the bundled starter, then write a domain-specific golden set targeting your real questions. *** ## mine-queries Harvest observed SQL from `pg_stat_statements` into the local store. Populates the `get_example_queries` MCP tool's response. ```bash theme={null} schemabrain mine-queries --url-env DATABASE_URL --store-path ./schemabrain.db ``` | Flag | Default | Purpose | | ------------------- | ------------------ | -------------------------------------------------------- | | `--source URL` | (none) | Source URL. Deprecated when the URL contains a password. | | `--url-env VARNAME` | (none) | Env var holding the source URL. Preferred. | | `--store-path PATH` | `./schemabrain.db` | Path to the local SQLite store. | ### Prerequisites Requires the `pg_stat_statements` extension on the source database: ```sql theme={null} -- One-time, as a superuser, in postgresql.conf: -- shared_preload_libraries = 'pg_stat_statements' -- Then restart Postgres, then: CREATE EXTENSION pg_stat_statements; ``` The mining role needs read access to the `pg_stat_statements` view (superusers always have it; non-super roles need `pg_read_all_stats`). If the extension or grant is missing, `mine-queries` exits cleanly with an actionable message — no row is written, the store stays intact, and `get_example_queries` keeps returning `status: empty` with a recovery hint pointing to [Manual flow — Mine observed queries](/setup/manual#2-optional-mine-observed-queries). The `joins suggest` command also reads `pg_stat_statements` evidence — running `mine-queries` first improves canonical-join ranking. *** ## fixture-path Print the absolute path to a bundled fixture. Paste-clean for shell substitution. ```bash theme={null} schemabrain fixture-path ecommerce.sql # /abs/path/to/site-packages/schemabrain/fixtures/ecommerce.sql psql -f "$(schemabrain fixture-path ecommerce.sql)" "$DATABASE_URL" ``` | Argument | Purpose | | ------------------- | ------------------------------------------------------------------------------------------------------ | | `name` (positional) | Bundled fixture basename, e.g. `ecommerce.sql` (SQL seed) or `ecommerce.json` (golden set for `eval`). | Useful for: * Seeding a demo Postgres against the bundled e-commerce schema. * Loading the starter golden set into a custom `eval` driver. * CI smoke tests that operate against a known shape. *** ## import dbt Import entities (and optionally metrics) from a dbt `manifest.json`. Read-only against dbt — no export path. ```bash theme={null} schemabrain import dbt /path/to/dbt/target/manifest.json --url-env DATABASE_URL ``` | Argument / Flag | Default | Purpose | | ---------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `manifest_path` (positional) | (required) | Path to your dbt project's compiled `target/manifest.json`. Run `dbt compile` to produce it. Remote (dbt Cloud) manifests aren't supported — download locally and pass the path. | | `--source URL` | (none) | Source URL. Deprecated when the URL contains a password. | | `--url-env VARNAME` | (none) | Env var holding the source URL. Preferred. | | `--store-path PATH` | `./schemabrain.db` | Path to the local SQLite store. | | `--dry-run` | (off) | Compute the plan (added / updated / ownership-transferred / skipped / orphans) and print the summary, but write nothing. Best mode for CI previews. | | `--report PATH` | (none) | Optional. Writes a JSON report of the plan (bucket counts + per-model details) to this path. Works with both dry-run and apply. | | `--include-metrics` | (off) | Also import dbt metrics (type=`simple` only) anchored on the entities imported in this run. Skips ratio / derived / cumulative metrics with structured reasons. Off by default to preserve backwards-compatible behaviour from earlier releases; on by default in a future release. | ### dbt-driven curation via `init` `schemabrain init` auto-detects a dbt manifest from `$DBT_PROJECT_DIR` (or by walking up from cwd for `dbt_project.yml`) and routes the entity + metric curation stages through this importer instead of the LLM. See [`schemabrain init`](/reference/cli/init). *** ## Related Index first, then `eval` / `mine-queries`. Consumes `mine-queries` output for canonical-join ranking. The agent-facing surface `mine-queries` populates. Auto-detects dbt and routes curation through this importer.