Scoping
The scope tells Seedfast what to generate — which tables, how many records, and what kind of data. You can define it interactively in the terminal or pass it directly via the --scope flag.
Default behavior#
When you run seedfast seed without any scope, Seedfast analyzes your schema and proposes a reasonable default scope on its own. It picks a set of tables that form a coherent dataset and suggests record counts that make sense for the schema size.
This default is good enough to get started, but explicit scoping produces better results. The more precisely you describe what you need, the better Seedfast can match it — both in structure and in the realism of the generated data.
Interactive mode#
Interactive mode starts when you run seedfast seed without --scope. Seedfast proposes a scope, shows you the plan, and waits for your input before writing anything.
Adding tables to scope:
If the proposed plan doesn't include a table you need:
Approve? (Y/n): also include the invoices table
Seedfast replans with the added table, resolving any new dependencies automatically.
Removing tables from scope:
Approve? (Y/n): skip audit_logs and system_events
Adjusting record counts:
Approve? (Y/n): I need at least 500 orders, keep everything else the same
Refining data quality:
The scope isn't just about which tables and how many rows — it also guides the character of the data:
Approve? (Y/n): make customers US-based enterprise companies, not individuals
Approve? (Y/n): orders should be mostly in a completed or shipped state, not pending
These instructions become part of the generation context. Seedfast incorporates them and replans. You can refine as many times as needed — the session stays alive, no restarting.
CLI mode (--scope flag)#
Pass --scope to skip the interactive prompt entirely. Seedfast builds the plan and starts seeding immediately:
seedfast seed --scope "seed 100 users with orders and invoices"
This is how you use Seedfast in scripts, CI/CD pipelines, or any non-interactive environment.
What to put in the scope:
Be explicit about tables and counts:
seedfast seed --scope "seed users, orders, and products — 200 users, 1000 orders"
Describe relationships when they matter:
seedfast seed --scope "seed 50 enterprise customers, each with 5-10 active subscriptions"
Exclude tables explicitly:
seedfast seed --scope "seed all tables in the public schema except audit_logs"
Add context about the data itself:
seedfast seed --scope "seed 100 employees across 5 departments, mix of seniority levels"
If the scope is ambiguous or has dependency issues, Seedfast exits with an error in --scope mode rather than entering an interactive loop — because there's no one at the terminal to resolve it. In interactive mode, the same issues trigger a conversation.
Auto-adaptation to schema changes#
Seedfast reads your live schema on every run. When your schema changes — new tables, renamed columns, added foreign keys — Seedfast picks it up automatically. You don't need to update scope instructions for changes that don't affect what you're seeding.
If a change breaks your scope (a table you reference was renamed, or a new required dependency appeared), Seedfast detects it and tells you before writing anything.
More detail = better quality#
Scoping affects not just structure but data quality. Every piece of context you provide — domain, geographic region, status distribution, user type — improves the realism of what gets generated.
Seedfast always tries to squeeze the maximum quality from the schema alone. But the schema has limits: it can tell Seedfast there's a status column with values active and inactive, but it can't tell Seedfast what ratio makes sense for your use case. The scope can.
See Data Realism for more on how Seedfast uses context to improve output quality.