cli-gh

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
• Browse repositories, PRs, and files in the browser

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)
• Reverting pull requests (creates a new revert PR)
• 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 GitHubgh auth login# Login and copy OAuth code to clipboard automaticallygh auth login --clipboard# Check authentication statusgh auth status# Check auth status with JSON outputgh auth status --json# Configure git to use gh as credential helpergh auth setup-git

Pull Requests

Creating PRs

# Create PR interactivelygh pr create# Create PR with title and bodygh pr create --title "Add feature" --body "Description"# Create PR to specific branchgh pr create --base main --head feature-branch# Create draft PRgh pr create --draft# Create PR from current branchgh pr create --fill  # Uses commit messages# Create PR with Copilot Code Reviewgh pr create --reviewer @copilot

Viewing PRs

# List PRsgh pr list# List my PRsgh pr list --author @me# View PR detailsgh pr view 123# View PR in browsergh pr view 123 --web# View PR diffgh pr diff 123# View PR diff excluding specific filesgh pr diff 123 --exclude "*.lock"# Check PR statusgh pr status

Managing PRs

# Checkout PR locallygh pr checkout 123# Review PRgh pr review 123 --approvegh pr review 123 --comment --body "Looks good!"gh pr review 123 --request-changes --body "Please fix X"# Request Copilot Code Reviewgh pr edit 123 --add-reviewer @copilot# Merge PRgh pr merge 123gh pr merge 123 --squashgh pr merge 123 --rebasegh pr merge 123 --merge# Close PRgh pr close 123# Reopen PRgh pr reopen 123# Ready draft PRgh pr ready 123# Update PR branch with base branchgh pr update-branch 123# Revert a merged PR (creates a new revert PR)gh pr revert 123

PR Checks

# View PR checksgh pr checks 123# Watch PR checksgh pr checks 123 --watch

Issues

Creating Issues

# Create issue interactivelygh issue create# Create issue with title and bodygh issue create --title "Bug report" --body "Description"# Use a Markdown issue template as interactive/editor starting body textgh issue create --template "Bug Report"# Create issue with labelsgh issue create --title "Bug" --label bug,critical# Assign issuegh issue create --title "Task" --assignee @me# Set the issue type (GitHub.com and GHES 3.17+)gh issue create --type Bug

--template cannot be combined with --body or --body-file; use it with prompts, --editor, or --web. For YAML issue forms, fetch and render the form fields yourself for non-interactive automation, or finish in the browser.

Viewing Issues

# List issuesgh issue list# List my issuesgh issue list --assignee @me# List by labelgh issue list --label bug# Filter by issue typegh issue list --type Bug# Advanced issue searchgh issue list --search "is:open label:bug sort:created-desc"# View issue detailsgh issue view 456# View in browsergh issue view 456 --web

Managing Issues

# Close issuegh issue close 456# Close as duplicate, linking to the original issuegh issue close 123 --duplicate-of 456# Reopen issuegh issue reopen 456# Edit issuegh issue edit 456 --title "New title"gh issue edit 456 --add-label buggh issue edit 456 --add-assignee @user# Comment on issuegh issue comment 456 --body "Update"# Create branch to work on issuegh issue develop 456 --checkout

Issue Types, Sub-Issues & Relationships

Issue types and sub-issues require GitHub.com or GHES 3.17+; blocking relationships require GHES 3.19+.

# Set or remove the issue typegh issue edit 456 --type Buggh issue edit 456 --remove-type# Create a sub-issue under a parentgh issue create --parent 100# Organize existing issues into a parent/child hierarchygh issue edit 100 --add-sub-issue 123,124gh issue edit 100 --remove-sub-issue 123gh issue edit 123 --parent 100gh issue edit 123 --remove-parent# Track blocked-by / blocking relationshipsgh issue create --blocked-by 200,201 --blocking 300gh issue edit 123 --add-blocked-by 200 --add-blocking 300,301gh issue edit 123 --remove-blocked-by 200 --remove-blocking 301

Discussions

When the user asks to list, view, create, edit, or comment on GitHub Discussions, see references/discussions.md. The gh discussion command set is in preview and subject to change.

Copilot Agent Tasks

Delegate work to the Copilot coding agent and track its sessions. The gh agent-task command set (aliases gh agent, gh agents) is in preview.

# Create an agent task on the current repositorygh agent-task create "Improve the performance of the data processing pipeline"# List your most recent agent tasksgh agent-task listgh agent-task list --json id,name,state# View an agent task session (by PR number, session ID, or URL)gh agent-task view 123gh agent-task view <session-id> --json state --jq '.state'

Agent Skills

Discover, install, and publish agent skills from GitHub repositories. The gh skill command set (alias gh skills) is in preview.

# Search for skills across GitHubgh skill search terraform# Preview a skill before installinggh skill preview github/awesome-copilot documentation-writer# Install a skill (default scope: project)gh skill install github/awesome-copilot documentation-writergh skill install owner/repo skill-name --scope user --pin v1.2.0# Include skills in hidden dirs (.claude/skills/, .agents/skills/, .github/skills/)gh skill install owner/repo skill-name --allow-hidden-dirs# List installed skills and update themgh skill listgh skill update --all# Validate and publish your own skillsgh skill publish --dry-run

Repository Operations

Repository Info

# View repositorygh repo view# View in browsergh repo view --web# Clone repositorygh repo clone owner/repo# Clone without adding upstream remotegh repo clone owner/repo --no-upstream# Fork repositorygh repo fork owner/repo# List repositoriesgh repo list owner

Repository Management

# Create repositorygh repo create my-repo --publicgh repo create my-repo --private# Sync forkgh repo sync owner/repo# Set default repositorygh repo set-default# Configure the squash-merge commit message defaultgh repo edit --squash-merge-commit-message COMMIT_MESSAGES

Reading Repo Contents

Read files and directories without cloning. The gh repo read-file and gh repo read-dir commands are in preview and subject to change.

# Read a file from the default branch (paged in a TTY, raw when piped)gh repo read-file README.md --repo cli/cli# Read from a specific branch, tag, or commitgh repo read-file go.mod --ref v2.94.0 --repo cli/cli# Write to disk instead of stdout (--clobber to overwrite)gh repo read-file README.md --output ./README.md --clobber# Refuse escape sequences by default; opt in for TTY/piped outputgh repo read-file script.sh --allow-escape-sequences# List a directory (root when no path given)gh repo read-dir script --repo cli/cli# Inspect entries as JSON for scriptinggh repo read-dir docs --repo cli/cli --json name,path,type,size

Search

When the user asks to search GitHub repositories, issues, or pull requests, see references/search.md.

Labels

When the user asks to list, create, edit, or clone repository labels, see references/labels.md.

Codespaces

When the user asks to list, create, connect to, or manage files within GitHub Codespaces, see references/codespaces.md.

Browse

Open repositories, files, and resources in the browser.

# Open current repo in browsergh browse# Open specific filegh browse src/main.go# Open file at specific linegh browse src/main.go:42# Open blame view for a filegh browse --blame src/main.go# Open Actions tabgh browse --actions# Open specific branchgh browse --branch feature

Releases

When the user asks to create, list, view, or download GitHub releases, see references/releases.md.

Gists

When the user asks to create, list, view, or edit GitHub gists, see references/gists.md.

Configuration

# Set default editorgh config set editor vim# Set default git protocolgh config set git_protocol ssh# View configurationgh config list# Set browsergh config set browser firefox

Quick Reference

Common gh operations at a glance:

Additional Resources

Reference Guides

For detailed patterns and advanced usage, see:

• Discussions - List, view, create, edit, and comment on GitHub Discussions (preview)
• 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

When the user wants to use --json flags or needs the correct gh CLI JSON field names, see references/json-output.md.

Tips

1. Use --web flag to open items in browser for detailed view
2. Leverage interactive prompts by omitting parameters - most commands support interactive mode
3. Apply filters with --author, --label, --state to narrow down lists efficiently
4. Add --json flag to enable scriptable output for automation
5. Always check --help for valid JSON field names - they differ from GitHub API
6. Use gh repo create --template to scaffold from template repositories
7. Enable auto-merge with gh pr merge --auto for PRs that pass checks