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.

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 lists the authentication and other options it accepts under its Global options in the CLI reference.

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 can serve every command except mergify ci junit-process: it needs a ci application key, and it is the one command that never falls back to GITHUB_TOKEN.