Load seed and test data into an environment from the same Zod schemas and codecs that define your tables and KV stores.
Synopsis
pithy seed [--worker <name>] [--env <name>] [--dry-run] [--redo] [--yes] \
[--confirm-production <phrase>] [--confirm-reset <phrase>] [--destroy-retained <n>] \
[--host <host>] [--json]Flags
| Flag | Default | Purpose |
|---|---|---|
--worker <name> | every Worker | Seed one Worker instead of every Worker under apps/ |
--env <name> | dev | The environment to seed. dev runs locally against Miniflare; anything else runs against the live D1, KV, R2, Images and Stream for that environment |
--json | false | Machine-readable output — the full write plan or run report as one line. Implies non-interactive: pithy seed never prompts when it is set, nor under --no-input or PITHY_NONINTERACTIVE=1 |
--dry-run | false | Show the plan and write nothing. Computes the write plan without touching any backend. Reads media sidecars so it can report upload, skip or reupload accurately; mints nothing |
--redo | false | Destructive. Drop every table and recreate the schema before seeding. See Resetting data, below |
--confirm-reset <phrase> | — | Unlock a non-dev --redo: the exact phrase yes, i really want to reset <env> |
--destroy-retained <n> | — | DESTRUCTIVE. Let --redo drop rows in retained tables. Must equal the row count the refusal printed |
--host <host> | the Worker’s own address | The host a prepared set’s origin is built from — see Where a prepared set is pointed, below |
--yes | false | Confirm a non-dev environment. Required for staging and prod; dev never needs it |
--confirm-production <phrase> | — | The non-interactive unlock for prod. See The production exception, below |
What it does
Fixtures are authored with defineSeed — the peer of defineCapability — and composed library-before-app, exactly like the migrations pithy migrate runs. There is no separate fixture format and no hand-written SQL: the schemas that define your tables are the schemas that define your test data.
Seed test data is the authoring model. This page is the command.
While it runs
Each write is named as it starts, one plain line each: ▸ Seeding things on DB for api... for a D1 table, the same shape for a KV store, an R2 key and a media file, with the store it lands in and the Worker it is written through. A remote seed is a REST round trip per write, and this is how you tell a slow one from a hung one. --redo narrates its reset first, in pithy migrate’s words. The report still prints once, at the end, unchanged. --json prints none of it; a missing TTY prints all of it.
Where a prepared set is pointed
A prepared set is handed the origin its Worker answers on (context.origin). Each environment answers it from its own source:
dev: the port this checkout pinned in.dev.config.json.- A declared environment: its address, the way
pithy envresolves it — thedomainsdeclaration, then the route, thenvars.BASE_URL. feature:https://<script>.<subdomain>.workers.dev— the feature Worker’s script name under the account’sworkers.devsubdomain, which the run looks up once. Without an account to ask, it reads the addresspithy provision --featurestamped.
--host overrides all three: --host preview.example.com. A bare host takes the environment’s scheme — http in dev, https everywhere else — and a full http:// or https:// origin is taken as written. One rule decides what a host is, and it refuses rather than repairs, before anything is written:
- every label a DNS label, so an encoded host like
%2e%2eis refused; - nothing after the host — a path, a query, a fragment, a trailing
/— and no credentials; - off
dev, no port and nohttp: a deployed Worker answers over https on the default port; localhost,127.0.0.1and*.localhostindevonly;- as a URL parser reads it: a host
new URLrefuses —xn--a.test— is refused, and a spelling it rewrites is refused rather than taken, so127.1,0177.0.0.1,0x7f.0.0.1and0are the loopback they parse to. Offdev, loopback in any spelling,0.0.0.0and IPv6[::1]are refused, and so is every IP address: a deployed Worker answers on a name.
pithy seed mints nothing, so it offers a prepared set an empty channel. context.mintedThisRun answers undefined for every name here, in every environment. That is not a failure: the only commands that mint and seed in one process are pithy provision --feature and pithy provision --env <environment> --seed, and a set that has to seal something under a freshly minted secret runs through one of those.
On a feature, a prepared set that asks for a secret is refused, as on staging and prod. A feature’s secrets exist only in its own Secrets Store and SECRETS database, where pithy provision --feature created them and the Worker reads them; nothing reads them back to this machine. The dev secrets file is never opened — it belongs to dev. There is no dev login on a feature; a magic link is how anybody signs in to one.
Idempotency
Every run is safe to repeat. D1 rows insert with INSERT OR IGNORE, KV entries put by key, and a once media asset uploads on its first run only and skips on every run after. Re-running against an environment that already has the fixtures loaded writes nothing new and changes nothing existing.
This is also why editing a fixture’s values and re-running does nothing: the row already exists, so it is ignored, unchanged. --redo is the answer to that, and it is below.
Fixture size
Make a fixture as big as the thing it has to prove. A paged list needs more rows than a page, and the default page size is 25.
D1 accepts 100 bound parameters in one statement, and an insert binds one per column per row — so a seven-column table fits about fifteen rows per statement. pithy seed writes each group in chunks sized from that table’s own column count, so the limit is never a fixture’s problem and never a number to look up. A 500-row group lands the way a 3-row one does.
A group is not atomic across its chunks, and INSERT OR IGNORE is what makes that safe: a run that dies partway is re-run, the landed rows are ignored, and the rest go in.
The production exception
Every other flag in this CLI follows one rule everywhere: --json means non-interactive, full stop. pithy seed --env prod is the one place a flag additionally gates content rather than just interactivity — because seeding production is rare and should stay rare.
devnever asks for anything.staging, and any other non-dev, non-production environment, needs--yes.prodneeds--yesand the exact phraseyes, i really want to seed production, matched case-insensitively after trimming. Interactively you are prompted for it. Non-interactively —--json,--no-input,PITHY_NONINTERACTIVE=1, CI, no terminal — there is no prompt, so pass it. Omitting it there is refusedcore/person_required, exit 5, and the action names--confirm-production: the phrase is a person’s to give, so an agent stops and asks:
pithy seed --env prod --yes --confirm-production "yes, i really want to seed production"Get it wrong, or omit it headlessly, and the run is refused before anything opens:
$ pithy seed --env prod --yes --json
The production confirmation phrase did not match.
Pass --confirm-production "yes, i really want to seed production" to seed production.The flag and the phrase keep the word production deliberately. The environment is named prod, and --env production is refused — but a confirmation phrase is read by a person about to overwrite live data, and yes, i really want to seed prod is a sentence you can type without meaning it.
Underneath both gates is a third, structural one that no flag can bypass: a seed set is only ever composed for prod if it lists prod in its own environments array.
Resetting data with --redo
--redo is for the moment you edited a fixture’s values and want them to actually land. It is not a per-row refresh. It is a full schema reset:
Seeded data is local by default, which is what makes it safe to throw away and rebuild while pithy dev is running.
- Roll every migration back — every
down, not just the latest, in reverse order. - Reapply every migration’s
up, recreating the schema empty. - Seed as normal.
Because every table the migration registry owns comes back empty, step 3’s ordinary non-destructive writes just work. There is also nothing left of what was there before: --redo destroys every row in every table the registry owns, not just the rows a fixture wrote. Data you inserted by hand, in a seeded table, does not survive.
That is the sharp edge. Reach for --redo only when a clean rebuild is what you actually want.
A real reset opens with the banner that names what it just did, then a line per database:
$ pithy seed --env dev --redo
DESTRUCTIVE. Every table in dev was dropped and recreated.
Reset app (DB): 1 migration rolled back and reapplied.
api 0200_leaderboard_demo_board: 12 rows.
Done.--redo carries its own, stricter gate. --yes means yes, this is not dev; it was designed to authorize writing seed rows, which is additive and harmless. A reset drops every table first. Letting one flag authorize both would mean a script — or a hand — that knew only to pass --yes could destroy an environment’s entire dataset.
| Environment | Plain seed | --redo |
|---|---|---|
dev | Free | Free — a local Miniflare store is what reset is for |
staging, a feature environment, anything non-dev | --yes | The exact phrase yes, i really want to reset <env> |
prod, and any name in seed.productionEnvironments | --yes plus the seed confirm phrase | The reset phrase, and it is refused headlessly without it |
The phrase names its environment, so one authorizing a staging reset cannot be pasted into a command targeting another. Automation is preserved — CI passes the flag explicitly — and a reset simply cannot happen by accident.
Two things --redo does not reset. A retained table — the secrets vault, the email suppression list — holds rows that exist nowhere else, so a reset refuses while one holds rows, naming each table and the count, before any database moves. --confirm-reset agrees to a reset; it does not agree to losing credentials. Pass --destroy-retained <n> with the printed count to drop them anyway. And a database another environment binds — EMAIL_SUPPRESSIONS, one database in every stanza — is kept, because resetting it from staging resets production’s. The dry run names both:
$ pithy seed --env staging --redo --dry-run
Would reset secrets (SECRETS): 1 migration. Retained: pithy_secrets_rotations, pithy_secrets_system_secrets.
Kept emailSuppressions (EMAIL_SUPPRESSIONS): prod binds it too.
Nothing to seed for staging.
Dry run. Nothing written.A non-dev reset is audited: a seed/schema_reset event at critical severity, naming the environment and the databases involved. The outcome is always truthful — recorded as success once the reset completes, or as failure, with the command still failing, if it dies partway. A dev reset records nothing, because auditing covers actions that reach a remote system and a dev run only touches the local store.
--json
One line, the same shape for a plan and for a report, with dryRun telling you which.
$ pithy seed --env dev --dry-run --json
{"command":"seed","schemaVersion":2,"env":"dev","dryRun":true,"workers":[{"worker":"api","sets":[{"name":"0200_leaderboard_demo_board","d1":[{"database":"app","table":"boardEntries","rows":12}],"kv":[],"r2":[],"media":[]}],"skippedByEnv":[],"shared":[]}],"devSecrets":null}| Key | Type | Meaning |
|---|---|---|
command | string | "seed" |
schemaVersion | integer | The version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one |
env | string | The environment seeded |
dryRun | boolean | Whether the plan was computed and nothing written |
workers | object[] | The per-Worker outcome, in fan-out order |
workers[].worker | string | The Worker’s name |
workers[].sets | object[] | The per-set outcome, in run order, each named by its composed key and carrying its d1, kv, r2 and media writes |
workers[].sets[].d1[].rows | integer | The rows the fixture carries for that table: what the run planned |
workers[].sets[].d1[].written | integer, optional | A real run only: the rows that landed. An existing row is ignored, so a re-run reports 0. Absent on a dry run |
workers[].sets[].kv[].entries | integer | The entries the fixture carries for that store: what the run planned |
workers[].sets[].kv[].written | integer, optional | A real run only: the entries put. An existing key is left alone, so a re-run reports 0. Absent on a dry run |
workers[].sets[].r2[].written | boolean, optional | A real run only: whether the object was put. An existing key is left alone, so a re-run reports false. Absent on a dry run |
workers[].skippedByEnv | string[] | The sets the registry carries that this environment disallows — surfaced, never silently dropped |
workers[].shared | string[] | The sets an earlier Worker in the fan-out already wrote to the same store. Two Workers sharing a binding share one store, so the fixture runs once and the second says so rather than double-counting |
reset | object[] | Present only with --redo: one entry per physical database whose schema was, or would be, reset |
reset[].retained | string[] | The retained tables that database carries. A reset refuses while one holds rows. Empty when there are none |
reset[].boundBy | string[], optional | The other environments binding that database. Present only when the reset keeps it |
devSecrets | object or null | What the dev-secrets pass wrote, and which Workers’ .dev.vars it refused. null on a dry run and outside dev, where nothing is written |
plan | object | Present only under --dry-run: the same writes in the shape every --dry-run shares. Each table, store, object and asset is one data entry, and each database a --redo would reset is a reset |
Errors
Every refusal here is a gate rather than a fault, and each one names the flag that opens it.
| Condition | Effect |
|---|---|
--env production | Refused at the flag, exit 2. The environment is prod |
A non-dev environment without --yes | Refused before anything opens, exit 2 |
prod without the confirmation phrase, non-interactively | Refused core/person_required, exit 5, naming --confirm-production in the action, before anything opens |
A non-dev --redo without --confirm-reset "yes, i really want to reset <env>" | Refused core/person_required, exit 5, naming --confirm-reset, when nobody could be asked or the phrase is wrong. The phrase names its environment |
A --redo over a retained table that holds rows, without --destroy-retained <n> equal to them | Refused before any database moves, exit 2. The refusal names each table and the count to pass |
A Worker that was supposed to get a generated .dev.vars and did not | The fixtures still run — they are the rest of the run and worth doing — and the exit code is 1. The refusal names the file and offers .dev.vars.local |
Examples
A normal run reports one line per seed set, then Done. Every line is prefixed with the Worker that ran it, because the run fans out over apps/* and a fan-out should read as one list rather than several interleaved ones.
$ pithy seed --env dev
api 0100_auth_test_users: 3 rows, 1 entry.
api 0200_leaderboard_demo_board: 12 rows.
Done.A set with nothing to write still gets a line, so a quiet run is never mistaken for a skipped one:
$ pithy seed --env dev
api 0300_media_avatar: nothing to seed.
Done.A set present in the registry but not allowed for the target environment is reported above the sets that ran, never silently dropped:
$ pithy seed --env dev
api skipped 0210_leaderboard_prod_smoke: not allowed in dev.
api 0200_leaderboard_demo_board: 12 rows.
Done.--dry-run prints the same per-set shape and ends with a plain reminder in place of Done.:
$ pithy seed --env staging --dry-run
api 0200_leaderboard_demo_board: 12 rows.
Dry run. Nothing written.A real run counts what landed. Seeding never overwrites, so a second run plans the same writes, finds them already there, and says so. A plain count is what was written:
$ pithy seed --env dev
api 0100_auth_test_users: 3 rows already there, 1 entry already there.
api 0200_leaderboard_demo_board: 12 rows already there.
Done.