Github cli queries

GitHub CLI Query Skill

Overview

Use the gh CLI tool to efficiently query GitHub pull requests and issues with filtering, date range support, and structured JSON output.

Installation & Setup

# gh CLI is typically pre-installed on most systems
gh --version

# Ensure you're authenticated
gh auth status

# If not authenticated
gh auth login

Basic Patterns

Query Pull Requests by Date Range

# List PRs created in December 2024 with JSON output
gh pr list --repo cli/cli --state all --created "2024-12-01..2024-12-31" --json number,title,createdAt,mergedAt,closedAt,author --limit 500

# Key fields in JSON output:
# - number: PR number
# - title: PR title
# - createdAt: when PR was created (ISO 8601)
# - mergedAt: when PR was merged (null if not merged)
# - closedAt: when PR was closed (null if still open)
# - author: {login: string, name: string}

Query Issues by Date Range

# List issues created in December 2024
gh issue list --repo cli/cli --state all --created "2024-12-01..2024-12-31" --json number,title,createdAt,closedAt,labels --limit 500

# Key fields:
# - number: issue number
# - title: issue title
# - createdAt: when issue was created (ISO 8601)
# - closedAt: when issue was closed (null if still open)
# - labels: array of label objects with name and description

Date Format

• Use ISO 8601 format: YYYY-MM-DD
• Date ranges: YYYY-MM-DD..YYYY-MM-DD
• The range is inclusive on both ends

State Filtering

• --state all: Include open, closed, and merged (for PRs)
• --state open: Only open items
• --state closed: Only closed items (for issues) or merged/closed (for PRs)

Common Flags

• --limit N: Set maximum results (default 30, max typically 500)
• --json <fields>: Request specific fields as JSON
• --repo owner/repo: Specify repository

Date Parsing Tips

• Always capture both createdAt and mergedAt/closedAt to calculate deltas
• Handle null values when calculating metrics
• Parse ISO 8601 timestamps in your processing language

Example: Full PR Data Export

gh pr list --repo cli/cli --state all --created "2024-12-01..2024-12-31" \
  --json number,title,createdAt,mergedAt,closedAt,author,labels \
  --limit 500 > prs.json

Performance Notes

• Large result sets (500+ items) may take time to process
• Use --limit to control result size
• JSON output is faster than parsing text output
• Paginate if needed by using multiple queries with different date ranges