GH-PR-LIST(1)

💅 GH-PR-LIST(1) — like, the whole entire manual, bestie

okay so this is gh-pr-list from the GitHub CLI manual — yes, that GitHub CLI, the one you keep forgetting to update — and it's literally the page that teaches you how to list pull requests from your terminal like a main character. sit down, grab a boba, we're doing this 🧋✨

---

🌸 NAME 🌸

gh-pr-list — List pull requests in a repository. that's it. that's the whole vibe. 👑

---

✨ SYNOPSIS ✨

gh pr list [flags]

---

🦋 DESCRIPTION 🦋

so you wanna see the PRs in a GitHub repository. iconic. by default this only lists open PRs — like, it's not gonna dump every closed and merged thing in your face unless you ask, because it respects you. 🫶

the search query syntax is documented here, and yes you have to actually go read it:

⟨https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests⟩

and on supported GitHub hosts, you can use advanced issue search syntax inside the --search query. that's the fancy stuff. for more info on advanced issue search, see:

⟨https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/filtering-and-searching-issues-and-pull-requests#building-advanced-filters-for-issues⟩

ngl those URLs are giving "assigned reading" but they're lowkey useful, iykyk 📚

---

💅 OPTIONS 💅

this is the part you actually came for. every single flag, no skips, no cap:

• --app <string> — filter by GitHub App author. yes, bots have feelings too 🤖
• -a, --assignee <string> — filter by assignee. who's holding the bag on this one
• -A, --author <string> — filter by author. and hey — use --app if you're filtering by a GitHub App, bestie, don't mix them up 💀
• -B, --base <string> — filter by base branch. the branch it's merging into, okay
• -d, --draft — filter by draft state. for the PRs that aren't ready yet (real)
• -H, --head <string> — filter by head branch. heads up: the ":" syntax is not supported here 🙈
• -q, --jq <expression> — filter JSON output using a jq expression. chef's kiss for piping 🍓
• --json <fields> — output JSON with the specified fields. pick your faves (full list further down 👇)
• -l, --label <strings> — filter by label. multiple labels = multiple flags, see the example
• -L, --limit <int> (default 30) — maximum number of items to fetch. thirty is the default, don't come for me
• -S, --search <query> — search pull requests with query. go wild with that advanced syntax
• -s, --state <string> (default "open") — filter by state: {open|closed|merged|all}. the whole squad of states 🌈
• -t, --template <string> — format JSON output using a Go template; see gh help formatting
• -w, --web — list pull requests in the web browser. for when you want the ✨graphical experience✨

---

👑 OPTIONS INHERITED FROM PARENT COMMANDS 👑

the parent commands said "here, take these too":

• -R, --repo <[HOST/]OWNER/REPO> — select another repository using the [HOST/]OWNER/REPO format. yes that bracket syntax is intentional, it's giving optional-host energy 🌟

---

🎀 ALIASES 🎀

gh pr ls

that's it. ls works. type less, slay more. literally.

---

🧚 JSON FIELDS 🧚

here's the full menu of fields you can pass to --json, and i'm listing every single one because i would never do you dirty like that:

additions, assignees, author, autoMergeRequest, baseRefName, baseRefOid, body, changedFiles, closed, closedAt, closingIssuesReferences, comments, commits, createdAt, deletions, files, fullDatabaseId, headRefName, headRefOid, headRepository, headRepositoryOwner, id, isCrossRepository, isDraft, labels, latestReviews, maintainerCanModify, mergeCommit, mergeStateStatus, mergeable, mergedAt, mergedBy, milestone, number, potentialMergeCommit, projectCards, projectItems, reactionGroups, reviewDecision, reviewRequests, reviews, state, statusCheckRollup, title, updatedAt, url

that's a lot. that's the point. pick what you need 🍓

---

💀 EXIT CODES 💀

when the command comes back, it comes back with a number, and the number means things:

1. 0 — Successful execution 🎉
2. 1 — Error 😭
3. 2 — Command canceled 🙈
4. 4 — Authentication required 🔐

NOTE: Specific commands may have additional exit codes. Refer to the command's help for more information. so like, don't @ me if there's a fifth one hiding somewhere

---

🔥 EXAMPLE 🔥

copy these exactly, bestie, they're tested:

# List PRs authored by you
$ gh pr list --author "@me"

# List PRs opened by a GitHub App such as Dependabot
$ gh pr list --app dependabot

# List PRs with a specific head branch name
$ gh pr list --head "typo"

# List only PRs with all of the given labels
$ gh pr list --label bug --label "priority 1"

# Filter PRs using search syntax
$ gh pr list --search "status:success review:required"

# Find a PR that introduced a given commit
$ gh pr list --search "<SHA>" --state merged

not the --label one needing two whole flags for two labels — the way that's just how it works 😌 and yes, "<SHA>" is a placeholder, swap in your actual SHA, please don't run it literally.

---

🌈 SEE ALSO 🌈

• gh-pr(1) — go read the parent, it's the whole PR universe

---

and that's the page!! mwah 💋 this was GitHub CLI v2.102.0, dated Oct 2026, and it's the GH-PR-LIST(1) manual page — go list some PRs, you absolute icon 🫶✨