CLI commands

Install the CLI globally or run with npx. All commands support global options where relevant.

Installation

npm install -g @xubylele/schema-forge

Or use without installing: npx @xubylele/schema-forge init

Global options

  • --safe — block execution if destructive operations are detected (exit with error)
  • --force — bypass safety checks and proceed (shows warning)

--safe and--force cannot be used together.

Commands

init

Initialize a new schema project (creates schemaforge/, config, state, migrations dir).

schema-forge init

generate

Generate SQL migration from schema changes. In CI, exits with code 3 if destructive unless --force.

schema-forge generate [--name "migration description"] [--safe] [--force]
  • --name — optional migration name (default: "migration")

diff

Compare schema with tracked state (or live DB when--url given) and show migration SQL. Does not write files.

schema-forge diff [--url "$DATABASE_URL"] [--schema public] [--safe] [--force]
  • --url — PostgreSQL URL (default: DATABASE_URL)
  • --schema — comma-separated schema names (default: public)

doctor

Check live database drift against state. Exits with code 2 when drift is detected.

schema-forge doctor [--url "$DATABASE_URL"] [--schema public] [--json]

introspect

Extract normalized schema from PostgreSQL (information_schema).

schema-forge introspect [--url "$DATABASE_URL"] [--schema public] [--json] [--out path.json]

import

Reconstruct schema.sf from existing SQL migrations (file or directory).

schema-forge import <path-to-sql-or-dir> [--out schemaforge/schema.sf]

validate

Detect destructive or risky changes. With--url, validates against live DB;--json outputs a drift report.

schema-forge validate [--url "$DATABASE_URL"] [--schema public] [--json]

Exit codes

  • 0 — success
  • 1 — validation error (invalid DSL, config, or operation blocked e.g. by --safe)
  • 2 — drift detected (doctor, validate)
  • 3 — destructive operations in CI unless --force

For the full machine-readable contract, see docs/exit-codes.json in the repo.