Command referencegh run watch
gh run watch command (Linux & Windows / GitHub CLI)
What it does
Watch a GitHub Actions run until it completes, printing progress updates. When people search for gh run watch, they usually want practical GitHub CLI flags, safe examples, and how this subcommand fits everyday PR and repo workflows on Linux, Windows, and macOS. Syntax, options, and copyable examples are below.
Watch a GitHub Actions run until it completes, printing progress updates.
Syntax
gh run watch <run-id> [flags]
Common options
| Flag / option | Meaning |
|---|---|
| --exit-status | Exit with the run’s failure status. |
| --interval | Refresh interval in seconds. |
Practical examples
Watch a run
gh run watch 123456789
Streams status updates until the run finishes.
Fail the shell on CI failure
gh run watch 123456789 --exit-status
Useful in scripts that must stop when Actions fails.
Common mistakes
- Watching the wrong run after a matrix of retries.
- Assuming watch also prints full step logs — use `gh run view --log` for logs.
Related commands
- gh run listList recent GitHub Actions workflow runs for the repository.
- gh run viewInspect a GitHub Actions run, including jobs, annotations, and optional logs.
- gh workflow runTrigger a workflow_dispatch event for a GitHub Actions workflow.
- gh pr checksShow GitHub Actions and status-check results for a pull request.
- gh auth loginAuthenticate the GitHub CLI with GitHub.com or GitHub Enterprise so other gh commands can run.
- gh pr createCreate a pull request from the current branch with title, body, reviewers, and base branch options.
- gh pr mergeMerge a pull request using merge commit, squash, or rebase strategies.
- gitTrack source history and collaborate through distributed repositories.
FAQ
What does gh run watch do in GitHub CLI?
Watch a GitHub Actions run until it completes, printing progress updates.
Does gh run watch work on Windows and Linux?
Yes. The GitHub CLI (`gh`) runs on Linux, Windows, and macOS with the same subcommand syntax after you authenticate with `gh auth login`.
What is a practical gh run watch example?
Try `gh run watch 123456789` — Streams status updates until the run finishes.
Do I need a token in the command line for gh run watch?
Prefer `gh auth login` so credentials stay in the system keyring or secure storage. Avoid pasting personal access tokens into shell history.
Browse the full Linux and Windows command reference to search more bash, CMD, PowerShell, Conda, and GitHub CLI commands.