Github CLI

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

Authentication Contexts

Sources

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