Skip to content
onwardpg

CLI reference

All commands emit JSON by default. Use --target NAME when a repository configures more than one target.

config check

Section titled “config check”
Terminal window
onwardpg config check

Validate config and database boundaries, deterministically compile desired DDL, materialize it in disposable PostgreSQL, and verify accepted history.

init

Section titled “init”
Terminal window
onwardpg init

Create the first clone-verified history entry. It refuses a non-empty target history.

plan

Section titled “plan”
Terminal window
onwardpg plan [NAME] \
  [--hint JSON] [--hints-file FILE] \
  [--dev-hint JSON] [--dev-hints-file FILE] \
  [--output json|text|sql]

Start or revise one worktree-local active migration. The durable comparison is accepted history to working DDL. When a development database is configured, --output sql prints a separate direct development reconciliation; onwardpg does not apply it.

Exit status 2 means the plan needs a semantic decision or editable SQL, not that onwardpg guessed a result.

status

Section titled “status”
Terminal window
onwardpg status

Report the local active PlanID, selected bundle, and whether its parent is current. This is Git-independent and does not contact PostgreSQL.

verify

Section titled “verify”
Terminal window
onwardpg verify [NAME]
onwardpg verify --check
onwardpg verify --through expand

Replay exact history and bundle bytes in disposable databases, run assertions, and prove catalog convergence. --check is the read-only CI gate; partial verification proves both the prefix and its continuation without claiming either ran in a real environment.

drift check

Section titled “drift check”
Terminal window
onwardpg drift check --database "$PRODUCTION_DATABASE_URL"

Inspect the supplied database read-only and compare it with accepted desired state. A finding is evidence to investigate, never permission for onwardpg to change production.

dev plan

Section titled “dev plan”
Terminal window
onwardpg dev plan --output text

Lower-level development reconciliation from the read-only dev catalog to working DDL. Workspace mode preserves absence-only local objects to make branch switching less destructive.

For the full preview protocol and lower-level draft, history status, selectors, and planner flags, see the repository’s canonical docs/cli.md.