one global binary. node 18+.
satus ships as a single Node binary. We test on Node 18, 20, and 22 across macOS and Linux. Windows is supported via WSL2.
# install globally$ npm i -g @passkeybridge/satus# verify$ satus --versionsatus 0.2.0
point at any postgres. pick a profile.
Supabase, Neon, Railway, RDS, or a local instance—satus reads DATABASE_URL and your LLM key from the environment. It will refuse to run against a database with more than 10,000 user rows unless you pass --force.
# 1 · database & llm provider$ export DATABASE_URL="postgres://user:pass@localhost:5432/app"$ export OPENAI_API_KEY="sk-..."# 2 · fork an official profile into ./satus/$ satus init --profile e-commerce✓ wrote satus/profiles/e-commerce.md✓ wrote satus/satus.config.json
see the sql before it hits your database.
--dry runs the full pipeline—introspect, plan, generate—but writes the output to stdout as a single SQL transcript instead of executing it. Diff it, review it, commit it as a fixture.
# write the planned inserts to a file$ satus generate --profile e-commerce --dry > satus-output.sql✓ planned 4,812 rows across 14 tables✓ estimated cost · $0.07
one transaction. all-or-nothing.
satus generate runs inside a single Postgres transaction. If any insert fails, the entire run rolls back—your database is never left in a half-seeded state.
$ satus generate --profile e-commerce✓ 4,812 rows · $0.07 · 11.4s
the three failures you’ll hit on day one.
Most issues fall into three buckets. If you hit something we haven’t listed, open an issue with the stack trace and the offending CREATE TABLE statement—schema reproduction is the #1 thing we triage.
- errorE_FK_CYCLEForeign-key cycle could not be broken automatically
satus detects cycles in your FK graph at planning time and breaks them automatically by deferring a nullable column and back-patching in pass 2 (see the cyclic FKs post). This error fires when every column on the cycle is NOT NULL with no DEFAULT, so there's nowhere to put a placeholder. Mark one side nullable, add a DEFAULT, or declare the constraint DEFERRABLE.
- errorE_DB_NOT_EMPTYDatabase has more than 10,000 user rows
Safety guard. Re-run with --force if you are certain you want to add seed data on top of real rows. We recommend pointing at a fresh branch (Supabase, Neon) or a Docker container instead.
- errorE_LLM_RATE_LIMITLLM provider rate-limited the run
satus retries with exponential backoff up to 5 attempts. If you hit a hard tier ceiling, lower --batch-size (default 50) or upgrade your provider tier. We never resell tokens—the bill is on your provider's dashboard.
satus.sh—built for engineers who hate seeing John Doe in their demo data.