github-cli

name	github-cli
description	GitHub CLI (gh) workflows and best practices. Use when working with PRs, issues, workflows, releases, or GitHub API. Triggers on "gh", "github cli", "create pr", "check ci", "merge pr", "copilot coding agent", etc.

GitHub CLI

When to Use

• Creating, reviewing, or merging PRs
• Working with issues, releases, or workflows
• Querying GitHub API (prefer gh api over raw curl)
• CI/CD debugging and monitoring
• Managing Copilot coding agent tasks

What's New (2026)

Native gh copilot Bridge (v2.86.0)

# Launches Copilot CLI (prompts to install if missing)
gh copilot

# Forward args directly to Copilot CLI
gh copilot <args>

Replaces the old gh-copilot extension. Now built into gh as a native command.

Copilot Coding Agent Integration (v2.80.0+)

# Create a coding agent task
gh agent-task create "refactor authentication module"

# Use a custom agent
gh agent-task create --custom-agent my-agent "refactor auth"

# List active agent tasks
gh agent-task list

# View task details and follow logs
gh agent-task view <task-id> --follow

PR Revert Command (v2.83.0)

# Revert a merged PR
gh pr revert <number>

Release Attestation Verification (v2.81.0)

# Verify release attestation
gh release verify v1.2.3

# Verify specific asset
gh release verify-asset v1.2.3 binary.tar.gz

Advanced Search Syntax (v2.79.0)

# Use GitHub's full search syntax with --search
gh pr list --search 'review:required draft:false'
gh issue list --search 'no:assignee label:"help wanted",bug sort:created-asc'

# Logical operators
gh pr list --search 'label:"bug" label:"urgent"'  # AND
gh pr list --search 'label:"bug","wip"'           # OR

Auth Improvements

# Auto-copy OAuth code to clipboard
gh auth login --clipboard
gh auth refresh --clipboard

# JSON output for scripting
gh auth status --json

Accessibility Preview (v2.72.0+)

# Enable accessibility features (screen reader support, color customization)
gh a11y

Copilot CLI (Standalone)

The old gh-copilot extension was deprecated Oct 25, 2025. Replaced by standalone Copilot CLI + native gh copilot bridge (v2.86.0).

# Install (pick one)
npm install -g @github/copilot-cli    # Requires Node.js 22+
brew install copilot-cli               # macOS/Linux

# Launch interactive session
copilot

# Or via gh bridge
gh copilot

# Key slash commands
/model          # Switch the active model (Claude Sonnet or GPT)
/delegate       # Hand off to coding agent (commits unstaged changes to new branch)
/login          # Authenticate (first time only)

The new Copilot CLI supports custom MCP servers, custom agents (copilot --agent=my-agent), and is a full agentic assistant.

Modern Patterns

JSON Output + jq

Always use --json for scripting. Never parse human-readable output.

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

# Filter in the query
gh pr list --json number,title,state --jq '.[] | select(.state == "OPEN")'

Browse Shortcuts

# Open repo in browser
gh browse

# Specific pages
gh browse -p     # Projects
gh browse -r     # Releases
gh browse -s     # Settings
gh browse -A     # Actions (v2.85.0)

# Open file at line
gh browse path/to/file.py:59

# Open issue/PR by number
gh browse 123

The -w Flag (Open in Web)

Works across many commands:

gh issue list -w
gh pr view -w
gh release view -w
gh workflow view -w
gh run view -w

Issue-Linked Branches

# Create branch linked to issue (auto-links PRs from this branch)
gh issue develop -c 123

PR Creation Modes

# Interactive (prompts for everything)
gh pr create

# Fill from commits
gh pr create --fill                 # Title + body from commits
gh pr create --fill-first           # Just first commit
gh pr create --fill-verbose         # Detailed commit list

# Direct
gh pr create -t "feat: thing" -b "Description here"
gh pr create -t "feat: thing" -F body.md

# Open editor
gh pr create -e --fill-first

# Open in browser (prefills form)
gh pr create -w

# With metadata
gh pr create --fill -d -r @team/reviewers -l "needs-review"

PR Checkout

# By number or URL
gh pr checkout 719
gh pr checkout https://github.com/user/repo/pull/719

# Alias
gh co 719

# Works even for closed PRs with deleted branches

PR Review

# Full context before reviewing — body, review summaries, and the comment thread
gh pr view 719 --comments

# The diff is the substance — body and comments rarely tell the whole story
gh pr diff 719
gh pr diff 719 --name-only      # changed files only, for scope

# Inline line-level review comments are NOT in --comments — fetch via the API
gh api 'repos/{owner}/{repo}/pulls/719/comments' \
  --jq '.[] | "\(.path):\(.line) — \(.user.login): \(.body)"'

# Cross-references — issues/PRs that mention this one (shared issue timeline endpoint)
gh api 'repos/{owner}/{repo}/issues/719/timeline' --paginate \
  --jq '.[] | select(.event=="cross-referenced") | .source.issue | "\(.repository.full_name)#\(.number) — \(.title)"'

Auto-Merge Workflows

# Enable auto-merge (requires branch protection)
gh pr merge --auto --squash

# Merge methods
gh pr merge -m    # Merge commit
gh pr merge -r    # Rebase
gh pr merge -s    # Squash

# Delete branch after merge
gh pr merge -d --squash

# Cancel auto-merge
gh pr merge --disable-auto

Workflow Watching

# Watch current commit's run (live updates every 3s)
gh run watch

# Watch specific run
gh run watch <run-id>

# Compact output for large workflows
gh run watch --compact

# Exit with failure code if run fails (useful in scripts)
gh run watch --exit-status

# Trigger and watch
gh workflow run deploy.yml && sleep 2 && gh run watch

CI Debugging

# View failed job logs only
gh run view <run-id> --log-failed

# Re-run only failed jobs
gh run rerun <run-id> --failed

# Force cancel
gh run cancel <run-id> --force

# Download artifacts
gh run download <run-id>

Cache Management

# List caches
gh cache list

# Delete by key
gh cache delete <key>

# Delete by ref
gh cache delete <key> --ref refs/heads/feature-x

# Delete all (with safety flag)
gh cache delete --all --succeed-on-no-caches

GraphQL API

Use for complex/nested queries where REST would require multiple calls.

gh api graphql -f query='
  query($owner: String!, $repo: String!) {
    repository(owner: $owner, name: $repo) {
      pullRequests(first: 10, states: OPEN) {
        nodes {
          number
          title
          reviews(first: 5) { nodes { state } }
        }
      }
    }
  }
' -F owner='{owner}' -F repo='{repo}'

Attestation Verification

# Verify artifact attestation
gh attestation verify <artifact> --owner <org>

# Verify with specific bundle
gh attestation verify <artifact> --bundle attestation.json

Extensions

# Install
gh extension install <owner/repo>

# Notable extensions (2025)
gh extension install dlvhdr/gh-dash       # TUI dashboard
gh extension install github/gh-models     # Model evals (gh models eval)

gh-models (Model Evaluation)

# Run prompt evaluations defined in .prompt.yml
gh models eval

# Auto-generate test cases
gh models generate

Useful Aliases

gh alias set pv 'pr view --web'
gh alias set co 'pr checkout'
gh alias set ms 'pr merge --squash --auto'
gh alias set ww 'run watch --exit-status'

Anti-Patterns

Avoid	Instead
Parsing text output	--json + --jq
curl to GitHub API	gh api (handles auth, pagination)
Manual polling for CI	gh run watch
Multiple REST calls for nested data	GraphQL
gh copilot extension (old)	copilot CLI or gh copilot bridge (v2.86.0+)
gh < v2.86	Upgrade — native Copilot bridge, agent-task improvements

Authentication Contexts

Context	Method
Local dev	gh auth login (browser OAuth)
CI/Actions	GITHUB_TOKEN auto-injected
CI (elevated perms)	GH_TOKEN env var with PAT
Codespaces	Auto-authenticated
SSH preference	gh auth login --git-protocol ssh
Scope refresh	gh auth refresh --scopes write:packages

Sources

• GitHub CLI Releases
• CLI Manual
• Copilot CLI Repo
• Copilot CLI Docs
• gh-copilot Deprecation Notice
• Adam Johnson: Top gh Commands (Nov 2025)