CLI Reference
Complete reference for all MigrationPilot CLI commands and options.
analyze
Analyze a single migration file for safety issues.
migrationpilot analyze <file> [options] Options: --pg-version <version> Target PostgreSQL version (default: 17) --format <format> Output: text, json, sarif, markdown --fail-on <severity> Exit code threshold: critical, warning, never --database-url <url> PostgreSQL connection for production context --license-key <key> Org plan license key (policy enforcement) --fix Auto-fix safe violations --dry-run Preview fixes without writing (use with --fix) --stdin Read SQL from stdin --quiet One-line-per-violation output --verbose Show all checks including passing --exclude <rules> Comma-separated rules to skip --offline Skip update checks and network access --no-config Ignore config file
check
Analyze all migration files in a directory.
migrationpilot check <dir> [options] Options: --pattern <glob> File pattern (default: **/*.sql) --pg-version <version> Target PostgreSQL version --format <format> Output: text, json, sarif, markdown --fail-on <severity> Exit code threshold --database-url <url> PostgreSQL connection for production context --license-key <key> Org plan license key (policy enforcement) --exclude <rules> Comma-separated rules to skip --offline Skip update checks and network access --no-config Ignore config file
plan
Show execution plan with lock timeline visualization.
migrationpilot plan <file> [options] Options: --pg-version <version> Target PostgreSQL version
plan-fix
Emit a step-by-step expand-contract plan for the violations that have no one-line fix. Each step is runnable SQL with its own lock note, and a DEPLOY BOUNDARY marks where an application release has to ship before the next step may run.
migrationpilot plan-fix <file> [options] Options: --pg-version <version> Target PostgreSQL version --format <format> Output: text, json --rule <ids> Comma-separated rules to plan for (e.g. MP002,MP007) --no-config Ignore config file
simulate
Run the migration for real against PostgreSQL compiled to WASM (PGlite), in memory, thrown away at exit. Catches what reading SQL cannot: CONCURRENTLY inside a transaction, casts PostgreSQL refuses, references to objects that do not exist yet. It cannot observe lock contention — one connection means nothing to block — and its timings say nothing about production, where the tables have rows.
migrationpilot simulate <target> [options] Options: --baseline <file> SQL to load as the starting schema --pattern <glob> File pattern when target is a directory --pg-version <version> Target PostgreSQL version for the static rules --format <format> Output: text, json --search-path <name> Schema to introspect for the diff (default: public) --no-static Skip static analysis, report execution only --exclude <rules> Comma-separated rules to skip --no-config Ignore config file Needs the optional PGlite engine, which is 25 MB and only this command uses: npm install @electric-sql/pglite # in your project, and for npx npm install -g @electric-sql/pglite # for a global migrationpilot Exit codes: 0 everything executed, 2 a statement failed.
mutation-test
Test the guardrail rather than the migration. Instead of asking "is this migration safe?", this mutates migrations that already pass into dangerous near-neighbours and reports which ones your config would let through. Experimental: operators and output may change between minor versions.
migrationpilot mutation-test <target> [options] Options: --pattern <glob> File pattern when target is a directory --pg-version <version> Target PostgreSQL version --format <format> Output: text, json --fail-on-holes Exit 1 when a dangerous mutant survives (default) --no-fail-on-holes Report holes but always exit 0 --exclude <rules> Comma-separated rules to skip --no-config Ignore config file
predict
Estimate how long a migration will take, from the operation type and whatever table statistics you can supply.
migrationpilot predict <file> [options] Options: --row-count <count> Table row count for calibration --size <bytes> Table size in bytes --index-count <count> Number of existing indexes --format <format> Output: text, json
rollback
Generate the reverse SQL for a migration. Not every statement has an exact inverse — see rollback grading for what the grades mean.
migrationpilot rollback <file> [options] Options: --output <file> Write to a file instead of stdout
template
Generate a known-safe expand-contract migration for a schema change that is dangerous done directly.
migrationpilot template <operation> Operations: rename-column Add, backfill, sync, then drop the old column change-type Move to a new column of the new type split-table Extract columns into a new table safely add-not-null The validated-constraint path to NOT NULL remove-column Drop a column across two deploys
team
Show the members and seat usage recorded for the Org plan. The linter itself is free and unmetered; this reports on an Org-plan deployment and prints nothing about the analysis.
migrationpilot team [--json]
init
Generate a default .migrationpilotrc.yml config file.
migrationpilot init
detect
Detect migration frameworks in the current project.
migrationpilot detect [dir]
watch
Watch migration files for changes and analyze on save.
migrationpilot watch <dir> [options] Options: --pattern <glob> File pattern (default: **/*.sql) --pg-version <version> Target PostgreSQL version
hook
Install or uninstall a Git pre-commit hook.
migrationpilot hook install [dir] migrationpilot hook uninstall [dir]
precommit
What the .pre-commit-hooks.yaml entry runs. The pre-commit framework appends the staged files it matched, so this takes many paths at once where analyze takes one. Clean files stay silent; only files with violations are reported.
migrationpilot precommit <files...> [options] Options: --pg-version <version> Target PostgreSQL version --fail-on <severity> Block the commit on: critical, warning, never --exclude <rules> Comma-separated rules to skip --no-config Ignore config file
list-rules
List all available safety rules.
migrationpilot list-rules [options] Options: --json Output as JSON --severity <level> Filter by severity
explain
Show the full entry for one rule: what it detects, why it matters, the safe alternative, and how to configure or disable it.
migrationpilot explain MP001
doctor
Run diagnostic checks on your environment.
migrationpilot doctor
trends
View historical analysis trends.
migrationpilot trends [options] Options: --format <format> Output: text, json
drift
Compare two database schemas for differences.
migrationpilot drift [options] Options: --source <url> Source database connection string --target <url> Target database connection string --schema <name> Schema to compare (default: public) --format <format> Output: text, json
completion
Generate shell completion scripts.
# Bash migrationpilot completion bash >> ~/.bashrc # Zsh migrationpilot completion zsh >> ~/.zshrc # Fish migrationpilot completion fish > ~/.config/fish/completions/migrationpilot.fish