CLI Reference

Quick Reference

Command	Purpose
`pgmt init`	Initialize new project
`pgmt apply`	Apply schema to dev database
`pgmt diff`	Preview what apply would do
`pgmt migrate new`	Generate migration
`pgmt migrate update`	Regenerate migration after changes
`pgmt migrate apply`	Apply migrations to target database
`pgmt migrate status`	Show migration status
`pgmt migrate validate`	Validate migrations match schema
`pgmt migrate diff`	Detect drift in target database
`pgmt migrate baseline`	Create baseline / consolidate migrations
`pgmt migrate baseline list`	List baselines
`pgmt debug dependencies`	Analyze object dependencies

Global Options

Available for all commands:

-h, --help                    # Show help
-V, --version                 # Show version
--config-file <FILE>          # Config file (default: pgmt.yaml)
-v, --verbose                 # Verbose output
-q, --quiet                   # Suppress non-essential output
--debug                       # Debug output

Database overrides:

--dev-url <URL>               # Development database
--shadow-url <URL>            # Shadow database
--target-url <URL>            # Target/production database

Directory overrides:

--schema-dir <PATH>           # Schema directory
--migrations-dir <PATH>       # Migrations directory
--baselines-dir <PATH>        # Baselines directory

pgmt init

Initialize a new pgmt project. Can be re-run to update an existing configuration.

pgmt init [OPTIONS]

Options:

--dev-url <URL>               # Database URL (required)
--create-baseline             # Create baseline from existing database
--no-baseline                 # Skip baseline creation
--no-import                   # Skip import (empty project)
--defaults                    # Use defaults for all prompts
--schema-dir <DIR>            # Schema directory name (default: "schema")
--migrations-dir <DIR>        # Migrations directory name (default: "migrations")
--baselines-dir <DIR>         # Baselines directory name (default: "schema_baselines")
--auto-shadow                 # Use auto shadow database
--shadow-pg-version <VER>     # PostgreSQL version for auto shadow (e.g., "14", "15", "16")
--roles-file <PATH>           # Path to roles file (default: auto-detect roles.sql)
--fresh                       # Force fresh init (overwrite existing config)

Re-initialization:

When run in a directory with an existing pgmt.yaml, you’ll be prompted to:

Update - Modify existing config (shows current values as defaults)
Fresh - Start over with new configuration
Cancel - Keep current configuration

Use --fresh to skip this prompt and always overwrite.

Examples:

# Interactive (recommended)
pgmt init --dev-url postgres://localhost/myapp_dev

# Import existing database with baseline
pgmt init --dev-url postgres://localhost/existing_db --create-baseline

# Empty project
pgmt init --defaults --no-import

# Custom directory structure
pgmt init --dev-url postgres://localhost/myapp_dev \
    --schema-dir db/schema \
    --migrations-dir db/migrations \
    --baselines-dir db/baselines

# Specify PostgreSQL version for shadow database
pgmt init --dev-url postgres://localhost/myapp_dev --auto-shadow --shadow-pg-version 14

# Re-initialize with fresh config
pgmt init --dev-url postgres://localhost/newdb --fresh

pgmt apply

Apply schema files to the development database.

pgmt apply [OPTIONS]

Options:

--dry-run                     # Preview changes without applying
--force                       # Apply all changes without confirmation
--safe-only                   # Apply only safe changes, skip destructive
--require-approval            # Fail if destructive changes exist
--watch                       # Watch for file changes

Default behavior:

In terminal (interactive): Auto-apply safe changes, prompt for destructive
In CI/pipes (non-interactive): Fail with exit code 2 if destructive changes exist

Exit codes:

0: Success (or no changes needed)
1: Error
2: Destructive changes exist (in --require-approval mode or non-interactive)

Examples:

pgmt apply                    # Interactive - prompts when needed
pgmt apply --watch            # Watch mode - shows which file changed
pgmt apply --dry-run          # Preview only
pgmt apply --force            # Apply all without prompts
pgmt apply --safe-only        # Skip destructive changes

# CI/CD usage:
pgmt apply                    # Fails (exit 2) if destructive ops exist
pgmt apply --force            # Forces all changes in CI

pgmt diff

Compare schema files against the development database. Shows what pgmt apply would do.

pgmt diff [OPTIONS]

Options:

--format <FORMAT>             # detailed | summary | sql | json
--output-sql <FILE>           # Save SQL to file

Examples:

pgmt diff                     # Detailed comparison
pgmt diff --format summary    # Quick overview
pgmt diff --format sql        # SQL to sync

Exit codes: 0 = no differences, 1 = differences found

pgmt migrate new

Generate a new migration based on schema changes.

pgmt migrate new [DESCRIPTION] [OPTIONS]

Options:

--create-baseline             # Create baseline alongside migration

Examples:

pgmt migrate new "add users table"
pgmt migrate new "v2.0 release" --create-baseline
pgmt migrate new                  # Interactive (prompts for description)

pgmt migrate update

Regenerate a migration after schema changes or when your branch is behind.

pgmt migrate update [VERSION] [OPTIONS]

Arguments:

VERSION                       # Migration version (e.g., 1234567890, V1234567890, or partial 123456)
                              # If omitted, updates the latest migration

Options:

--dry-run                     # Preview without updating
--backup                      # Create .bak file before updating

Examples:

pgmt migrate update 1734567890    # Update specific migration (V prefix also accepted)
pgmt migrate update --dry-run     # Preview
pgmt migrate update --backup      # Update with backup

Note: This regenerates the migration from scratch. Manual edits will be lost.

pgmt migrate apply

Apply migrations to a target database.

pgmt migrate apply [OPTIONS]

Options:

--target-url <URL>            # Target database (required unless configured)

Examples:

pgmt migrate apply --target-url postgres://prod/myapp
pgmt migrate apply            # Uses target_url from pgmt.yaml

pgmt migrate status

Show migration status for a target database.

pgmt migrate status [OPTIONS]

Options:

--target-url <URL>            # Target database

Example output:

Applied:
  1734500000 - create_users (applied: 2024-12-18 10:00)
  1734510000 - add_posts (applied: 2024-12-18 11:00)

Pending:
  1734520000_add_comments.sql

pgmt migrate validate

Validate that migrations produce the expected schema. Use in CI to catch missing migrations.

pgmt migrate validate [OPTIONS]

Options:

--format <FORMAT>             # human | json
--verbose                     # Detailed output

Examples:

pgmt migrate validate
pgmt migrate validate --format json

Exit codes: 0 = valid, 1 = mismatch

pgmt migrate diff

Detect drift between schema files and target database.

pgmt migrate diff [OPTIONS]

Options:

--format <FORMAT>             # detailed | summary | sql | json
--output-sql <FILE>           # Save remediation SQL to file
--target-url <URL>            # Target database

Examples:

pgmt migrate diff --target-url postgres://prod/myapp
pgmt migrate diff --format sql --output-sql fix-drift.sql

Exit codes: 0 = no drift, 1 = drift detected

pgmt migrate baseline

Create a baseline from current schema files. By default, deletes all existing migrations and old baselines since the baseline supersedes them.

pgmt migrate baseline [OPTIONS]

Options:

--force                       # Skip baseline validation
--keep-migrations             # Don't delete old migrations
--dry-run                     # Preview what would happen

Examples:

pgmt migrate baseline                      # Baseline + clean up migrations
pgmt migrate baseline --keep-migrations    # Baseline only, keep migrations
pgmt migrate baseline --dry-run            # Preview what would be deleted

pgmt migrate baseline list

List existing baselines.

pgmt migrate baseline list

pgmt debug dependencies

Analyze object dependencies from both PostgreSQL introspection and -- require: headers. Useful for troubleshooting dependency ordering issues.

pgmt debug dependencies [OPTIONS]

Options:

--format <FORMAT>             # json | text (default: json)
--object <NAME>               # Filter to specific object

Examples:

pgmt debug dependencies                         # JSON output
pgmt debug dependencies --format text           # Human-readable
pgmt debug dependencies --object public.users   # Filter to one object

Output includes:

All tracked objects and their types
File-to-object mappings (which file defines which objects)
File dependencies from -- require: headers
Dependency graph showing what each object depends on

pgmt config

Manage configuration.

pgmt config get <KEY>              # Get value
pgmt config set <KEY> <VALUE>      # Set value
pgmt config list                   # List all values
pgmt config validate               # Validate config file

Examples:

pgmt config get databases.dev
pgmt config set databases.dev postgres://localhost/myapp
pgmt config list --format json

Environment Variables

PGMT_CONFIG_FILE              # Override config file location
PGMT_DEV_URL                  # Override dev database URL
PGMT_SHADOW_URL               # Override shadow database URL
PGMT_TARGET_URL               # Override target database URL

Exit Codes

General:

Code	Meaning
0	Success
1	Error (general)

Command-specific:

Command	Code	Meaning
`pgmt apply`	2	Destructive operations exist (in non-interactive/`--require-approval` mode)
`pgmt diff`	1	Differences detected
`pgmt migrate diff`	1	Drift detected
`pgmt migrate validate`	1	Validation failed