---
title: CLI Installation & Authentication
description: Install the Mergify CLI and authenticate it to manage your merge queue, freezes, and stacked pull requests from the terminal.
---

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](/cli).

## Installation

### macOS (Homebrew)

On macOS, the recommended way to install the CLI is through Mergify's
[Homebrew tap](https://github.com/Mergifyio/homebrew-tap):

```bash
brew install mergifyio/tap/mergify-cli
```

Upgrade with `brew upgrade mergify-cli`.

### Linux and macOS (install script)

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

<CliInstall />

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

```bash
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`.

### Windows

Download `mergify-<version>-x86_64-pc-windows-msvc.zip` from the
[latest release](https://github.com/Mergifyio/mergify-cli/releases/latest),
extract it, and put `mergify.exe` anywhere on your `PATH`.

### GitHub Actions

To install the CLI in a GitHub Actions workflow, use the
[`Mergifyio/setup-cli`](https://github.com/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.

```yaml
- 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:

```yaml
- 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 }}"
```

:::tip
  Pinning a specific version is the default and works well with
  [Renovate](https://docs.renovatebot.com/), which can open pull requests to
  bump the version as new releases ship. Use `latest` only when you always want
  the most recent build.
:::

## Authentication

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](https://cli.github.com/) (`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](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
and either set it as an environment variable:

```bash
export GITHUB_TOKEN=your_token_here
```

Or pass it directly to any command:

```bash
mergify --token your_token_here <command>
```

Each command lists the authentication and other options it accepts under its
**Global options** in the [CLI reference](/cli).