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.3.5
$ satus --help
§02|Environment

one db url. one provider key.

satus reads its connection string and an LLM provider key from the environment. Both are required for generate; init, activate, and whoami need neither.

Pick one provider per run. If both OPENAI_API_KEY and ANTHROPIC_API_KEY are exported and no --provider flag or provider config field is set, the run aborts with a clear message — auto-detect deliberately refuses to guess so a misplaced key never spends on the wrong invoice.

  • 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.

  • one of two
    OPENAI_API_KEY

    Bring-your-own OpenAI 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 (Groq, Together, a local proxy).

  • one of two
    ANTHROPIC_API_KEY

    Bring-your-own Anthropic key. The CLI calls api.anthropic.com directly using the pinned Messages API (anthropic-version: 2023-06-01) with tool-use forcing for structured output. ANTHROPIC_BASE_URL is honored if you need a compatible proxy.

§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.
  • --provider <id>auto-detectLLM provider: openai or anthropic. Falls back to env-var auto-detect (errors if both keys are set with no explicit choice).
  • --model <id>provider defaultModel id. Defaults to gpt-4o-mini for openai and claude-haiku-4-5 for anthropic. Cross-provider model names are not validated client-side.
  • --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.
  • -v, --verbosefalsePrint one line per LLM batch: table, batch index, rows, input/output tokens, and USD spent.
  • --jsonfalseEmit a single newline-terminated JSON object on stdout at completion (snake_case keys). All human output is redirected to stderr so stdout is safe for jq and CI.
§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.3.5 (released 2026-07-15). Flag defaults are stable across the 0.x line; new flags may be added in minor releases.