CLI reference
Use migrate --help or migrate <command> --help to confirm the flags in your installed version. Use migrate version to identify the binary.
Global flags
| Flag | Default | Meaning |
|---|---|---|
--config, -c | Automatic search | Select a file; see search order when omitted |
--working-dir, -w | Current directory | Resolve config from this directory and override migration working directory |
--non-interactive | false | Fail instead of requesting secrets or approval for unknown SSH host keys |
new config
migrate new config [filename] [--format yaml|json] [--multi] [--shards N] [--ssh-tunnel] [--force]
migrate new config shards.yml --multi --shards 4
migrate new config shards-ssh.yml --multi --ssh-tunnel --proxy socks5Generate migration_config.yml. Use --multi for multiple databases, --shards N to set how many, --ssh-tunnel to add SSH settings and --proxy socks5|http to add an SSH upstream proxy. Choose SSH authentication with --ssh-auth agent|private_key|password. --shards N requires --multi and a positive count, numbered from 0. --proxy requires --ssh-tunnel. --force permits overwriting an existing file. A .json filename or --format json selects JSON output. Run migrate new config --help for all options; see configuration for common setups.
new version
migrate new version <description> [-v <version>] [--format sql|js|ts|mjs]Create a version file in the migration directory. --version / -v overrides the generated version; --format defaults to sql. Quote descriptions with spaces, as in migrate new version "init users"; spaces become underscores in filenames. See SQL migrations or script migrations.
Multiple databases
With data_sources configured, create/baseline/status/up/down visit every source. Each accepts --parallel N (default 8). One failure does not cancel other targets; results are grouped by source and any failure yields a nonzero exit. See multiple databases for shared files and SSH settings. status --output json returns results sorted by data-source name. Each item has data_source and status, plus migrations on success or error on failure.
create
migrate createIdempotently create the history table. User migration files are not applied.
baseline
migrate baselineRecord pending migrations as baseline without executing them. First confirm the existing database already matches those files. See History and baseline.
up
migrate up [--dry-run]Apply pending versions in order. Dry-run prints SQL or script plans without executing user migrations; it may connect to read history. See Apply migrations.
down
migrate down <to-version> [--dry-run]
migrate down --all [--dry-run]Reverse versions above the target, keeping the target applied, or reverse all applied versions. The target and --all are mutually exclusive; one is required. See Rollback.
status
migrate status [--output table|json]Compare files and database history. --output / -o defaults to table. See status values.
capabilities
migrate capabilities [--output text|json]Report build formats, aliases, script verification and transaction limits without reading config or connecting to a database. --output / -o defaults to text. See Supported databases.
version
migrate versionPrint the CLI version without reading config or opening a database connection. This reports the tool version, not the database's latest migration version.