Command-Line Interface

The CLI is where DBSprout started and where most automation lives. It is a standard POSIX-style command with subcommands, structured exit codes, and --help available at every level.

The core loop

dbsprout init --db postgresql://user:pass@localhost/mydb
dbsprout generate --rows 500 --engine heuristic
dbsprout validate

init introspects the target and writes a dbsprout.toml and a schema snapshot under .dbsprout/. generate reads that snapshot and produces numbered seed files in ./seeds/ (e.g. 001_users.sql, 002_posts.sql) in FK-safe order. validate replays the generation and asserts 100% referential and structural integrity.

The same three commands work against a schema file instead of a live database:

dbsprout init --file schema.dbml
dbsprout generate --output-format csv
dbsprout validate

Commands at a glance

Core

Command	What it does
`init`	Introspect a database or schema file; write `dbsprout.toml` + snapshot
`generate`	Generate seed data from the current snapshot
`validate`	Check generated data for FK, UNIQUE, NOT NULL, CHECK violations
`diff`	Report schema changes since the last `init` snapshot

Ops and diagnostics

Command	What it does
`report`	Generate an HTML quality report from recorded generation runs
`audit`	Show the LLM interaction audit log
`doctor`	Diagnose the environment (Python version, drivers, models, disk, secrets, plugins)
`models`	List, download, and inspect embedded GGUF models
`plugins`	Inspect discovered DBSprout plugins

Surfaces

Command	What it does
`tui`	Launch the Terminal UI — interactive schema browser and live progress
`serve`	Launch the Web Studio on `localhost:8420`

Advanced

Command	What it does
`train`	QLoRA fine-tuning pipeline — extract → serialize → run

Why use the CLI?

Pipe-friendly. All commands emit plain text or JSON (--format json on validate, diff). Pipe the output of dbsprout validate --format json into jq or into a CI assertion step without any extra tooling.

Shell history. Complex generation invocations (--rows 1000 --engine spec --privacy redacted --output-format direct --db ...) compose naturally as shell history entries or Makefile targets. They are repeatable with !! and diffable in code review.

CI-ready. Exit code 0 means success; non-zero means something failed. The --seed flag (default 42) makes output deterministic, so generated fixture files can be committed, diffed in PRs, and their changes reviewed. Add dbsprout generate && dbsprout validate to any CI step and you get guaranteed-correct seed data as an artefact.

Offline by default. Every command works without an internet connection. The [llm] extra adds an embedded 1.5 B parameter model for spec generation that runs entirely on device.

For the full option listing for every command, see the CLI Reference.