seedkit-cli

Realistic, referentially-correct test data for any Postgres schema — or a fresh disposable Postgres from a sentence.

npx seedkit-cli new --prompt "saas crm"
# ✓ 8 tables, 14 relations · 14,820 rows · ready
# postgres://user:****@ep-cool-leaf-7281.eu-central-1.host.tld/seedkit_a3fd

Install

npm i -g seedkit-cli          # or: pnpm / yarn / bun
seedkit --help

Or run once without installing: npx seedkit-cli <command>.

Note: the package on npm is seedkit-cli, but the binary it installs is just seedkit. After a global install, type seedkit everywhere.

Quickstart

seedkit login                                 # one-time, browser-based
seedkit new --prompt "substack clone"         # provision a disposable Postgres
seedkit preview                               # sample rows without inserting
seedkit seed --scope "technical writers"      # re-seed with fresh AI-generated data
seedkit connect                               # introspect + print schema summary
seedkit list                                  # see your active databases
seedkit destroy substack-clone --yes          # tear it down (data stays on file)
seedkit revive substack-clone                 # bring it back

seedkit new provisions a hosted Postgres and returns a connection string. seed / preview / connect work against any Postgres URL — either the one you just created (remembered automatically), $DATABASE_URL, or one you pass via --url.

Commands

| Command | What it does | |---|---| | login | Browser-based device-flow auth. Stores a PAT in ~/.config/seedkit/config.json (chmod 0600). | | logout | Clear credentials + remembered DB. | | whoami | Show authenticated user + active org + API URL. | | new | Provision a disposable hosted Postgres from a prompt or DDL file, seed it, return the URL. | | list | List your disposable databases (active by default; --all includes destroyed). | | destroy | Destroy a live database by name/id. The seed data is kept for revive. Requires --yes. | | revive | Re-provision a destroyed database from its stored seed data. | | connect | Introspect a Postgres URL and print a schema summary. | | preview | Print 5 sample rows per table without touching the database. | | seed | Generate realistic INSERT SQL on the server and apply it to a Postgres URL. | | cache | List cached SQL blobs (useful for --from-cache / --seed). |

Run seedkit <command> --help for flag-level details.

seedkit new

seedkit new --prompt <text>
seedkit new --schema <path-to-ddl.sql>

Creates a fresh disposable Postgres for your org, seeds it with realistic AI-generated data, prints the connection URL, and remembers it so subsequent commands can skip --url.

Flags:

• --prompt "…" — natural-language description (mutually exclusive with --schema).
• --schema ./file.sql — read a CREATE TABLE ... DDL file instead.
• --name — database name (default: slug of the prompt or filename).
• --rows <n> — approximate rows per table, 5–1000 (default 100).
• --seed <id> — lock a reproducible variant. Same seed + same prompt → identical cached data.
• --from-cache — reuse an existing cached SQL blob; error if none matches. Mutually exclusive with --seed.
• --env [path] — on success, append DATABASE_URL=... to .env.local (or the given path).
• --no-wait — queue provisioning and exit; useful in CI pipelines.
• --org <id|slug> — override the active org from your config.

Output contract: status lines on stderr, the raw connection URL as the final line on stdout — so DATABASE_URL=$(seedkit new --prompt "saas crm") just works.

seedkit seed

seedkit seed [--url <postgres-url>] [--scope "…"]

Generates INSERT SQL for your schema and applies it transactionally. Introspects the target DB, hands the DDL to the backend, and applies the returned SQL wrapped in BEGIN ... COMMIT with SET CONSTRAINTS ALL DEFERRED.

Flags:

• --url — target DB. Defaults to $DATABASE_URL, then the remembered one from a previous new/connect.
• --schema <schema> — schemas to introspect, comma-separated (default public).
• --scope "…" — domain description for the generator (e.g. "German B2B SaaS").
• --locale en-US — passed through to the generator.
• --rows <n> — row count hint (default 100).
• --seed <id> — lock a reproducible variant.
• --from-cache — reuse a cached SQL blob; error if none. Mutually exclusive with --seed.
• --reset — TRUNCATE target tables before inserting. Required if you're re-seeding and hitting unique-constraint violations.

seedkit preview

Same inputs as seed, but renders a 5-row sample per table and does not write. Use --raw to print key=value pairs instead of a boxed table.

seedkit list / destroy / revive

seedkit list [--all] [--limit N]
seedkit destroy <name|id> --yes
seedkit revive <name|id>

list shows a flat status table with colored dots (● ready / ⟳ provisioning / ○ destroyed). <name|id> accepts a full id, an id prefix of ≥8 chars (like the ones printed by list), or a case-insensitive full name. Ambiguous matches (multiple DBs sharing a name) are rejected so you pass the id.

revive polls until the re-provisioned database is ready and prints a fresh connection URL; the CLI then remembers it.

seedkit cache

seedkit cache [--limit N]

Lists the cached INSERT-SQL blobs stored against your org. Useful when --from-cache doesn't find what you expected — the SCHEMA column is a hash prefix of the DDL each entry was generated from, so you can see whether seedkit new (LLM-authored DDL) and seedkit seed (introspected DDL) actually match.

Caching model (--seed / --from-cache)

Every new/seed/preview generation is cached in Supabase Storage, keyed by sha256(schema_ddl + scope + row_hint + seed_id + model).

• No flags → fresh LLM call every run. Still cached (under a random nonce) so billing stats stay accurate; just not retrievable by name.
• --seed <id> → first run calls the LLM and caches under <id>. Subsequent runs with the same --seed return byte-identical SQL, no LLM call.
• --from-cache → look up any prior cached entry for this schema + scope + rows + model. Error if none matches.
• --seed and --from-cache are mutually exclusive.

A cache hit is free against your ai_calls quota. A miss (fresh generation) counts one ai_lookup per call.

Remembered database

On a successful new/connect, the URL, id, and name are written to ~/.config/seedkit/config.json. Subsequent seed/preview/connect invocations fall back to it when --url and $DATABASE_URL are both unset. Precedence: --url → $DATABASE_URL → remembered.

If a remembered URL stops working (database expired or credentials rotated), the CLI detects the stale-connection error, clears the config entry, and tells you what to do next (seedkit new or --url).

Authentication & configuration

Auth token storage, in priority order:

1. SEEDKIT_API_KEY env var.
2. token in ~/.config/seedkit/config.json (written by seedkit login).

Backend URL, in priority order:

1. SEEDKIT_API_URL env var.
2. apiUrl in config file (persisted across login calls).
3. https://seedkit.dev.

For local development against a running app, the simplest path:

SEEDKIT_API_URL=http://localhost:3001 seedkit login      # env-var sticks to config
seedkit whoami                                           # works without env var now

Examples

Scenario-focused guides live in ./examples:

• examples/seed.md — what seeding actually does, --scope, re-seeding safely.
• examples/cache.md — how --seed / --from-cache / seedkit cache interact.
• examples/ci.md — using seedkit as your CI fixture (GitHub Actions, CircleCI, GitLab).
• examples/agents.md — giving AI agents a disposable Postgres via tool-calls or MCP.

Build & test (contributors)

pnpm install
pnpm typecheck
pnpm build
node dist/index.js <command>   # run the just-built CLI

Licensing

MIT. See LICENSE.