CLI Installation & Authentication

The Mergify CLI lets you interact with Mergify features directly from your terminal. This page covers installation and authentication; for the commands themselves, see the CLI reference.

On macOS, the recommended way to install the CLI is through Mergify’s Homebrew tap:

brew install mergifyio/tap/mergify-cli

Upgrade with brew upgrade mergify-cli.

On Linux, or on macOS if you’d rather not use Homebrew, install with the official script:

curl -fsSL https://raw.githubusercontent.com/Mergifyio/mergify-cli/main/install.sh | sh

This installs mergify to ~/.local/bin. Set MERGIFY_INSTALL_DIR to pick a different location, or MERGIFY_VERSION to pin a specific release:

curl -fsSL https://raw.githubusercontent.com/Mergifyio/mergify-cli/main/install.sh | MERGIFY_INSTALL_DIR="$HOME/bin" sh

Once installed this way, upgrade with mergify self-update.

Download mergify-<version>-x86_64-pc-windows-msvc.zip from the latest release, extract it, and put mergify.exe anywhere on your PATH.

To install the CLI in a GitHub Actions workflow, use the Mergifyio/setup-cli action. It downloads the prebuilt mergify binary, verifies it against the release SHA256SUMS, and adds it to the PATH. No Python or extra toolchain is required, and it runs on Linux and macOS runners.

- uses: Mergifyio/setup-cli@v2
- run: mergify --version

By default the action installs a pinned version, which keeps your CI reproducible. Set the mergify_cli_version input to latest to install the newest release instead. The action also exposes the version it actually installed as the mergify_cli_version output:

- uses: Mergifyio/setup-cli@v2
  id: setup-cli
  with:
    mergify_cli_version: latest

- run: echo "Installed mergify-cli ${{ steps.setup-cli.outputs.mergify_cli_version }}"

The CLI needs an authentication token to interact with your repositories. Depending on the command, this can be a GitHub token or a Mergify API token.

If you have the GitHub CLI (gh) installed and authenticated, the Mergify CLI automatically uses its token for commands that require GitHub access. No extra configuration needed.

Otherwise, create a personal access token and either set it as an environment variable:

export GITHUB_TOKEN=your_token_here

Or pass it directly to any command:

mergify --token your_token_here <command>

Each command lists the authentication and other options it accepts under its Global options in the CLI reference.