---
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, authentication, and the exit codes
commands return; 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.

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:

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

Each command's entry in the [CLI reference](/cli) lists the options it accepts,
`--token` included.

### GitHub token

Stacks commands act on pull requests through the GitHub API and need a GitHub
token specifically. If you have the [GitHub CLI](https://cli.github.com/)
(`gh`) installed and authenticated, the Mergify CLI uses its token
automatically. 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 set it as an environment variable:

```bash
export GITHUB_TOKEN=your_token_here
```

### Mergify token

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](https://dashboard.mergify.com) and set it as
`MERGIFY_TOKEN`:

```bash
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](/api/usage#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.

## Exit Codes

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:

| Code | Name | Meaning |
|------|------|---------|
| `0` | `Success` | Command completed successfully. |
| `1` | `GenericError` | Unclassified runtime failure (I/O error, bug, or captured panic). |
| `3` | `StackNotFound` | Stack, branch, or commit not found. |
| `4` | `Conflict` | Rebase or merge conflict. |
| `5` | `GitHubApiError` | GitHub API request failed. |
| `6` | `MergifyApiError` | Mergify API request failed. |
| `7` | `InvalidState` | CLI invariant violated (e.g. command run outside a valid context). |
| `8` | `ConfigurationError` | Configuration file missing, unparseable, or failing validation. |