Mergify CLI

Common errors

• mergify: command not found

  cause The `mergify-cli` package is not installed, or its installation directory is not in your system's PATH.
  fix Run `pip install mergify-cli`. If it's already installed, ensure your PATH environment variable includes the directory where pip installs executables (e.g., `~/.local/bin` on Linux/macOS or `Scripts` folder in Python install on Windows).

• Error: GitHub token not found. Please run 'mergify setup'.

  cause The Mergify CLI requires a GitHub Personal Access Token (PAT) for authentication, which was not found or is invalid.
  fix Run `mergify setup` interactively to configure your GitHub token, or set the `MERGIFY_TOKEN` environment variable manually (e.g., `export MERGIFY_TOKEN='ghp_YOUR_TOKEN'`). Ensure the token has sufficient scopes (e.g., `repo`, `workflow`).

• Error: Unknown command 'reviews'

  cause You are attempting to use a command (`reviews`) that has been removed from the Mergify CLI.
  fix The `reviews` command was removed in version `2026.3.11.1`. Consult the latest documentation or release notes for available commands. Do not use this command in new scripts or try to remove it from existing ones.

• Error: failed to checkout stack 'my-feature': no stack named 'my-feature' found

  cause The stack name provided to `mergify stack checkout` does not exist in your current repository context, or you mistyped the name. This can also happen if the stack was recently deleted or merged.
  fix Verify the correct name of the stack. Use `mergify stack status` to list active stacks or `git branch` to see local branches. Ensure you are in the correct repository.

Warnings

• breaking The `mergify stack github_action_auto_rebase` command has been removed.
  Fix: Review your CI/CD pipelines and scripts that relied on this specific command. If you were using it for rebasing stacks in GitHub Actions, you might need to adapt your workflow to use other `mergify stack` commands or native Git operations.
• breaking The `mergify reviews` command has been reverted and removed.
  Fix: Any automation or scripts that used `mergify reviews` will no longer function. Check release notes for alternative functionality or implement review management through other means.
• breaking The `mergify stack checkout` command now takes a positional `NAME` argument.
  Fix: Update scripts or muscle memory to use `mergify stack checkout <stack-name>` instead of previous invocation patterns. For example, `mergify stack checkout feature-branch`.
• gotcha Previous versions of `mergify stack push` could unintentionally delete similarly named branches.
  Fix: This issue was fixed in version `2026.3.13.1`. Ensure you are on the latest version of `mergify-cli` to prevent this behavior. If on an older version, carefully review your stack names before pushing.

Install

• pip install mergify-cli Install via pip

Quickstart

The Mergify CLI is primarily used as a command-line tool. The quickstart guides you through installation, initial setup (including GitHub token configuration), and common `stack` commands like `push` and `status`. Run `mergify setup` interactively for the easiest initial configuration.

# 1. Install mergify-cli
pip install mergify-cli

# 2. Set up your GitHub token (replaces MERGIFY_TOKEN with your actual token)
#    or run `mergify setup` for interactive configuration.
export MERGIFY_TOKEN="ghp_YOUR_GITHUB_TOKEN"

# 3. Initialize Mergify CLI in your Git repository
#    This will guide you through connecting to GitHub.
mergify setup

# 4. Create and push a stacked pull request
#    (Assuming you have local commits on a feature branch)
mergify stack push

# 5. Check the status of your current stack
mergify stack status

# 6. Checkout a specific stack by name
# mergify stack checkout my-feature-stack