What output formats does gh pr list support?

By default it prints a table, but you can use --json to get structured JSON for scripting.

How do I filter by multiple labels?

Use repeated --label flags, e.g., gh pr list --label "bug" --label "priority" to require both labels.

Do I need to be in the repo to list PRs?

You can specify the repository explicitly with --repo OWNER/REPO if you’re not in the repository directory.

gh-pr-list

npx machina-cli add skill dceoy/github-cli-agent-skills/gh-pr-list --openclaw

Files (1)

SKILL.md

2.6 KB

GitHub PR List

When to use

The user asks to list pull requests in a repository.
You need to find PRs by author, label, state, or search query.
Checking overall PR backlog or finding specific PRs.

Inputs to confirm

Filter criteria: state (open/closed/merged/all), author, assignee, labels.
Search query if advanced filtering needed.
Target repo if not current (--repo OWNER/REPO).
Output format (table, JSON, web).

Workflow

Verify auth:
```
gh --version
gh auth status
```

List PRs with filters:

gh pr list
gh pr list --state all --limit 50
gh pr list --author "@me"
gh pr list --label "bug" --label "priority"
gh pr list --assignee "@me" --state open

Use search syntax for advanced queries:

gh pr list --search "status:success review:required"
gh pr list --search "draft:false review:approved"

Get JSON output for scripting:

gh pr list --json number,title,state,author --jq '.[] | "\(.number): \(.title)"'

Examples

# List your open PRs
gh pr list --author "@me"

# Find PRs needing review
gh pr list --search "review:required"

# List merged PRs to main
gh pr list --state merged --base main --limit 20

# Get PR numbers and titles as JSON
gh pr list --json number,title,reviewDecision

Flags reference

Flag	Description
`-s, --state`	Filter: open, closed, merged, all (default: open)
`-A, --author`	Filter by author
`-a, --assignee`	Filter by assignee
`-l, --label`	Filter by label (repeatable)
`-B, --base`	Filter by base branch
`-H, --head`	Filter by head branch
`-S, --search`	Search with GitHub query syntax
`-L, --limit`	Max items to fetch (default 30)
`--json`	Output specific fields as JSON
`-w, --web`	Open list in browser

References

GitHub CLI manual: https://cli.github.com/manual/
Search syntax: https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests
gh pr list --help

Source

git clone https://github.com/dceoy/github-cli-agent-skills/blob/main/skills/gh-pr-list/SKILL.mdView on GitHub

Overview

This skill uses the GitHub CLI (gh) to list pull requests with filters like state, author, assignee, and labels, and supports advanced search queries. It helps you surface PRs in a repo or backlog and export results for automation.

How This Skill Works

You run gh pr list with various flags (e.g., --state, --author, --label, --assignee, --base, --head, --search, --limit) to narrow results. For scripting, use --json to fetch structured fields and optionally pipe through --jq for formatting. If you’re not in the repo root, supply --repo OWNER/REPO.

When to Use It

When you need to list pull requests in a repository
When you need to find PRs by author, label, state, or a search query
When analyzing overall PR backlog or locating specific PRs
When you’re not in the repo’s directory and must specify the repo with --repo
When you want structured output for automation using --json (and --jq)

Quick Start

Step 1: Verify gh is ready: gh --version and gh auth status
Step 2: List PRs with basic filters, e.g., gh pr list --state open --author "@me"
Step 3: Get JSON output for scripting with --json, e.g., gh pr list --json number,title,state

Best Practices

Combine multiple labels with repeated --label calls to intersect filters
Use --state all or merged to see completed PRs alongside open ones
Use --author "@me" or --assignee "@me" to focus on your PRs
Export data with --json and format with --jq for scripting
Always verify authentication with gh auth status before listing PRs

Example Use Cases

gh pr list --author "@me"
gh pr list --search "review:required"
gh pr list --state merged --base main --limit 20
gh pr list --json number,title,reviewDecision
gh pr list --label "bug" --label "priority"

Frequently Asked Questions

Add this skill to your agents