one global binary. node 20+.
satus ships as a single Node binary. We test on Node 20 and 22 across macOS and Linux. Windows is supported via WSL2.
# install globally$ npm i -g @passkeybridge/satus# verify$ satus --version0.3.11
point at any postgres. pick a profile.
Supabase, Neon, Railway, RDS, or a local instance—satus reads DATABASE_URL and your LLM provider key from the environment. The free tier caps runs at 25 rows per table across 5 tables; a Pro or Team key (satus activate) removes the caps.
Pick one provider: export OPENAI_API_KEY, ANTHROPIC_API_KEY or XAI_API_KEY (xAI, from the CLI release after 0.3.11). If more than one is set, pass --provider openai|anthropic|xai on satus generate—auto-detect deliberately refuses to guess so a misplaced key never spends on the wrong invoice.
# 1 · database & llm provider (openai shown; swap for ANTHROPIC_API_KEY for Claude)$ export DATABASE_URL="postgres://user:pass@localhost:5432/app"$ export OPENAI_API_KEY="sk-..."# 2 · scaffold satus.config.json (interactive: schema, profile, provider, model)$ satus init✓ wrote satus.config.json
see the sql before it hits your database.
--dry-run runs the full pipeline offline—introspect, FK-sort, simulate, validate—without calling the model or writing a row. It prints a per-table cost estimate, then runs the relational validator against simulated output and exits non-zero on findings, so it works as a CI gate. Add --json for a machine-readable report.
# plan + validate offline; no spend, no writes$ satus generate --profile ecommerce --dry-runestimated cost: $0.0094✓ no validation findings across 5 tables
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 ecommerce --rows 25✓ inserted 125 rows across 5 tables
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_NO_PARENT_ROWSNo parent rows available for a NOT NULL foreign key
A child table's NOT NULL FK points at a table that isn't in the run set—usually because it lives in another schema or is listed under `exclude` in satus.config.json. Bring the parent into the run, make the column nullable, or seed the parent yourself first.
- errorE_LLM_RATE_LIMITLLM provider rate-limited the run
The run aborts and the transaction rolls back, so your database is untouched—re-run once the limit clears. Lower --batch-size (default 25) to shrink each request, 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.