CLI Installation & Authentication

The Mergify CLI lets you interact with Mergify features directly from your terminal. This page covers installation, authentication, and the exit codes commands return; 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.

Most commands that need one resolve it in the same order: the --token option, then the MERGIFY_TOKEN environment variable, then GITHUB_TOKEN. Stacks commands fall back once more to gh auth token. There is no global --token on mergify itself, so pass it to the subcommand:

mergify <command> --token your_token_here

Each command’s entry in the CLI reference lists the options it accepts, --token included.

Stacks commands act on pull requests through the GitHub API and need a GitHub token specifically. If you have the GitHub CLI (gh) installed and authenticated, the Mergify CLI uses its token automatically. No extra configuration needed.

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

export GITHUB_TOKEN=your_token_here

Commands that call the Mergify API, such as mergify queue, mergify events, mergify freeze, and mergify ci, accept a Mergify application key. Create one from your dashboard and set it as MERGIFY_TOKEN:

export MERGIFY_TOKEN=your_token_here

An application key carries either the admin scope or the ci scope, and belongs to a GitHub account rather than to a single repository. See Application Key Scopes for what each one covers. The Mergify API also accepts a GitHub personal access token, so one GitHub token serves most commands. Two exceptions need a ci application key. mergify ci junit-process (and the deprecated mergify ci junit-upload) never falls back to GITHUB_TOKEN. mergify ci scopes-send reads GITHUB_TOKEN, but posts to an endpoint that rejects anything other than a ci key.

The CLI reports failures with these exit codes, so a CI job can tell a conflict apart from an API failure without parsing the output: