gh run watch
Follow an Actions run in real time
gh run watch streams the progress of a GitHub Actions run in your terminal, updating each job's status until the run finishes. Combine it with --exit-status to fail scripts on a broken build, so you can gate deploys on a green pipeline.
gh run watchSyntax
gh run watch [<run-id>] [flags]Examples
Pick a recent run and watch it
gh run watchWatch a specific run by ID
gh run watch 8123456789Fail the shell if the run fails
gh run watch 8123456789 --exit-statusCompact single-line output
gh run watch --compactCustom refresh interval
gh run watch 8123456789 --interval 5Options & flags
| Flag | What it does |
|---|---|
| --exit-status | Exit with a non-zero code if the run fails. |
| -i, --interval | Refresh interval in seconds (default 3). |
| --compact | Show only the most relevant, in-progress steps. |
How to use gh run watch, step by step
- List recent runs with
gh run listto grab an ID. - Run
gh run watch <run-id>, or plaingh run watchto choose interactively. - gh refreshes each job's status until the run completes.
- Add
--exit-statusso CI scripts fail on a failed run.
Common errors and fixes
no runs found
No recent workflow runs exist. Trigger one with gh workflow run first, or push a commit that starts CI.
run 8123456789 has already completed
The run is finished, so there's nothing live to watch. Inspect it with gh run view 8123456789 --log.
Related commands
Frequently asked questions
How do I watch a GitHub Actions run from the terminal?
Run gh run watch to pick a recent run interactively, or gh run watch <run-id> for a specific one. gh streams live status until the run finishes.
How do I make a script fail when a workflow run fails?
Add --exit-status: gh run watch <run-id> --exit-status returns a non-zero exit code on failure, so you can chain it before a deploy step.
Can I change how often gh run watch refreshes?
Yes. Use --interval with a number of seconds, e.g. gh run watch --interval 5.