GitHub CLI Skill

This skill enables natural language interaction with GitHub via the gh CLI tool (https://cli.github.com/).

Quick Reference

Intent	Command
View PR	`gh pr view NUMBER`
List PRs	`gh pr list`
My PRs	`gh pr list --author @me`
Create PR	`gh pr create -t "Title" -b "Body"`
PR status	`gh pr status`
Merge PR	`gh pr merge NUMBER`
View issue	`gh issue view NUMBER`
List issues	`gh issue list`
Create issue	`gh issue create -t "Title" -b "Body"`
Workflow runs	`gh run list`
View run	`gh run view RUN-ID`
Repo info	`gh repo view`
Open in browser	`gh browse`

Pull Requests

Viewing PRs

# View PR in terminal
gh pr view NUMBER

# View PR in browser
gh pr view NUMBER --web

# View PR with comments
gh pr view NUMBER --comments

# View PR diff
gh pr diff NUMBER

# View PR checks/CI status
gh pr checks NUMBER

# View PR files changed
gh pr diff NUMBER --name-only

# View current branch's PR
gh pr view

# Get PR as JSON (for scripting)
gh pr view NUMBER --json number,title,state,mergeable,reviewDecision

Listing PRs

# List open PRs
gh pr list

# List my PRs
gh pr list --author @me

# List PRs assigned to me for review
gh pr list --search "review-requested:@me"

# List PRs by state
gh pr list --state open
gh pr list --state closed
gh pr list --state merged
gh pr list --state all

# List PRs by label
gh pr list --label bug
gh pr list --label "needs review"

# List PRs by base branch
gh pr list --base main
gh pr list --base develop

# List PRs by head branch
gh pr list --head feature/my-branch

# List draft PRs
gh pr list --draft

# Search PRs
gh pr list --search "fix login"
gh pr list --search "author:username"
gh pr list --search "is:open is:draft"

# Limit results
gh pr list --limit 10

# JSON output for scripting
gh pr list --json number,title,author,createdAt

# Web view of PR list
gh pr list --web

Creating PRs

# Interactive PR creation
gh pr create

# Non-interactive with title and body
gh pr create --title "Add feature X" --body "Description here"

# Create with specific base branch
gh pr create --base develop

# Create draft PR
gh pr create --draft --title "WIP: Feature"

# Create and request reviewers
gh pr create --title "Feature" --reviewer user1,user2

# Create with assignees
gh pr create --title "Feature" --assignee @me,user2

# Create with labels
gh pr create --title "Fix" --label bug,urgent

# Create with milestone
gh pr create --title "Feature" --milestone "v1.0"

# Create with project
gh pr create --title "Feature" --project "Project Name"

# Create from issue (links PR to issue)
gh pr create --title "Fix #123" --body "Closes #123"

# Fill title/body from commit messages
gh pr create --fill

# Fill from specific commit
gh pr create --fill-first

# Use template
gh pr create --template bug_report.md

# Create and open in browser
gh pr create --title "Feature" --web

# Read body from file
gh pr create --title "Feature" --body-file DESCRIPTION.md

PR Status and Checks

# Show status of PRs relevant to you
gh pr status

# Check CI status for a PR
gh pr checks NUMBER

# Watch CI status (updates live)
gh pr checks NUMBER --watch

# Wait for checks to complete
gh pr checks NUMBER --watch --fail-fast

# Check specific PR's review status
gh pr view NUMBER --json reviewDecision,reviews

# List required checks
gh pr checks NUMBER --required

Reviewing PRs

# Start a review
gh pr review NUMBER

# Approve PR
gh pr review NUMBER --approve

# Request changes
gh pr review NUMBER --request-changes --body "Please fix X"

# Comment without approval/rejection
gh pr review NUMBER --comment --body "Looks good overall"

# View PR diff for review
gh pr diff NUMBER

# Checkout PR locally for testing
gh pr checkout NUMBER

# Checkout PR to specific branch
gh pr checkout NUMBER --branch test-pr-123

# Add comment to PR
gh pr comment NUMBER --body "Comment text"

# Edit PR comment
gh pr comment NUMBER --edit-last --body "Updated comment"

Merging PRs

# Merge PR (uses repo default method)
gh pr merge NUMBER

# Merge with specific method
gh pr merge NUMBER --merge  # Create merge commit
gh pr merge NUMBER --squash # Squash and merge
gh pr merge NUMBER --rebase # Rebase and merge

# Merge and delete branch
gh pr merge NUMBER --delete-branch

# Auto-merge when checks pass
gh pr merge NUMBER --auto

# Disable auto-merge
gh pr merge NUMBER --disable-auto

# Merge with custom commit message
gh pr merge NUMBER --squash --subject "feat: add feature" --body "Details"

# Admin merge (bypass protections)
gh pr merge NUMBER --admin

Editing PRs

# Edit PR title
gh pr edit NUMBER --title "New title"

# Edit PR body
gh pr edit NUMBER --body "New description"

# Add labels
gh pr edit NUMBER --add-label bug,urgent

# Remove labels
gh pr edit NUMBER --remove-label wip

# Add reviewers
gh pr edit NUMBER --add-reviewer user1,user2

# Remove reviewers
gh pr edit NUMBER --remove-reviewer user1

# Add assignees
gh pr edit NUMBER --add-assignee @me

# Set milestone
gh pr edit NUMBER --milestone "v1.0"

# Convert to draft
gh pr ready NUMBER --undo

# Mark ready for review
gh pr ready NUMBER

# Set base branch
gh pr edit NUMBER --base develop

Closing/Reopening PRs

# Close PR
gh pr close NUMBER

# Close with comment
gh pr close NUMBER --comment "Closing because..."

# Close and delete branch
gh pr close NUMBER --delete-branch

# Reopen PR
gh pr reopen NUMBER

Issues

Viewing Issues

# View issue
gh issue view NUMBER

# View in browser
gh issue view NUMBER --web

# View with comments
gh issue view NUMBER --comments

# Get issue as JSON
gh issue view NUMBER --json number,title,state,labels,assignees

Listing Issues

# List open issues
gh issue list

# List my issues
gh issue list --assignee @me

# List issues I created
gh issue list --author @me

# List issues mentioning me
gh issue list --mention @me

# List by state
gh issue list --state open
gh issue list --state closed
gh issue list --state all

# List by label
gh issue list --label bug
gh issue list --label "help wanted"

# List by milestone
gh issue list --milestone "v1.0"

# Search issues
gh issue list --search "login error"
gh issue list --search "is:open label:bug"

# Limit results
gh issue list --limit 20

# JSON output
gh issue list --json number,title,labels,createdAt

# Web view
gh issue list --web

Creating Issues

# Interactive creation
gh issue create

# Non-interactive
gh issue create --title "Bug: X not working" --body "Description"

# Create with labels
gh issue create --title "Bug" --label bug,urgent

# Create with assignees
gh issue create --title "Task" --assignee @me,user2

# Create with milestone
gh issue create --title "Feature" --milestone "v1.0"

# Create with project
gh issue create --title "Feature" --project "Project Name"

# Use template
gh issue create --template bug_report.md

# Read body from file
gh issue create --title "Feature" --body-file ISSUE.md

# Create and open in browser
gh issue create --title "Bug" --web

# Create from current branch name
gh issue create --recover

Editing Issues

# Edit title
gh issue edit NUMBER --title "New title"

# Edit body
gh issue edit NUMBER --body "New description"

# Add labels
gh issue edit NUMBER --add-label bug,urgent

# Remove labels
gh issue edit NUMBER --remove-label wip

# Add assignees
gh issue edit NUMBER --add-assignee user1

# Remove assignees
gh issue edit NUMBER --remove-assignee user1

# Set milestone
gh issue edit NUMBER --milestone "v1.0"

# Add to project
gh issue edit NUMBER --add-project "Project Name"

Closing/Reopening Issues

# Close issue
gh issue close NUMBER

# Close with comment
gh issue close NUMBER --comment "Fixed in #PR"

# Close as completed
gh issue close NUMBER --reason completed

# Close as not planned
gh issue close NUMBER --reason "not planned"

# Reopen issue
gh issue reopen NUMBER

Issue Comments

# Add comment
gh issue comment NUMBER --body "Comment text"

# Edit last comment
gh issue comment NUMBER --edit-last --body "Updated"

# Open comment editor
gh issue comment NUMBER --editor

Linking Issues and PRs

# Create PR that closes issue
gh pr create --title "Fix #123" --body "Closes #123"

# Link issue in PR body
gh pr create --body "Fixes #123, Related to #456"

# Develop on issue (create branch)
gh issue develop NUMBER

# Develop with custom branch name
gh issue develop NUMBER --name feature/fix-issue

# Develop and checkout
gh issue develop NUMBER --checkout

Workflows and Actions

Listing Runs

# List recent workflow runs
gh run list

# List runs for specific workflow
gh run list --workflow build.yml

# List runs by status
gh run list --status success
gh run list --status failure
gh run list --status in_progress

# List runs for branch
gh run list --branch main

# List runs for user
gh run list --user @me

# Limit results
gh run list --limit 10

# JSON output
gh run list --json databaseId,status,conclusion,name

# Web view
gh run list --web

Viewing Runs

# View run details
gh run view RUN-ID

# View run in browser
gh run view RUN-ID --web

# View specific job
gh run view RUN-ID --job JOB-ID

# View run log
gh run view RUN-ID --log

# View failed job logs only
gh run view RUN-ID --log-failed

# Exit with run's exit code
gh run view RUN-ID --exit-status

# Watch run progress
gh run watch RUN-ID

# Get run as JSON
gh run view RUN-ID --json status,conclusion,jobs

Managing Runs

# Rerun failed jobs
gh run rerun RUN-ID --failed

# Rerun all jobs
gh run rerun RUN-ID

# Rerun specific job
gh run rerun RUN-ID --job JOB-ID

# Rerun with debug logging
gh run rerun RUN-ID --debug

# Cancel a run
gh run cancel RUN-ID

# Delete a run
gh run delete RUN-ID

# Download run artifacts
gh run download RUN-ID

# Download specific artifact
gh run download RUN-ID --name artifact-name

# Download to specific directory
gh run download RUN-ID --dir ./artifacts

Triggering Workflows

# Trigger workflow (workflow_dispatch)
gh workflow run workflow.yml

# Trigger with inputs
gh workflow run workflow.yml -f param1=value1 -f param2=value2

# Trigger on specific branch
gh workflow run workflow.yml --ref feature-branch

# Trigger from JSON file
gh workflow run workflow.yml --json <inputs.json

Listing Workflows

# List all workflows
gh workflow list

# List enabled workflows
gh workflow list --state enabled

# List disabled workflows
gh workflow list --state disabled

# View specific workflow
gh workflow view workflow.yml

# View workflow in browser
gh workflow view workflow.yml --web

# Enable workflow
gh workflow enable workflow.yml

# Disable workflow
gh workflow disable workflow.yml

Repository Management

Viewing Repos

# View current repo
gh repo view

# View specific repo
gh repo view owner/repo

# View in browser
gh repo view --web

# Get repo as JSON
gh repo view --json name,description,stargazerCount,forkCount

# View README
gh repo view --readme

Cloning and Forking

# Clone repo
gh repo clone owner/repo

# Clone to specific directory
gh repo clone owner/repo ./my-dir

# Fork repo
gh repo fork owner/repo

# Fork and clone
gh repo fork owner/repo --clone

# Fork with custom name
gh repo fork owner/repo --fork-name my-fork

Creating Repos

# Create repo interactively
gh repo create

# Create public repo
gh repo create my-repo --public

# Create private repo
gh repo create my-repo --private

# Create from template
gh repo create my-repo --template owner/template

# Create and clone
gh repo create my-repo --clone

# Create with description
gh repo create my-repo --description "My project"

# Create with gitignore
gh repo create my-repo --gitignore Node

# Create with license
gh repo create my-repo --license MIT

# Create org repo
gh repo create org/my-repo

Editing Repos

# Edit description
gh repo edit --description "New description"

# Set homepage
gh repo edit --homepage "https://example.com"

# Change visibility
gh repo edit --visibility private
gh repo edit --visibility public

# Enable/disable features
gh repo edit --enable-issues
gh repo edit --enable-wiki=false
gh repo edit --enable-discussions

# Set default branch
gh repo edit --default-branch main

# Enable auto-merge
gh repo edit --enable-auto-merge

# Enable delete branch on merge
gh repo edit --delete-branch-on-merge

# Archive repo
gh repo archive
gh repo archive owner/repo

# Unarchive
gh repo unarchive owner/repo

# Delete repo
gh repo delete owner/repo --yes

Repository Secrets

# List secrets
gh secret list

# Set secret
gh secret set SECRET_NAME

# Set secret from env
gh secret set SECRET_NAME --body "$VALUE"

# Set secret from file
gh secret set SECRET_NAME <secret.txt

# Set environment secret
gh secret set SECRET_NAME --env production

# Set org secret
gh secret set SECRET_NAME --org my-org

# Remove secret
gh secret delete SECRET_NAME

Repository Variables

# List variables
gh variable list

# Set variable
gh variable set VAR_NAME --body "value"

# Set environment variable
gh variable set VAR_NAME --env production --body "value"

# Delete variable
gh variable delete VAR_NAME

Releases

Listing Releases

# List releases
gh release list

# List with limit
gh release list --limit 10

# Exclude drafts
gh release list --exclude-drafts

# Exclude pre-releases
gh release list --exclude-pre-releases

Viewing Releases

# View latest release
gh release view

# View specific release
gh release view v1.0.0

# View in browser
gh release view v1.0.0 --web

# Get as JSON
gh release view v1.0.0 --json tagName,name,body,assets

Creating Releases

# Create release interactively
gh release create v1.0.0

# Create with title and notes
gh release create v1.0.0 --title "Version 1.0" --notes "Release notes"

# Create from file
gh release create v1.0.0 --notes-file CHANGELOG.md

# Auto-generate release notes
gh release create v1.0.0 --generate-notes

# Create draft
gh release create v1.0.0 --draft

# Create pre-release
gh release create v1.0.0 --prerelease

# Create with assets
gh release create v1.0.0 ./dist/*.zip ./dist/*.tar.gz

# Create from specific commit/branch
gh release create v1.0.0 --target main

# Set as latest
gh release create v1.0.0 --latest

# Don't mark as latest
gh release create v1.0.0 --latest=false

# Create and open discussion
gh release create v1.0.0 --discussion-category "Announcements"

Editing Releases

# Edit release
gh release edit v1.0.0 --title "New Title"

# Edit notes
gh release edit v1.0.0 --notes "Updated notes"

# Convert draft to published
gh release edit v1.0.0 --draft=false

# Mark as pre-release
gh release edit v1.0.0 --prerelease

# Set as latest
gh release edit v1.0.0 --latest

Managing Release Assets

# Upload assets
gh release upload v1.0.0 ./dist/*.zip

# Upload with custom name
gh release upload v1.0.0 ./build/app.zip#app-v1.0.0.zip

# Overwrite existing
gh release upload v1.0.0 ./dist/app.zip --clobber

# Download assets
gh release download v1.0.0

# Download specific asset
gh release download v1.0.0 --pattern "*.zip"

# Download to directory
gh release download v1.0.0 --dir ./downloads

# Delete asset
gh release delete-asset v1.0.0 app.zip

Deleting Releases

# Delete release
gh release delete v1.0.0

# Delete release and tag
gh release delete v1.0.0 --yes

# Cleanup old releases (delete drafts)
gh release delete v1.0.0-draft --yes

Gists

# List gists
gh gist list

# View gist
gh gist view GIST-ID

# View in browser
gh gist view GIST-ID --web

# Create gist
gh gist create file.txt

# Create public gist
gh gist create file.txt --public

# Create with description
gh gist create file.txt --desc "My gist"

# Create from multiple files
gh gist create file1.txt file2.js

# Create from stdin
echo "content" | gh gist create

# Edit gist
gh gist edit GIST-ID

# Add file to gist
gh gist edit GIST-ID --add newfile.txt

# Clone gist
gh gist clone GIST-ID

# Delete gist
gh gist delete GIST-ID

Browsing

# Open repo in browser
gh browse

# Open specific file
gh browse path/to/file.js

# Open at specific line
gh browse path/to/file.js:42

# Open specific branch
gh browse --branch develop

# Open commit
gh browse --commit abc123

# Open PRs page
gh browse --prs

# Open issues page
gh browse --issues

# Open actions page
gh browse --actions

# Open settings
gh browse --settings

# Open wiki
gh browse --wiki

# Open projects
gh browse --projects

# Print URL only (don't open)
gh browse --no-browser

Code Search and Codespaces

Code Search

# Search code in repo
gh search code "function" --repo owner/repo

# Search across GitHub
gh search code "pattern" --language javascript

# Search repos
gh search repos "topic:react" --limit 10

# Search issues
gh search issues "bug" --repo owner/repo

# Search PRs
gh search prs "fix" --state open

# Search commits
gh search commits "fix bug" --repo owner/repo

Codespaces

# List codespaces
gh codespace list

# Create codespace
gh codespace create --repo owner/repo

# Create with specific branch
gh codespace create --repo owner/repo --branch feature

# Create with machine type
gh codespace create --repo owner/repo --machine largePremiumLinux

# SSH into codespace
gh codespace ssh --codespace NAME

# Open in VS Code
gh codespace code --codespace NAME

# Open in browser
gh codespace view --codespace NAME --web

# Stop codespace
gh codespace stop --codespace NAME

# Delete codespace
gh codespace delete --codespace NAME

# Port forwarding
gh codespace ports forward 3000:3000 --codespace NAME

Authentication and Configuration

# Login
gh auth login

# Login with specific host
gh auth login --hostname enterprise.github.com

# Login with token
gh auth login --with-token <token.txt

# Check auth status
gh auth status

# Refresh auth
gh auth refresh

# Switch accounts
gh auth switch

# Logout
gh auth logout

# View current user
gh api user --jq .login

# Set git protocol
gh config set git_protocol ssh

# Set default editor
gh config set editor vim

# Set default browser
gh config set browser firefox

# View config
gh config list

API Access

# Make API request
gh api repos/owner/repo

# POST request
gh api repos/owner/repo/issues -f title="Bug" -f body="Description"

# Use jq for filtering
gh api repos/owner/repo --jq '.stargazers_count'

# Paginate results
gh api repos/owner/repo/issues --paginate

# GraphQL query
gh api graphql -f query='{ viewer { login } }'

# Include headers in output
gh api repos/owner/repo --include

Natural Language Mapping

When interpreting user requests, map these patterns:

User says	Interpret as
"my PRs", "my pull requests"	`--author @me`
"PRs for review", "to review"	`--search "review-requested:@me"`
"open PRs"	`--state open`
"merged PRs"	`--state merged`
"closed PRs/issues"	`--state closed`
"draft PRs"	`--draft`
"bugs", "bug issues"	`--label bug`
"my issues"	`--assignee @me`
"issues I created"	`--author @me`
"failing CI", "failed checks"	`gh pr checks` or `--status failure`
"CI status", "check status"	`gh pr checks NUMBER`
"recent runs", "workflow runs"	`gh run list`
"open it", "show in browser"	`--web` or `gh browse`
"merge it"	`gh pr merge`
"approve", "LGTM"	`gh pr review --approve`
"request changes"	`gh pr review --request-changes`
"latest release"	`gh release view`
"create release"	`gh release create`
"checkout PR"	`gh pr checkout NUMBER`
"PR diff", "what changed"	`gh pr diff NUMBER`

PR/Issue Detection

PR and issue numbers follow patterns: #123, PR #123, issue #123

When a user mentions a number in conversation:

Offer to view: gh pr view NUMBER or gh issue view NUMBER
Or open: gh browse with the appropriate path

Tips

Always show the command before running it
Use --json for scripting and parsing output
Use @me to reference the current user
Use --web to open results in browser
Use --help on any command for more options
The -R owner/repo flag can override the current repo context
Use gh api for operations not covered by specific commands
Enable shell completion: gh completion -s bash/zsh/fish

Error Handling

Common issues:

"not found" - verify repo access and PR/issue number
"not authenticated" - run gh auth login
"merge blocked" - check required reviews/checks
"no upstream" - push branch first: git push -u origin branch
"draft PR" - mark ready with gh pr ready NUMBER