CLI

The Mergify CLI lets you interact with Test Insights data from the terminal. It’s handy when you want to triage a failing test quickly, or when an AI coding agent needs to decide whether to retry, fix, or ignore a failure.

Search the Test Insights catalog by test name and print health, ratios, and the most recent failure context for each match.

mergify tests show -r owner/repo "tests/auth/test_login.py::test_login_timeout"

Names accept glob patterns (*, ?), and several can be passed in one call. Add --json for a machine-readable payload. Run mergify tests show --help for the full list of flags, and see the API reference for the underlying endpoints and response schemas.

The exit code reflects the worst health observed across the matched tests, so callers can branch without parsing output:

Exit code 2 is reserved for CLI argument errors.

The exit-code contract is designed to be chained from agents that ran a test, saw it fail, and need to decide what to do next.

if mergify tests show -r owner/repo "$FAILED_TEST" --json > /tmp/health.json; then
  status=0
else
  status=$?
fi

case $status in
  0) echo "Healthy or unknown: investigate as a real regression." ;;
  1) echo "Known flaky: retry before touching code." ;;
  6) echo "Broken: fix is required; skip the retry loop." ;;
esac

Add a skill or a prompt snippet that points the agent at the CLI:

When a test fails locally or in CI, before attempting a fix, run:

  mergify tests show -r OWNER/REPO --json "<failed-test-name>"

Then branch on the exit code:
- 0, non-empty payload → healthy in Mergify; investigate as a real
  regression.
- 0, empty payload → unknown to Mergify; treat as a new test or one on
  a non-default branch.
- 1 → known flaky. Rerun once; only investigate if it fails again.
- 6 → known broken (pre-existing). Surface to the user instead of
  attempting a fix.

In Cursor, add the same guidance to a project rule (.cursor/rules/test-triage.mdc) so it auto-loads in agent sessions.