Mergify CLI
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 tokenautomatically; override with env vars or flags when scripting. - Built for pipelines. Logs to stderr, structured
--jsonoutput 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 putmergify.exeanywhere on yourPATH. - Linux / macOS — download
mergify-<version>-<target>.tar.gz(e.g.mergify-2026.4.23.1-aarch64-apple-darwin.tar.gz), extract withtar -xzf, and put the resultingmergifybinary anywhere on yourPATH.
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 |
Mergify application keys come in two classes, and a few commands will not
accept the narrower one. A ci key is scoped to what a CI job does — trace
upload, ci scopes-send, quarantine evaluation and the quarantine list.
Reading test health (mergify tests show) and changing the quarantine
(mergify tests quarantines add / remove) need an admin key or a GitHub
PAT, and answer a ci key with 403 Forbidden. Note that GITHUB_TOKEN
inside GitHub Actions is the ephemeral installation token, not a PAT, and
does not reach the Mergify API.
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 auth— Sign in to Mergify and manage the stored credential (login,logout,status).mergify stack— Create and maintain stacked pull requests. Docsmergify queue— Inspect and control the merge queue. Docsmergify 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. Docsmergify tests— Look up test health and manage the flaky-test quarantine. Docsmergify freeze— Schedule merge freezes for release windows and maintenance. Docsmergify config— Validate your configuration and simulate actions before you merge. Docsmergify 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 or credentials missing, unparseable, or failing validation (including "not logged in"). |
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.
Metadata
Release files for mergify-cli 2026.9.10.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| mergify_cli-2026.9.10.1.tar.gz | 562.2 kB | Details |
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| mergify_cli-2026.9.10.1-py3-none-win_amd64.whl | Python 3 | none | Windows x86-64 | Details |
| mergify_cli-2026.9.10.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl | Python 3 | none | Linux glibc 2.17+ x86-64 | Details |
| mergify_cli-2026.9.10.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl | Python 3 | none | Linux glibc 2.17+ ARM64 | Details |
| mergify_cli-2026.9.10.1-py3-none-macosx_11_0_arm64.whl | Python 3 | none | macOS 11.0+ ARM64 | Details |
| mergify_cli-2026.9.10.1-py3-none-macosx_10_12_x86_64.whl | Python 3 | none | macOS 10.12+ x86-64 | Details |
Total release size: 32.2 MB
Release files / mergify_cli-2026.9.10.1.tar.gz
| Download URL | mergify_cli-2026.9.10.1.tar.gz |
|---|---|
| Size | 562.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fb4f66f5b4db2766552f26d6873172c91addce862f5448618320692d3f8aa8db
|
|
BLAKE2b-256 checksum How to use checksums |
c180cfc891495e1d7b9d36d72490bea5f7c69e5a140294cb700e8a66cf60815d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 11, 2026.
Transparency logRelease files / mergify_cli-2026.9.10.1-py3-none-win_amd64.whl
| Download URL | mergify_cli-2026.9.10.1-py3-none-win_amd64.whl |
|---|---|
| Size | 6.1 MB |
| Tags | Python 3 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
c73d65395fa9e7fef75efc216ccc772483828dc9cf3b93c755c902b8aa29e088
|
|
BLAKE2b-256 checksum How to use checksums |
16dccfbb7b7f2bf811d150a93bf3f2cd77fedb8ba1f71d5ab6ce211d93412645
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 11, 2026.
Transparency logRelease files / mergify_cli-2026.9.10.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | mergify_cli-2026.9.10.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 7.1 MB |
| Tags | Linux glibc 2.17+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
7e1160911df28cb2307cb3e3d04374a8e231e8b6176f5a543893247d0941f8ad
|
|
BLAKE2b-256 checksum How to use checksums |
e9b448ed8ec1c9130cb0ab31cec09eaf8f92654632489bc5792caedfccd71ef7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 11, 2026.
Transparency logRelease files / mergify_cli-2026.9.10.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | mergify_cli-2026.9.10.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 6.7 MB |
| Tags | Linux glibc 2.17+ ARM64 Python 3 |
|
SHA-256 checksum How to use checksums |
ab93f02f3b21b0764c4ddf3f6fe61e0a42f4e15ba882356f42939202f0619d16
|
|
BLAKE2b-256 checksum How to use checksums |
b2f207c2c10a326afd6993cdcfd51cf46859daf6781c6d91fefb060d797999dd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 11, 2026.
Transparency logRelease files / mergify_cli-2026.9.10.1-py3-none-macosx_11_0_arm64.whl
| Download URL | mergify_cli-2026.9.10.1-py3-none-macosx_11_0_arm64.whl |
|---|---|
| Size | 5.7 MB |
| Tags | Python 3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
5c1506b03c7f197a23c5c1118a70009b6a39794426f6607bd2b19753cc702ca2
|
|
BLAKE2b-256 checksum How to use checksums |
9ad1cc4692377bcab369ec2b50c466b3be8058f5a4ce17a89ba74b4748ca84b6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 11, 2026.
Transparency logRelease files / mergify_cli-2026.9.10.1-py3-none-macosx_10_12_x86_64.whl
| Download URL | mergify_cli-2026.9.10.1-py3-none-macosx_10_12_x86_64.whl |
|---|---|
| Size | 6.0 MB |
| Tags | Python 3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
2b7d35d98a3e37300f80b8ef16340499d6619054850088625e36c2ca6c67219b
|
|
BLAKE2b-256 checksum How to use checksums |
179af84ac5a9b364160c8756a6228fda1c701584a469a9afc503e627d3ef7270
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 11, 2026.
Transparency log
