# Running seeds (/docs/schema/seeds/running)

---
title: Running seeds
description: The options each seed command takes, the dry run that rolls itself back, the config key that seeds on startup, and the same four operations from code.
kind: guide
package: questpie
---

`questpie seed` is one of three ways to reach the runner. A deploy step calls
the CLI, an app can seed itself as it boots, and a test suite calls the same
operations from code.

## Options

| Option                    | Commands                          | Effect                                                  |
| ------------------------- | --------------------------------- | ------------------------------------------------------- |
| `-c, --config <path>`     | all four                          | Use a config file other than `questpie.config.ts`.      |
| `--category <categories>` | `seed`, `seed:undo`               | Comma-separated filter: `required`, `dev`, `test`.      |
| `--only <ids>`            | `seed`, `seed:undo`, `seed:reset` | Comma-separated seed ids.                               |
| `-f, --force`             | `seed`                            | Run them again even though tracking says they finished. |
| `--validate`              | `seed`                            | Run them in a transaction, then roll it back.           |

`--force` on a checkpointed seed clears its step checkpoints and its tracking
row first, so every step runs again.

## The dry run

`questpie seed --validate` wraps the whole selected batch in one transaction,
runs it, then throws the transaction away. Rows and step checkpoints go with it,
no tracking row is ever written, and the seeds stay pending. It answers whether
the code runs against the schema you have now.

<Callout type="warn" title="Only the database rolls back">
	Email, HTTP calls, queue jobs and object-storage writes are outside the
	transaction and happen for real. Keep those out of a seed you plan to
	validate, or guard them yourself.
</Callout>

## On startup

`autoSeed` in your runtime config runs seeds as the app boots, after migrations
when `autoMigrate` is on too.

```ts title="src/questpie/server/questpie.config.ts"
import { runtimeConfig } from "questpie/app";

export default runtimeConfig({
	autoSeed: "required",
});
```

A single category is a shorthand that includes `required`, because demo and test
data is worth nothing without the bootstrap rows underneath it. An array is
taken literally.

| Value              | Runs                 |
| ------------------ | -------------------- |
| `true`             | every pending seed   |
| `"required"`       | `required`           |
| `"dev"`            | `required`, `dev`    |
| `"test"`           | `required`, `test`   |
| `["dev"]`          | `dev`, no `required` |
| `false` or omitted | nothing              |

Startup seeding is a background promise. `await app.waitForInit()` resolves once
migrations and seeds have finished, which is the line to put before you start
serving traffic.

## From code

`app.seeds` exposes the four operations with the same options the CLI parses.
Tests and one-off scripts use it instead of shelling out.

```ts
await app.seeds.run({ category: "test" });
await app.seeds.run({ only: ["demoPosts"], force: true });

const { pending, executed } = await app.seeds.status();

await app.seeds.undo({ category: "dev" });
await app.seeds.reset({ only: ["demoPosts"] });
```

`run()` takes `validate` too. The runner logs to stdout unless
`QUESTPIE_SEEDS_SILENT` is `1`, `true` or `yes`. `NODE_ENV=test` silences it on
its own.

## What the CLI does and the API does not

After `questpie seed` finishes, the CLI reindexes every collection that has
`searchable` turned on. Write-time indexing normally goes through the queue, and
the CLI has no worker running, so the seeded rows would otherwise stay invisible
to search until the next reindex.

## Related

- **[Seeds](/docs/schema/seeds)** for the file, the categories and the ordering.
- **[Checkpointed seeds](/docs/schema/seeds/steps)** for what `--force` clears.
- **[Configuration](/docs/ship/configuration)** for the rest of `runtimeConfig`.