Skip to main content

​
CLI reference

Binary: schemabrain. Global flags: --version / -V, --verbose / -v (counted: -v → INFO, -vv → DEBUG). Default log level: WARNING (stderr only).
The SchemaBrain CLI is a single binary with subcommands grouped by purpose. Every state-bearing command takes --store-path (the SQLite store) and one of --source / --url-env (the Postgres source); --url-env VARNAME is preferred over --source URL because the URL never enters argv that way. 
$ schemabrain --help
usage: schemabrain [-h] [--version] [--verbose]
                   {index,eval,serve,mine-queries,fixture-path,entities,
                    import,joins,metrics,doctor,apply,diff,init,tail,
                    audit,check,inspect,dashboard,demo} ...

​
Global flags

FlagPurpose
--version, -VPrint the installed schemabrain version and exit.
--verbose, -vIncrease logging verbosity (stderr only). -v shows INFO; -vv shows DEBUG. Default WARNING.
For serve under Claude Desktop or another host that swallows CLI flags, set SCHEMABRAIN_LOG_LEVEL=DEBUG in the host’s env block instead.

​
Subcommand catalog

​
Setup and serve

schemabrain demo

Zero-setup showcase. Sample SaaS data, the firewall, and the dashboard — no API key.

schemabrain init

Activation wizard. Index, curate, wire your MCP host in one command.

schemabrain index

Reflect a Postgres schema into the local SQLite store.

schemabrain serve

Run the MCP server on stdio against the indexed store.

schemabrain dashboard

Boot the local read-only dashboard UI on 127.0.0.1.

​
Semantic-layer curation

schemabrain entities

list, apply, suggest, export, export-all.

schemabrain metrics

list, apply, suggest, show, audit, export, export-all.

schemabrain joins

list, apply, suggest, export, export-all.

​
Project-level operations

schemabrain apply

Walk a project tree (entities/, metrics/, joins/) and load every YAML.

schemabrain diff

Drift check between an on-disk project tree and the store.

​
Observability and verification

schemabrain audit

list, verify — inspect and verify the hash-chained audit log.

schemabrain tail

Stream MCP tool-call events from a running serve process.

schemabrain doctor

Health-check host config, store, and (optionally) source.

schemabrain check

Detect drift between persisted definitions and the live source schema.

schemabrain inspect

Browse the indexed schema + semantic-layer surface (no source needed).

​
Developer and niche commands

schemabrain eval, mine-queries, fixture-path, import

Retrieval scoring, query log mining, fixture paths, dbt manifest import.

​
Conventions you can rely on

​
Source URLs and credentials

Every command that touches Postgres accepts both --source URL and --url-env VARNAME. The two are mutually exclusive. The env-var form is preferred because the URL — and any embedded password — never appears in argv (visible to ps, shell history, journald). The positional and --source forms emit a deprecation warning when the URL contains a password. 
# Preferred
export DATABASE_URL="postgresql+psycopg://user:pass@host:5432/dbname"
schemabrain index --url-env DATABASE_URL --store-path ./schemabrain.db

# Still works, but deprecated when URL has a password
schemabrain index --source "postgresql+psycopg://user:pass@host:5432/dbname" --store-path ./schemabrain.db
The connection scheme must be postgresql+psycopg:// (psycopg v3). A bare postgresql:// will fail with ModuleNotFoundError: No module named 'psycopg2'.

​
Store path

The local SQLite store defaults to ./schemabrain.db. Pass --store-path PATH to override. The directory is created on first write; subsequent runs are idempotent.

​
Cost caps

Every command that calls an LLM (index, entities suggest, metrics suggest, the LLM stages of init) enforces a hard USD cap. The default is conservative; override with --max-cost-usd or the per-command equivalent. Caps abort cleanly with a guided error — no partial writes.

​
Exit codes

CodeMeaning
0Success.
1Drift / mismatch / non-fatal disagreement (e.g. diff found differences).
2Operational error — bad input, missing flag, malformed config, unreachable source.
3Cost cap exceeded.
audit verify follows the same 0 / 1 / 2 convention specifically — 0 intact, 1 mismatch, 2 operational error.

​
Output streams

Human-readable output goes to stderr (so it can be redirected separately from machine-readable payloads). Commands that emit JSON do so on stdout, gated by a --json flag where applicable. Progress bars auto-disable when stderr is not a TTY (CI-friendly).

​
Auto-detected configuration

Several commands auto-resolve their inputs when the standard env vars are set:
  • DATABASE_URL — not auto-detected on its own: the source URL is read via the --url-env <VAR> flag, which takes the name of the variable to read. These examples pass --url-env DATABASE_URL, so set DATABASE_URL (in your shell or .env) to match — or pass the name you use, e.g. --url-env SCHEMABRAIN_DATABASE_URL (the name init reads by default and writes into the host snippet). Pick one name and use it consistently.
  • ANTHROPIC_API_KEY — required for any LLM-touching command; cost-free --no-enrich / --dry-run modes skip the check.
  • DBT_PROJECT_DIR — init walks this (or the cwd, looking for dbt_project.yml) and auto-routes the curation stages through the dbt importer when found.
  • SCHEMABRAIN_LOG_LEVEL — read when -v/-vv flags are not available (e.g. serve under Claude Desktop).
  • SCHEMABRAIN_EVENTS_PATH — overrides the default events JSONL path for serve + tail.
  • SCHEMABRAIN_MAX_LLM_COST_USD — fallback cost cap when --max-cost-usd is not passed on suggest commands.
  • SCHEMABRAIN_STUB_RESPONSE — used by --provider stub for CI smoke tests.
A .env file in the current working directory is also loaded automatically before any subcommand runs. Shell exports always win — .env only fills gaps.

Setup

The end-to-end install walkthrough that uses these commands.

MCP tool reference

The twelve typed MCP tools schemabrain serve exposes.

Dashboard

The local UI launched by schemabrain dashboard.

Architecture

Where each command sits in the pipeline.