Skip to main content

Mergify CLI

CI Latest release Documentation License

Drive Mergify from your terminal and CI pipelines: stacked pull requests, the merge queue, CI Insights, scheduled freezes, and configuration — all from a single self-contained binary that reuses your existing GitHub (gh) login.

mergify stack push          # turn your local commits into stacked PRs
mergify queue status        # inspect the merge queue
mergify ci junit-process report.xml   # upload test results to CI Insights
  • One static binary. No runtime, no dependencies — drop it on a developer laptop or a CI runner and go.
  • Zero-config auth. Picks up gh auth token automatically; override with env vars or flags when scripting.
  • Built for pipelines. Logs to stderr, structured --json output on read commands, and stable exit codes for scripts and runbooks.
  • Cross-platform. Linux, macOS (x86_64 + aarch64), and Windows.

Installation

Homebrew (recommended for macOS)

brew install mergifyio/tap/mergify-cli

The fully-qualified name taps and installs in one step. Upgrade with brew upgrade mergify-cli — not mergify self-update, which overwrites the Homebrew-managed binary. See the tap for tap-trust and short-name details.

Install script (recommended for Linux; also macOS — x86_64 and aarch64)

curl -fsSL https://raw.githubusercontent.com/Mergifyio/mergify-cli/main/install.sh | sh

Installs to ~/.local/bin/mergify. Override with MERGIFY_INSTALL_DIR=/usr/local/bin or pin a version with MERGIFY_VERSION=<version>. Upgrade with mergify self-update.

Manual download (Windows, or to bypass the script)

Grab the matching archive from the latest release:

  • Windows — download mergify-<version>-x86_64-pc-windows-msvc.zip, extract it, and put mergify.exe anywhere on your PATH.
  • Linux / macOS — download mergify-<version>-<target>.tar.gz (e.g. mergify-2026.4.23.1-aarch64-apple-darwin.tar.gz), extract with tar -xzf, and put the resulting mergify binary anywhere on your PATH.

Verify against SHA256SUMS from the same release if you care.

Authentication

Most commands talk to the Mergify and GitHub APIs and need a token. The CLI resolves credentials and target repository in this order, so an authenticated gh is usually all you need:

What --flag then env then
Token --token / -t MERGIFY_TOKEN, GITHUB_TOKEN gh auth token
Repository --repository / -r GITHUB_REPOSITORY git remote (origin)
API URL --api-url / -u MERGIFY_API_URL https://api.mergify.com

See the authentication guide for details.

Quick start

# Stacked pull requests — one PR per commit, kept in sync
mergify stack setup                # once per repo: install the git hooks the stack needs
mergify stack push                 # push commits and create/update their PRs
mergify stack list                 # show the stack and its PR status
mergify stack sync                 # rebase the stack onto its trunk

# Merge queue
mergify queue status               # current queue state for the repo
mergify queue status --json        # same, as machine-readable JSON

# CI Insights — from inside your pipeline
mergify ci junit-process report.xml --test-language python

# Configuration
mergify config validate            # check .mergify.yml against the schema

Run mergify --help for the full command list and mergify <command> --help for any command's flags.

Commands

Every command group maps to a section of the CLI reference.

  • mergify stack — Create and maintain stacked pull requests. Docs
  • mergify queue — Inspect and control the merge queue. Docs
  • mergify events — Browse the events Mergify recorded for the repository or one pull request, as a timeline or JSON.
  • mergify ci — Send JUnit results and pull request scopes from any CI provider. Docs
  • mergify tests — Look up test health and manage the flaky-test quarantine. Docs
  • mergify freeze — Schedule merge freezes for release windows and maintenance. Docs
  • mergify config — Validate your configuration and simulate actions before you merge. Docs
  • mergify self-update — Update the CLI to the latest release.
  • mergify completions <shell> — Print a shell completion script (see below).

Run mergify <command> --help for a group's subcommands and flags.

Shell completions

Generate a completion script for your shell — bash, zsh, fish, elvish, or powershell:

# zsh — write to a directory on your $fpath
mergify completions zsh > ~/.zfunc/_mergify

# bash — load in your current session (add to ~/.bashrc to persist)
source <(mergify completions bash)

# fish
mergify completions fish > ~/.config/fish/completions/mergify.fish

Global options

These are accepted on every command:

Flag Description
-v, --verbose Increase log verbosity: -v info, -vv debug, -vvv trace. Logs go to stderr so stdout stays pipeable.
--debug Shorthand for at least debug-level logging (like -vv).
--color <auto|always|never> When to colorize terminal output.

Environment variables

Variable Effect
MERGIFY_TOKEN, GITHUB_TOKEN API token (falls back to gh auth token).
GITHUB_REPOSITORY Default owner/repo when --repository is omitted.
MERGIFY_API_URL API base URL (default https://api.mergify.com).
RUST_LOG Fine-grained log filtering; overrides --verbose.
NO_COLOR Disable colored output.
MERGIFY_INSTALL_DIR, MERGIFY_VERSION Install-script target directory / pinned version.

Exit codes

Commands return stable exit codes so scripts and runbooks can branch on them:

Code Meaning
0 Success.
1 Unclassified runtime failure (I/O error, bug, or captured panic).
2 Argument parsing / usage error.
3 Stack, branch, or commit not found.
4 Rebase or merge conflict.
5 GitHub API request failed.
6 Mergify API request failed.
7 CLI invariant violated (e.g. run outside a valid context).
8 Configuration missing, unparseable, or failing validation.

AI Agent Skills

Mergify CLI provides AI skills for managing stacked PRs and Git workflows, compatible with Claude Code, Cursor, and many other AI agents.

Install via npx (all agents):

npx skills add Mergifyio/mergify-cli

Install as a Claude Code plugin:

/plugin install mergify@claude-plugins-official

Documentation

Full reference and guides live at docs.mergify.com/cli.

Contributing

Contributions are welcome — open an issue or a pull request. The workspace is a Rust monorepo; see AGENTS.md for the crate layout, build, and test workflow.

License

Apache License 2.0 — see LICENSE.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mergify_cli-2026.8.7.1.tar.gz (475.5 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

mergify_cli-2026.8.7.1-py3-none-win_amd64.whl (5.9 MB view details)

Uploaded Python 3Windows x86-64

mergify_cli-2026.8.7.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (5.9 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64

mergify_cli-2026.8.7.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (5.5 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

mergify_cli-2026.8.7.1-py3-none-macosx_11_0_arm64.whl (5.5 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

mergify_cli-2026.8.7.1-py3-none-macosx_10_12_x86_64.whl (5.9 MB view details)

Uploaded Python 3macOS 10.12+ x86-64

File details

Details for the file mergify_cli-2026.8.7.1.tar.gz.

File metadata

  • Download URL: mergify_cli-2026.8.7.1.tar.gz
  • Upload date:
  • Size: 475.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for mergify_cli-2026.8.7.1.tar.gz
Algorithm Hash digest
SHA256 86708a4d34568f1fd0340f7d0432766eb3c3fdd8aa0f63c727c3c49601953434
MD5 b45d9e2824b63acfdf88f8daaee4cebe
BLAKE2b-256 df5e2b1a24e17b81453c9c33fce50629505f7ef33f4f80262c173fe6df16211f

See more details on using hashes here.

Provenance

The following attestation bundles were made for mergify_cli-2026.8.7.1.tar.gz:

Publisher: release.yml on Mergifyio/mergify-cli

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mergify_cli-2026.8.7.1-py3-none-win_amd64.whl.

File metadata

File hashes

Hashes for mergify_cli-2026.8.7.1-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 0f5d733fab1ecdf3a0ae90cc57cc8098ff6bbc0e47237529c9b24e7d527c9141
MD5 4a18f77a1dfe98ffd3b80b5ce486940c
BLAKE2b-256 76064e7cece93681ce3a6b28f568e818c9d329ad239dad63f9e9220f12fad02c

See more details on using hashes here.

Provenance

The following attestation bundles were made for mergify_cli-2026.8.7.1-py3-none-win_amd64.whl:

Publisher: release.yml on Mergifyio/mergify-cli

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mergify_cli-2026.8.7.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for mergify_cli-2026.8.7.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 99d3693c4b77b53d863d710d0f790ee6c014e6b9dc279f068b60fb4b86f7c3e5
MD5 99700e96e54af8ad6e5cdac22f00af01
BLAKE2b-256 5f2eca4beef0b4630e74e279e162dfb2e18490dc7e8e78f10295b99b8991c574

See more details on using hashes here.

Provenance

The following attestation bundles were made for mergify_cli-2026.8.7.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on Mergifyio/mergify-cli

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mergify_cli-2026.8.7.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for mergify_cli-2026.8.7.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 a44f97094472d5564b745c50bd8694c685f15d4b8e7bb92b1969424bf8835479
MD5 edfd8ae84a81f01375d41d4f5aecb6cf
BLAKE2b-256 87b81c843eb9da8a620942e6df960d7f5fa43bde096fb48ab215534a04d45cf9

See more details on using hashes here.

Provenance

The following attestation bundles were made for mergify_cli-2026.8.7.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yml on Mergifyio/mergify-cli

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mergify_cli-2026.8.7.1-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for mergify_cli-2026.8.7.1-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 5eddbbe3203f4497f14f863ee413273437be0e3107a31af18461333c3fd2126e
MD5 bdc261d5a5b18019251cf7d146db7810
BLAKE2b-256 c50e149944fb0bca1b3b0342abeaa98d278fdb01144e4a49c69a587d63ad768f

See more details on using hashes here.

Provenance

The following attestation bundles were made for mergify_cli-2026.8.7.1-py3-none-macosx_11_0_arm64.whl:

Publisher: release.yml on Mergifyio/mergify-cli

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mergify_cli-2026.8.7.1-py3-none-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for mergify_cli-2026.8.7.1-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 2566f3c769b99d226884b35fcae8f3152f2bed8d8336550587e3685a7a61ef78
MD5 4112b2204743f020d9990c12aac864c0
BLAKE2b-256 653a7beb36721d114034fa3b33719677dd09b87983ead52383eec3c84fa7ca6a

See more details on using hashes here.

Provenance

The following attestation bundles were made for mergify_cli-2026.8.7.1-py3-none-macosx_10_12_x86_64.whl:

Publisher: release.yml on Mergifyio/mergify-cli

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page