gh pr checks
See CI status without the browser
gh pr checks shows every status check and GitHub Actions run attached to a pull request, with a pass/fail summary. Add --watch to stream results live in your terminal until CI finishes — no more refreshing the PR page.
gh pr checks 123 --watchSyntax
gh pr checks [<number> | <url> | <branch>] [flags]Examples
Show checks for the current branch's PR
gh pr checksWatch checks update live until they finish
gh pr checks 123 --watchWatch and stop on the first failure
gh pr checks 123 --watch --fail-fastOnly required checks
gh pr checks 123 --requiredOpen the checks tab in the browser
gh pr checks 123 --webOptions & flags
| Flag | What it does |
|---|---|
| --watch | Watch checks until they all finish. |
| --fail-fast | Exit as soon as a check fails (implies --watch). |
| -i, --interval | Refresh interval in seconds when watching (default 10). |
| --required | Only show required checks. |
| --json | Output check data as JSON. |
| -w, --web | Open the checks page on github.com. |
How to use gh pr checks, step by step
- Run
gh pr checksfrom your PR branch to see the current status. - Add
--watchto keep the terminal updated until CI completes. - gh exits non-zero if any check fails, so you can gate scripts on it.
- Follow the printed link to inspect a failing run, or use
gh run view.
Common errors and fixes
no checks reported on the 'my-branch' branch
No CI has run yet, or no workflows are configured for this branch. Confirm your Actions or status-check integration is enabled.
no pull requests found for branch 'my-branch'
Open a PR first with gh pr create, or pass an explicit PR number.
Related commands
Frequently asked questions
How do I watch CI checks live from the terminal?
Run gh pr checks <number> --watch. gh refreshes the status in place every few seconds and returns control when every check has finished, exiting non-zero if any failed.
Can I use gh pr checks in a script?
Yes. It returns a non-zero exit code when checks fail, so you can write: gh pr checks 123 --watch && gh pr merge 123 --squash to merge only after CI is green.
How do I see only required checks?
Add the --required flag to hide informational checks and show only those that gate merging.