CLI Reference

Complete flag-by-flag reference for the seedforge CLI. Flags marked with defaults reflect the values baked into src/cli.ts in the library.

Synopsis

seedforge [options]

Seedforge reads a schema from a live database or ORM file, generates FK-correct fake rows, and either inserts them, writes a .sql file, or prints a dry-run summary. All behavior is controlled by the flags below or a .seedforge.yml config file.

Note

Flags always override values set in .seedforge.yml. See the config guide for YAML syntax.

Schema source

Exactly one schema source is required. If none is passed, Seedforge looks for prisma/schema.prisma in the current directory before giving up.

--db <url>

Database connection string. Accepts postgres://, postgresql://, mysql://, sqlite://, or a plain .db / .sqlite path.

seedforge --db postgres://localhost/mydb
seedforge --db mysql://root:pass@localhost/mydb
seedforge --db sqlite:///path/to/db.sqlite

--prisma <path>

Path to a Prisma schema file. No live DB is needed when combined with --output.

seedforge --prisma ./prisma/schema.prisma --output seed.sql

--drizzle <path>

Path to a Drizzle ORM schema file or directory of schema files.

seedforge --drizzle ./src/db/schema.ts --output seed.sql

--typeorm <path>

Path to a TypeORM entity directory.

seedforge --typeorm ./src/entities/ --output seed.sql

--jpa <path>

Path to a JPA/Hibernate Java entity directory.

seedforge --jpa ./src/main/java/com/example/entities/ --output seed.sql

--plugin <paths...>

One or more paths to plugin modules that register custom schema parsers or data generators.

seedforge --plugin ./my-parser-plugin.ts --output seed.sql

--schema <name>

Database schema namespace to introspect. Default: public.

seedforge --db postgres://localhost/mydb --schema app

Output

--output <file>

Write INSERT statements to a .sql file instead of executing them. When combined with a parser flag (--prisma, --drizzle, etc.), no live database connection is opened.

seedforge --db postgres://localhost/mydb --output seed.sql

--dry-run

Generate rows in memory and print a summary without touching the database. Default: false.

seedforge --db postgres://localhost/mydb --dry-run

--json

Emit a machine-readable JSON summary to stdout after the run. Default: false.

seedforge --db postgres://localhost/mydb --json

Generation

--count <number>

Rows per table. Default: 50. Per-table overrides live in .seedforge.yml under tables.<name>.count.

seedforge --db postgres://localhost/mydb --count 500

--seed <number>

PRNG seed for deterministic output. Same seed + same schema = identical rows every run.

seedforge --db postgres://localhost/mydb --seed 42

--fast

Use PostgreSQL’s COPY protocol for bulk insertion (10x+ faster on large datasets). PostgreSQL only — errors out with exit code 1 on MySQL or SQLite. Default: false.

seedforge --db postgres://localhost/mydb --count 100000 --fast

Filtering and config

--exclude <tables...>

Space-separated list of tables to skip. Glob patterns are supported in the config file but not on the CLI.

seedforge --db postgres://localhost/mydb --exclude schema_migrations audit_log

--config <path>

Path to a .seedforge.yml config file. If omitted, Seedforge auto-detects .seedforge.yml in the current directory.

seedforge --config ./config/seedforge.yml

AI-enhanced text

Seedforge can route text-column generation through an LLM for richer content. Requires --ai plus a provider.

--ai

Enable AI-enhanced text generation. Default: false.

--ai-provider <provider>

Provider name: openai, anthropic, ollama, or groq.

--ai-model <model>

Provider-specific model name.

--ai-columns <columns...>

Columns to route through the AI pool, either as bare column names (bio) or qualified (users.bio).

seedforge --db postgres://localhost/mydb \
  --ai --ai-provider openai --ai-model gpt-4o-mini \
  --ai-columns users.bio posts.body

Tip

API keys, temperature, batch size, and prompt templates live in .seedforge.yml under the ai: block.

Safety

--yes

Skip the production-database confirmation prompt. Seedforge warns before touching connection strings that look like managed hosts (RDS, Neon, Supabase, Cloud SQL, etc.). Default: false.

seedforge --db postgres://rds-host.amazonaws.com/mydb --yes

Logging

--verbose

Log the insertion order, deferred FK edges, self-referencing tables, and per-table column/FK counts. Default: false.

--quiet

Suppress all non-essential stdout. Errors still print to stderr. Default: false.

--debug

Dump the parsed schema as JSON and print the full options object (with connection strings redacted). Default: false.

seedforge --db postgres://localhost/mydb --verbose

Help and version

-h, --help

Display help text with examples.

-V, --version

Print the installed version.

Exit codes

Code	Meaning
0	Run completed successfully
1	Known error — bad config, missing schema source, production-check failure, plugin load failure, --fast on non-Postgres, etc. Rendered with an SF#### error code
2	Unexpected non-Error throw

Environment variables

Seedforge does not read environment variables directly from the CLI — every flag is explicit. However, .seedforge.yml supports ${VAR} interpolation, so the conventional pattern is to put the connection string in DATABASE_URL and reference it from YAML:

connection:
  url: ${DATABASE_URL}
  schema: public

DATABASE_URL=postgres://localhost/mydb seedforge --config .seedforge.yml

Any environment variable referenced with ${VAR} syntax inside .seedforge.yml is interpolated at config-load time.