Gh Cli Agentic

---
name: gh-cli-agentic
description: gh CLI commands with JSON output for agent workflows. Use when querying PRs, issues, workflow runs, or repo metadata; inspecting PR checks; fetching failed CI logs; or resolving a github.com URL to an API call.
user-invocable: false
allowed-tools: Bash(gh pr *), Bash(gh run *), Bash(gh issue *), Bash(gh repo *), Bash(gh workflow *), Bash(gh api *), Read
created: 2025-01-16
modified: 2026-09-24
reviewed: 2026-04-25
---

# GitHub CLI Agentic Patterns

## When to Use This Skill

| Use this skill when... | Use the alternative when... |
|---|---|
| Querying PRs, issues, runs, or repo metadata with `gh` and need JSON output | Use `git-cli-agentic` for porcelain-mode local git queries (status, diff, log) |
| Inspecting PR checks, mergeable status, or fetching failed CI logs | Use `gh-workflow-monitoring` to actively watch a run until it completes |
| Resolving a github.com URL into an `gh api` call or working with sub-issues | Use `git-issue-hierarchy` for sub-issue add/remove/dependency-graph operations |
| Looking up label, repo, or workflow metadata via `gh` JSON commands | Use `github-labels` to actually apply or create labels on issues/PRs |

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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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

| 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+):

```markdown
- 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](REFERENCE.md).