GitHub CLI (gh) Overview Expert guidance for GitHub CLI (gh) operations and workflows. Use this skill for command-line GitHub operations including pull request management, issue tracking, repository operations, workflow automation, and codespace management. Key capabilities: Create and manage pull requests from the terminal Track and organize issues efficiently Search across all of GitHub (repos, issues, PRs) Manage labels and project organization Trigger and monitor GitHub Actions workflows Work with codespaces Automate repository operations and releases Safety Rules CRITICAL: This skill NEVER uses destructive gh CLI operations. This skill focuses exclusively on safe, read-only, or reversible GitHub operations. The following commands are PROHIBITED and must NEVER be used: Permanently destructive commands: gh repo delete - Repository deletion gh repo archive - Repository archival gh release delete - Release deletion gh release delete-asset - Asset deletion gh run delete - Workflow run deletion gh cache delete - Cache deletion gh secret delete - Secret deletion gh variable delete - Variable deletion gh label delete - Label deletion gh ssh-key delete - SSH key deletion (can lock out users) gh gpg-key delete - GPG key deletion gh codespace delete - Codespace deletion gh extension remove - Extension removal gh gist delete - Gist deletion Bulk deletion operations using xargs with any destructive commands Shell commands: rm -rf (except for temporary file cleanup) Allowed operations: Creating resources (PRs, issues, releases, labels, repos) Viewing and listing (status, logs, information, searches) Updating and editing existing resources Closing PRs/issues (reversible - can be reopened) Canceling workflow runs (stops execution without deleting data) Merging pull requests (after proper review) Read-only git operations ( git status , git log , git diff ) Installation & Setup

Login to GitHub

gh auth login

Check authentication status

gh auth status

Configure git to use gh as credential helper

gh auth setup-git Pull Requests Creating PRs

Create PR interactively

gh pr create

Create PR with title and body

gh pr create --title "Add feature" --body "Description"

Create PR to specific branch

gh pr create --base main --head feature-branch

Create draft PR

gh pr create --draft

Create PR from current branch

gh pr create --fill

Uses commit messages

Viewing PRs

List PRs

gh pr list

List my PRs

gh pr list --author @me

View PR details

gh pr view 123

View PR in browser

gh pr view 123 --web

View PR diff

gh pr diff 123

Check PR status

gh pr status Managing PRs

Checkout PR locally

gh pr checkout 123

Review PR

gh pr review 123 --approve gh pr review 123 --comment --body "Looks good!" gh pr review 123 --request-changes --body "Please fix X"

Merge PR

gh pr merge 123 gh pr merge 123 --squash gh pr merge 123 --rebase gh pr merge 123 --merge

Close PR

gh pr close 123

Reopen PR

gh pr reopen 123

Ready draft PR

gh pr ready 123

Update PR branch with base branch

gh pr update-branch 123 PR Checks

View PR checks

gh pr checks 123

Watch PR checks

gh pr checks 123 --watch Issues Creating Issues

Create issue interactively

gh issue create

Create issue with title and body

gh issue create --title "Bug report" --body "Description"

Create issue with labels

gh issue create --title "Bug" --label bug,critical

Assign issue

gh issue create --title "Task" --assignee @me Viewing Issues

List issues

gh issue list

List my issues

gh issue list --assignee @me

List by label

gh issue list --label bug

View issue details

gh issue view 456

View in browser

gh issue view 456 --web Managing Issues

Close issue

gh issue close 456

Reopen issue

gh issue reopen 456

Edit issue

gh issue edit 456 --title "New title" gh issue edit 456 --add-label bug gh issue edit 456 --add-assignee @user

Comment on issue

gh issue comment 456 --body "Update"

Create branch to work on issue

gh issue develop 456 --checkout Repository Operations Repository Info

View repository

gh repo view

View in browser

gh repo view --web

Clone repository

gh repo clone owner/repo

Fork repository

gh repo fork owner/repo

List repositories

gh repo list owner Repository Management

Create repository

gh repo create my-repo --public gh repo create my-repo --private

Sync fork

gh repo sync owner/repo

Set default repository

gh repo set-default Search Search across all of GitHub for repositories, issues, and pull requests. Search Repositories

Search for repositories

gh search repos "machine learning" --language = python

Search with filters

gh search repos --stars = ">1000" --topic = kubernetes Search Issues

Search issues across GitHub

gh search issues "bug" --label = critical --state = open

Exclude results (note the -- to prevent flag interpretation)

gh search issues -- "memory leak -label:wontfix" Search Pull Requests

Search PRs

gh search prs --author = @me --state = open

Search with date filters

gh search prs "refactor" --created = ">2024-01-01" Labels Manage repository labels for issue and PR organization. List and View Labels

List all labels in repository

gh label list Create and Edit Labels

Create new label

gh label create "priority: high" --color FF0000 --description "High priority items"

Edit existing label

gh label edit "bug" --color FFAA00 --description "Something isn't working" Clone Labels Between Repos

Clone labels from another repository

gh label clone owner/source-repo Codespaces Manage GitHub Codespaces directly from the terminal. List and Create Codespaces

List codespaces

gh codespace list

Create new codespace

gh codespace create --repo owner/repo Connect to Codespaces

SSH into codespace

gh codespace ssh

Open in VS Code

gh codespace code

Open in JupyterLab

gh codespace jupyter Manage Codespace Files

Copy files to/from codespace

gh codespace cp local-file.txt remote:~/path/ gh codespace cp remote:~/path/file.txt ./local-dir/

View logs

gh codespace logs Releases Creating Releases

Create release

gh release create v1.0.0

Create release with notes

gh release create v1.0.0 --notes "Release notes"

Create release with files

gh release create v1.0.0 dist/*.tar.gz

Create draft release

gh release create v1.0.0 --draft

Generate release notes automatically

gh release create v1.0.0 --generate-notes Managing Releases

List releases

gh release list

View release

gh release view v1.0.0

Download release assets

gh release download v1.0.0 Gists

Create gist

gh gist create file.txt

Create gist from stdin

echo "content" | gh gist create -

List gists

gh gist list

View gist

gh gist view < gist-id

Edit gist

gh gist edit < gist-id

Configuration

Set default editor

gh config set editor vim

Set default git protocol

gh config set git_protocol ssh

View configuration

gh config list

Set browser

gh config set browser firefox Quick Reference Common gh operations at a glance: Operation Command Common Flags Create PR gh pr create --draft , --fill , --base , --title List PRs gh pr list --author @me , --label , --state View PR gh pr view --web , --comments Merge PR gh pr merge --squash , --rebase , --delete-branch Create issue gh issue create --title , --body , --label List issues gh issue list --assignee @me , --label , --state View issue gh issue view --web , --comments Clone repo gh repo clone -- (to pass git flags) Fork repo gh repo fork --clone , --remote View repo gh repo view --web Create release gh release create --title , --notes , --draft Run workflow gh workflow run --ref , --field Watch run gh run watch --exit-status Search repos gh search repos --language , --stars Create label gh label create --color , --description Create codespace gh codespace create --repo , --branch SSH to codespace gh codespace ssh --codespace Additional Resources Reference Guides For detailed patterns and advanced usage, see: Workflows & Actions - GitHub Actions workflows, runs, cache management, and CI/CD integration patterns Advanced Features - Aliases, API access, extensions, secrets, SSH/GPG keys, organizations, projects, and advanced scripting Automation Workflows - Common automation patterns, daily reports, release automation, and team collaboration workflows Troubleshooting - Solutions for authentication, permissions, rate limiting, and common errors Example Scripts Practical automation scripts (see examples/ directory): auto-pr-create.sh - Automated PR creation workflow issue-triage.sh - Bulk issue labeling and assignment workflow-monitor.sh - Watch and notify on workflow completion release-automation.sh - Complete release workflow automation External Documentation Official Manual : https://cli.github.com/manual GitHub Community : https://github.com/cli/cli/discussions API Documentation : https://docs.github.com/en/rest Extension Marketplace : https://github.com/topics/gh-extension JSON Output Use --json flag for structured output. Always verify field names with --help as they differ from GitHub API names.

Check available JSON fields for any command

gh repo view --help | grep -A 50 "JSON FIELDS" gh pr list --help | grep -A 50 "JSON FIELDS" Common JSON Field Corrections Wrong (API-style) Correct (gh CLI) stargazersCount stargazerCount forksCount forkCount watchersCount watchers openIssuesCount issues Repository View Fields

Common fields for gh repo view --json

gh repo view owner/repo --json name,description,stargazerCount,forkCount,updatedAt,url,readme Tips Use --web flag to open items in browser for detailed view Leverage interactive prompts by omitting parameters - most commands support interactive mode Apply filters with --author , --label , --state to narrow down lists efficiently Add --json flag to enable scriptable output for automation Always check --help for valid JSON field names - they differ from GitHub API Use gh repo create --template to scaffold from template repositories Enable auto-merge with gh pr merge --auto for PRs that pass checks