satus.
§01|Synopsis

four verbs. one binary.

The CLI exposes four subcommands—init, generate, activate, whoami—and two global flags. Connection strings and provider keys are read from the environment by default so secrets never land in shell history; equivalent overrides are documented per command below.

New here? Walk through the quickstart first—this page is the reference, not the tutorial.

# global form
$ satus <command> [flags]
# global flags
$ satus --version
satus 0.2.0
$ satus --help
§02|Environment

two variables. one optional override.

satus reads two environment variables at runtime. Both are required for generate; init, activate, and whoami need neither.

  • required
    DATABASE_URL

    Standard libpq connection string. SATUS_DATABASE_URL is also accepted and takes precedence. Either can be overridden per run with --dsn on generate.

  • required
    OPENAI_API_KEY

    Bring-your-own key. satus never proxies LLM calls; the request goes directly from your machine to OpenAI. OPENAI_BASE_URL is honored if you need to point at an OpenAI-compatible endpoint.

§03|satus init

scaffold a config in the current directory.

Writes satus.config.json to the current working directory. Interactive prompts ask for the connection string (blank falls back to $DATABASE_URL), the schema, the profile, and the row count. Safe to re-run; existing config is preserved unless --force is set.

$ satus init
  • --forcefalseOverwrite an existing satus.config.json.
§04|satus generate

one transaction. all-or-nothing.

Introspects the target schema, builds the foreign-key DAG, breaks any cycles whose back-edge is nullable, calls the LLM for realistic rows, then writes the entire dataset inside a single Postgres transaction. If any insert fails the whole run rolls back and your database is left untouched.

--dry-run performs introspection, planning, and cost estimation but skips both the LLM call and the write phase. It is the right way to preview what a run would do before spending tokens.

$ satus generate --profile saas --rows 25
# preview the plan without spending tokens or writing rows
$ satus generate --profile saas --dry-run
  • --profile <name>from configReference profile. One of: saas, ecommerce, b2b.
  • --rows <n>50Rows to generate per table. Free tier caps at 25 rows/table and 5 tables.
  • --batch-size <n>25Rows per LLM call. Lower if you hit provider rate limits.
  • --max-cost <usd>1.00Abort before any LLM spend if the estimated cost exceeds this ceiling.
  • --dsn <url>from envPostgres connection string. Overrides DATABASE_URL and the config file.
  • --schema <name>from configPostgres schema to seed. Defaults to public when neither config nor flag is set.
  • --model <id>from configOpenAI model id. Overrides the model recorded in satus.config.json.
  • --truncatefalseTRUNCATE target tables (RESTART IDENTITY CASCADE) before inserting.
  • --dry-runfalsePlan only. Print the insert order and the cost estimate; do not call the LLM and do not write to the database.
§05|satus activate

swap free for pro or team.

Validates a license key against https://satus.sh/api/public/license/verify and writes the result to the local cache (~/.satus/license-cache.json, 24-hour TTL). Until activated, generation runs under the Free tier limits noted above.

$ satus activate satus_live_••••••••
§06|satus whoami

read the cached license.

Prints the currently activated tier and the email the license was issued to. Reads the local cache only; no network call is made.

$ satus whoami
§07|Operational notes

exit codes, privacy, and the wire shape.

Every command returns 0 on success and 1 on any error, with a one-line diagnostic written to stderr. Stable per-failure-mode exit codes are planned for a future minor release; today, scripts that need to branch on failure should match the stderr message.

satus never sends your schema, your data, or your column names to satus.sh. The only network call to satus.sh is the license verify, which sends your license key and nothing else. LLM calls go directly from your machine to your provider with your key. Telemetry, when you opt in, sends an anonymized run summary (table count, row count, duration, exit code)—never table or column names, never row data.

Reference matches the published binary at v0.2.0 (released 2026-06-04). Flag defaults are stable across the 0.x line; new flags may be added in minor releases.