gh-cli-agentic

GitHub CLI Agentic Patterns

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).

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:

Field	Description
mergeable	MERGEABLE, CONFLICTING, UNKNOWN
reviewDecision	APPROVED, CHANGES_REQUESTED, REVIEW_REQUIRED
statusCheckRollup	Array of check statuses

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}

Custom Issue Fields

# List available fields for an org
gh api orgs/{org}/issue-fields --jq '.[].name'

# Get field values for an issue
gh api repos/{owner}/{repo}/issues/{N}/issue-field-values

# Set field value
gh api repos/{owner}/{repo}/issues/{N}/issue-field-values \
  -X POST -f field_id={id} -f value='{value}'

Issue Management

# Transfer issue to another repo
gh issue transfer {N} {target-repo}

# Pin/unpin issue
gh issue pin {N}
gh issue unpin {N}

# Lock/unlock issue thread
gh issue lock {N} --reason resolved
gh issue unlock {N}

# Create development branch from issue
gh issue develop {N} --checkout
gh issue develop {N} --name {branch-name}

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'

GitHub URL Resolution

Translate GitHub URLs into gh API commands for programmatic access.

URL → Command Mapping

URL Pattern	Command
github.com/{owner}/{repo}/pull/{n}	gh pr view {n} --repo {owner}/{repo} --json number,title,body,state
github.com/{owner}/{repo}/issues/{n}	gh issue view {n} --repo {owner}/{repo} --json number,title,body,state
github.com/{owner}/{repo}/commit/{sha}	gh api repos/{owner}/{repo}/commits/{sha}
github.com/{owner}/{repo}/blob/{ref}/{path}	gh api repos/{owner}/{repo}/contents/{path}?ref={ref}

File Contents by Ref

# Get decoded file content at a specific ref (branch, tag, or SHA)
gh api repos/{owner}/{repo}/contents/{path}?ref={ref} --jq '.content' | base64 -d

# Get raw file content directly (no JSON wrapper)
gh api repos/{owner}/{repo}/contents/{path}?ref={ref} -H "Accept: application/vnd.github.raw+json"

Diff and Patch via API

Use Accept headers to get raw diff or patch output from PRs and commits:

# PR diff
gh api repos/{owner}/{repo}/pulls/{n} -H "Accept: application/vnd.github.diff"

# PR patch
gh api repos/{owner}/{repo}/pulls/{n} -H "Accept: application/vnd.github.patch"

# Commit diff
gh api repos/{owner}/{repo}/commits/{sha} -H "Accept: application/vnd.github.diff"

# Commit patch
gh api repos/{owner}/{repo}/commits/{sha} -H "Accept: application/vnd.github.patch"

Agentic Optimizations

Context	Command
CI diagnosis	gh pr checks $N --json name,state,conclusion,detailsUrl
Get failure logs	gh run view $ID --log-failed
PR merge status	gh pr view $N --json mergeable,reviewDecision,statusCheckRollup
Quick issue list	gh issue list --json number,title,labels -L 10
Sub-issue progress	gh issue view $N --json title,subIssuesSummary
List sub-issues	gh api repos/{o}/{r}/issues/{N}/sub_issues --jq '.[].number'
Add sub-issue	gh api repos/{o}/{r}/issues/{N}/sub_issues -f sub_issue_id=M
Transfer issue	gh issue transfer N target-repo
Create dev branch	gh issue develop N --checkout
Workflow trigger	gh workflow run $NAME

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`

Field Reference

PR Fields

number, title, body, state, author, labels, assignees, reviewDecision, mergeable, statusCheckRollup, headRefName, baseRefName, isDraft, url, createdAt, updatedAt

Issue Fields

number, title, body, state, author, labels, assignees, comments, milestone, url, createdAt, updatedAt, closedAt, subIssuesSummary, type

Run Fields

databaseId, name, status, conclusion, jobs, createdAt, updatedAt, url, headBranch, headSha, event

Job Fields (within runs)

name, status, conclusion, startedAt, completedAt, steps