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.

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.