GitHub CLI Agentic Patterns

When to Use This Skill

Optimized gh commands for AI agent consumption using JSON output and structured field selection.

Core Principle

Always use --json <fields> for machine-readable output. The --jq filter is built-in (no jq installation required).

gh api sends every field as a string unless you use -F

-f key=value types the value as a string, so an endpoint expecting a number rejects it:

gh api -X POST repos/O/R/issues/2380/sub_issues -f sub_issue_id=5471095685
Invalid property /sub_issue_id: "5471095685" is not of type `integer`. (HTTP 422)

-F key=value reads the value as a typed literal (number, boolean, null, or @file) and the identical call succeeds. Observed 2026-09-16: six sub-issue links failed this way before the flag changed. The error quotes the value and names the property, so it reads as a bad id — the id was right and the flag was wrong. Use -F for every numeric id (sub_issue_id, after_id) and -f for free text.

Pull Request Operations

Check Status

# Get all check statuses
gh pr checks $PR_NUMBER --json name,state,conclusion,detailsUrl

# Filter to failed only
gh pr checks $PR_NUMBER --json name,state,conclusion --jq '.[] | select(.conclusion == "FAILURE")'

Fields: name, state, conclusion, detailsUrl, startedAt, completedAt

PR Details

# Essential PR info
gh pr view $PR_NUMBER --json number,title,state,mergeable,statusCheckRollup

# Full context
gh pr view $PR_NUMBER --json number,title,body,state,author,labels,assignees,reviewDecision,mergeable,statusCheckRollup

Key Fields:

List PRs

# Open PRs
gh pr list --json number,title,author,labels

# PRs by author
gh pr list --author @me --json number,title,state

# PRs needing review
gh pr list --search "review-requested:@me" --json number,title

Workflow Run Operations

Run Details

# Get run status with jobs
gh run view $RUN_ID --json conclusion,status,jobs,createdAt,updatedAt

# List recent runs
gh run list --json databaseId,status,conclusion,name,createdAt -L 10

Status Values: queued, in_progress, completed Conclusion Values: success, failure, cancelled, skipped, neutral

Watch Run Until Completion

# Watch and wait for run to complete (blocking, no timeout needed)
gh run watch $RUN_ID --compact --exit-status

# Find and watch latest run
RUN_ID=$(gh run list -L 1 --json databaseId --jq '.[0].databaseId')
gh run watch $RUN_ID --compact --exit-status

See gh-workflow-monitoring skill for comprehensive workflow watching patterns.

Failed Logs

# Get only failed step logs (most useful for debugging)
gh run view $RUN_ID --log-failed

# Full logs (verbose)
gh run view $RUN_ID --log

Workflow Triggers

# Trigger workflow manually
gh workflow run $WORKFLOW_NAME

# Trigger with inputs
gh workflow run $WORKFLOW_NAME -f param1=value1 -f param2=value2

# List workflows
gh workflow list --json name,state,path

Issue Operations

Issue Details

# Full issue context
gh issue view $ISSUE_NUMBER --json number,title,body,state,labels,assignees,comments

# Minimal
gh issue view $ISSUE_NUMBER --json number,title,state,labels

# With sub-issue progress
gh issue view $ISSUE_NUMBER --json number,title,state,subIssuesSummary

List Issues

# Open issues
gh issue list --json number,title,labels,assignees

# By label
gh issue list --label "bug" --json number,title

# Assigned to me
gh issue list --assignee @me --json number,title,state

Issue Types

# Create issue with type (requires repo/org with issue types configured)
gh issue create --title "..." --body "..." --type "Bug"
gh issue create --title "..." --body "..." --type "Feature"
gh issue create --title "..." --body "..." --type "Task"

Sub-Issues

# List sub-issues of a parent
gh api repos/{owner}/{repo}/issues/{parent}/sub_issues --jq '.[].number'

# Add existing issue as sub-issue
gh api repos/{owner}/{repo}/issues/{parent}/sub_issues -F sub_issue_id={child_id}

# Remove sub-issue
gh api repos/{owner}/{repo}/issues/{parent}/sub_issues/{sub_issue_id} -X DELETE

# Reprioritize sub-issue (move after another sub-issue)
gh api repos/{owner}/{repo}/issues/{parent}/sub_issues -X PATCH \
  -F sub_issue_id={id} -F after_id={after_id}

# Get sub-issue summary via issue view
gh issue view {N} --json title,subIssuesSummary
# Returns: {"total": 5, "completed": 3, "percentCompleted": 60}

Repository Operations

# Get repo info
gh repo view --json nameWithOwner,defaultBranchRef,description

# Just owner/name
gh repo view --json nameWithOwner --jq '.nameWithOwner'

API Direct Access

For operations not covered by subcommands:

# Get specific data
gh api repos/{owner}/{repo}/actions/runs --jq '.workflow_runs[:5]'

# With pagination
gh api repos/{owner}/{repo}/issues --paginate --jq '.[].number'

Agentic Optimizations

Error Handling in Context

Use 2>/dev/null to suppress errors in context expressions (do NOT use || fallbacks - blocked by Claude Code 2.1.7+):

- PR checks: !`gh pr checks $PR --json name,state,conclusion`
- Run status: !`gh run view $ID --json status,conclusion`

For custom issue fields, issue management (transfer/pin/lock/develop), GitHub URL resolution (file contents, diffs, patches), and complete JSON field lists, see REFERENCE.md.