CLI

The migracheck CLI lets you analyze migration scripts from your terminal or CI pipeline. It supports Flyway and Liquibase, integrates with GitHub and GitLab, and can collect metadata snapshots from your Aurora MySQL cluster for richer risk analysis.

Installation

macOS / Linux

curl -fsSL https://github.com/beachygreg/migracheck-releases/releases/latest/download/install.sh | bash

Manual download

Download the latest release for your platform from the releases page, extract the archive, and place the migracheck binary somewhere on your PATH.

Verify installation

migracheck --version

Authentication

Interactive login

migracheck auth login

Prompts you to paste an API key. Generate one in the web UI under your organization's API Keys page, then paste it when prompted (input is hidden). The key is stored in ~/.config/migracheck/config.yml (mode 0600).

API key (CI / non-interactive)

Set the MIGRACHECK_API_KEY environment variable:

export MIGRACHECK_API_KEY=mck_live_...

Generate an API key in the web UI under your organization's API Keys page. The environment variable takes precedence over the stored config file.

Check your session

migracheck auth whoami

Project configuration

Create a .migra.yml file in your repository root to set defaults. All flags can override these values.

# .migra.yml
project-id: "42"
migration-tool: flyway
aurora-version: "8.0.28"
replica-count: 2
fail-on:
  - critical
  - high
peak-traffic-window: "09:00-22:00 UTC"

Analyzing a migration

migracheck analyze --project-id 42 --file V5__add_index.sql

If you have a .migra.yml file, you only need the --file flag:

migracheck analyze --file V5__add_index.sql

Flags

Flag	Description
`--project-id`	Project ID (required, or set in `.migra.yml`).
`--file`	Path to the migration script (required).
`--snapshot-id`	Snapshot ID for metadata context. Defaults to the latest snapshot.
`--migration-tool`	`flyway` or `liquibase`.
`--aurora-version`	Aurora MySQL version, e.g. `8.0.28`.
`--replica-count`	Number of read replicas.
`--peak-traffic-window`	e.g. `'09:00-22:00 UTC'`.
`--instance-class`	Aurora instance class, e.g. `db.r6g.2xlarge`.
`--fail-on`	Comma-separated severities that trigger exit code 2.
`--json`	Output the full analysis as JSON instead of a formatted report.
`--no-color`	Disable ANSI color output.
`--github-report`	Post a PR comment and check run (GitHub Actions only).
`--gitlab-report`	Post an MR note and commit status (GitLab CI only).

Exit codes

0 — analysis complete, no threshold exceeded.
1 — execution error (auth, network, invalid input).
2 — severity threshold exceeded (only when --fail-on is set).

Metadata snapshots

Snapshots capture your production schema metadata (table sizes, row counts, indexes, foreign keys) so the risk engine can give more accurate assessments.

Collect and upload in one step

migracheck snapshot collect-and-upload \
  --project-id 42 \
  --dsn "user:pass@tcp(aurora-host:3306)/mydb"

Collect locally, upload later

# Collect to a file
migracheck snapshot collect \
  --dsn "user:pass@tcp(aurora-host:3306)/mydb" \
  --out snapshot.json

# Upload
migracheck snapshot upload \
  --project-id 42 \
  --file snapshot.json

List snapshots

migracheck snapshot list --project-id 42

Other commands

Projects

# List projects in your organization
migracheck project list --org-id 7

# Create a new project
migracheck project create --org-id 7 --name "payments-db"

# Show project details
migracheck project show --org-id 7 --project-id 42

Self-update

migracheck update

CI/CD usage

The CLI is designed for CI. Set MIGRACHECK_API_KEY as an environment variable and use --fail-on to gate deployments:

migracheck analyze \
  --file migration.sql \
  --fail-on critical,high \
  --no-color

For GitHub Actions, see the GitHub Actions docs which wraps the CLI in a reusable composite action with automatic PR comments and check runs.