GH-ISSUE-LIST(1)

💖 gh-issue-list — bestie's guide to listing issues 💖

okay so real talk, this page is from the GitHub CLI manual (yes, the gh thing, she's iconic, she's everywhere), and today we're learning gh-issue-list. buckle up bestie, it's giving "productivity" and honestly? ate.

---

✨ NAME ✨

gh-issue-list — literally just lists issues in a repository. that's the whole vibe. 🫶

---

🌸 SYNOPSIS 🌸

gh issue list [flags]

---

💅 DESCRIPTION 💅

So you wanna list issues in a GitHub repository? say less, main character. By default this only lists open issues — like, it's not gonna dump the whole graveyard on you unless you ask, and that's a vibe check it passes.

The search query syntax is documented here, iykyk:

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 in the --search query. no cap, it's real. more on advanced issue search over here:

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

---

🎀 OPTIONS 🎀

okay this is the part where I list every single one because I'm not about to do you dirty by skipping the "boring" ones. there are no boring ones. all flags are valid and beautiful. 🌈

• --app <string> — filter by GitHub App author
• -a, --assignee <string> — filter by assignee
• -A, --author <string> — filter by author (and psst: use --app if you're filtering by a GitHub App)
• -q, --jq <expression> — filter the JSON output using a jq expression
• --json <fields> — output JSON with the fields you specify
• -l, --label <strings> — filter by label
• -L, --limit <int> — maximum number of issues to fetch, and the default is 30 (yes, thirty, that's the number, don't come for me)
• --mention <string> — filter by mention
• -m, --milestone <string> — filter by milestone number or title
• -S, --search <query> — search issues with a query
• -s, --state <string> — filter by state: {open|closed|all}, default is "open"
• -t, --template <string> — format the JSON output using a Go template (go read gh help formatting for that one)
• --type <name> — filter by issue type name
• -w, --web — list issues in the web browser instead of the terminal, fancy

---

🦋 OPTIONS INHERITED FROM PARENT COMMANDS 🦋

the parents said "you're taking these with you" and honestly? fair.

• -R, --repo <[HOST/]OWNER/REPO> — select another repository using the [HOST/]OWNER/REPO format. note the square brackets, they're load-bearing. 💜

---

⭐ ALIASES ⭐

she has a nickname, obviously:

gh issue ls

---

🔥 JSON FIELDS 🔥

here's the full roster of fields you can ask for — every single one, in order, slay:

assignees, author, blockedBy, blocking, body, closed, closedAt,
closedByPullRequestsReferences, comments, createdAt, id, isPinned,
issueType, labels, milestone, number, parent, projectCards,
projectItems, reactionGroups, state, stateReason, subIssues,
subIssuesSummary, title, updatedAt, url

---

👑 EXIT CODES 👑

when you bounce, here's what the number means:

• 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 info — don't @ me, @ the help.

---

🌸 EXAMPLE 🌸

every single one of these works, copy-paste away bestie:

$ gh issue list --label "bug" --label "help wanted"
$ gh issue list --author monalisa
$ gh issue list --app dependabot
$ gh issue list --assignee "@me"
$ gh issue list --milestone "The big 1.0"
$ gh issue list --search "error no:assignee sort:created-asc"
$ gh issue list --state all
$ gh issue list --type Bug

notice the --label twice in the first one? yeah, multiple labels, she contains multitudes. and "@me" is you. it's always been you. 🪞

---

🌈 SEE ALSO 🌈

the family:

• gh-issue(1)

---

and that's the page!! 💖 this was GitHub CLI v2.102.0, dated Oct 2026 — like, from the future, but make it slay. go list some issues, you're literally the main character of your repo. 🎀✨👑