GH-RUN-WATCH(1)

💅 gh-run-watch(1) — the GitHub CLI manual, bestie edition 🎀

okay so real quick, we're in the gh-run-watch(1) page of the GitHub CLI manual and honestly? this one's a little baddie. it watches a run for you. let's get into it ✨

---

🌸 NAME 🌸

gh-run-watch — watch a run until it completes, showing its progress 🫶

---

🦋 SYNOPSIS 🦋

gh run watch <run-id> [flags]

---

✨ DESCRIPTION ✨

Watch a run until it completes, showing its progress. that's the whole vibe. you point it at a run and it just… keeps you posted. lowkey the most supportive command in the whole CLI tbh 😭💖

By default, all steps are displayed. that's every single one, no skips, main character energy for every step. but if that's too much for you (it's giving overwhelming), the --compact option can be used to only show the relevant/failed steps. much more chill. much more "just tell me what went wrong" 🙈

⭐ heads up though: this command does not support authenticating via fine grained PATs, because it is not currently possible to create a PAT with the checks:read permission. so like… that route's blocked, no cap. use something else to auth, bestie 💀

---

🔥 OPTIONS 🔥

• --compact — Show only relevant/failed steps. perfect when the full step feed is too loud and you just want the tea ☕
• --exit-status — Exit with non-zero status if run fails. so your scripts can actually tell when things go sideways. very demure, very useful 🎀
• -i, --interval <int> — Refresh interval in seconds. default is 3. so it's checking back every three seconds like a loyal bestie texting "u good?" 💅

---

👑 OPTIONS INHERITED FROM PARENT COMMANDS 👑

• -R, --repo <[HOST/]OWNER/REPO> — Select another repository using the [HOST/]OWNER/REPO format. you're not locked to the repo you're standing in, go explore 🦋

---

🌈 EXIT CODES 🌈

• 0 — Successful execution 🎉
• 1 — Error 😭
• 2 — Command canceled 🙈
• 4 — Authentication required 🔑

💜 NOTE: Specific commands may have additional exit codes. Refer to the command's help for more information. basically, always check the individual command's help, iykyk.

---

🍓 EXAMPLE 🍓

# Watch a run until it's done
$ gh run watch

# Watch a run in compact mode
$ gh run watch --compact

# Run some other command when the run is finished
$ gh run watch && notify-send 'run is done!'

that last one? iconic. chaining it with notify-send 'run is done!' so you literally get told the run is done. obsessed. periodt 💅✨

---

🧚 SEE ALSO 🧚

gh-run(1) — go read that one too, bestie, it's the parent vibe 💖

---

and that's the page!! 🌸 written up for GitHub CLI v2.102.0, dated Oct 2026 — ty for reading, ily, go watch some runs 🫶🎀💜