Github CLI

GitHub CLI (gh) Usage Skill

Purpose

GitHub CLI (gh) is the official command-line interface to GitHub, enabling direct interaction with repositories, pull requests, issues, GitHub Actions, and the GitHub API without leaving the terminal. This skill provides systematic guidance for using gh effectively while maintaining security through the integrated write-guard protection.

When to Use This Skill

Invoke this skill when:

• Creating or managing pull requests and issues via command line
• Querying GitHub API (REST or GraphQL) for repository data
• Automating GitHub workflows and Actions
• Managing releases, gists, projects, or codespaces
• Scripting GitHub operations for CI/CD pipelines
• User explicitly mentions "gh", "github cli", or requests GitHub interactions

Core Concepts

Authentication First

Before any gh operations, verify authentication status:

gh auth status              # Check current authentication
gh auth login               # Interactive authentication setup
gh auth refresh             # Refresh expired tokens

Authentication automatically stores Git credentials when HTTPS is selected as the preferred protocol.

gh vs git Distinction

• git: Version control operations (commit, push, pull) - works with any remote service
• gh: GitHub-specific operations (PRs, issues, API, Actions) - GitHub only

Use gh for GitHub platform interactions; use git for repository version control.

Quick Command Reference

Common Operations

Repositories:

gh repo view OWNER/REPO     # View repository details
gh repo clone OWNER/REPO    # Clone repository
gh repo list OWNER          # List repositories

Pull Requests:

gh pr list                  # List pull requests
gh pr view 123              # View PR details
gh pr checkout 123          # Checkout PR branch
gh pr create --draft        # Create draft PR (⚠️ write operation)

Issues:

gh issue list               # List issues
gh issue view 456           # View issue details
gh issue create             # Create issue (⚠️ write operation)

GitHub API:

gh api repos/{owner}/{repo}                    # GET request (read-only)
gh api -X GET /endpoint -f param=value         # GET with parameters
gh api --paginate /endpoint                    # Paginated requests
gh api repos/{owner}/{repo} --jq '.stars'      # JSON filtering with jq

Search:

gh search prs --review-requested=@me           # Search PRs
gh search issues "is:open label:bug"           # Search issues
gh search code "function name"                 # Search code

For detailed commands, patterns, and examples, see:

• references/gh-commands.md - Complete command catalog by category
• references/gh-api-patterns.md - REST/GraphQL API examples and authentication
• references/gh-scripting.md - Automation patterns, output formatting, and best practices

Security Considerations

Write Protection

This plugin includes a security guard that blocks write operations by default:

Blocked operations:

• Repository modifications: gh repo create, gh repo delete, gh repo archive
• PR/Issue changes: gh pr create, gh pr merge, gh issue close, gh issue edit
• Release management: gh release create, gh release delete
• API write methods: gh api -X POST, gh api -X PUT, gh api -X PATCH, gh api -X DELETE
• Workflow triggers: gh workflow run, gh run cancel

Allowed operations:

• All read commands: gh repo view, gh pr list, gh issue list
• API GET requests: gh api repos/{owner}/{repo}
• Search operations: gh search prs, gh search issues

Authorization Workflow

When write operations are needed:

1. Ask user for explicit permission first
2. User authorizes the specific write operation
3. Perform authorized write operations only after confirmation

API Method Security

# ❌ Blocked - Write methods
gh api -X POST /repos/{owner}/{repo}/issues
gh api -X PUT /repos/{owner}/{repo}
gh api -X DELETE /repos/{owner}/{repo}/issues/123

# ❌ Blocked - Implicit POST via field parameters
gh api /repos/{owner}/{repo}/issues -f title="Bug"

# ✅ Allowed - Explicit GET with parameters
gh api -X GET /repos/{owner}/{repo}/issues -f state=open -f labels=bug

Note: Field parameters (-f, -F, --field) trigger implicit POST unless -X GET is explicitly specified.

Configuration

The security guard can be configured in ~/.claude/settings.json:

{
  "githubWriteGuard": {
    "enabled": true
  }
}

Note: The guard is enabled by default. Set enabled: false to disable write protection.

Available Commands

• /gh-cli-status - View current guard status

Environment Variables

export GH_REPO="owner/repo"              # Override repository context
export GH_HOST="github.example.com"      # Use specific GitHub instance
export GITHUB_TOKEN="ghp_..."            # Set API token (not recommended)
export PAGER="less -FX"                  # Configure pager

Troubleshooting

Authentication:

gh auth status          # Check authentication state
gh auth refresh         # Refresh expired token
gh auth login           # Re-authenticate

API Rate Limits:

gh api rate_limit                               # Check rate limit
gh api --cache 1h repos/{owner}/{repo}/releases # Use caching

Debug Mode:

gh pr create --title "Test" --verbose           # Verbose output
GH_DEBUG=api gh api repos/{owner}/{repo}        # See HTTP requests

References

Detailed documentation:

• references/gh-commands.md - Complete command catalog by category
• references/gh-api-patterns.md - REST/GraphQL examples and authentication
• references/gh-scripting.md - Automation patterns and best practices

Official resources:

• GitHub CLI Manual: https://cli.github.com/manual/
• GitHub Docs: https://docs.github.com/en/github-cli
• Repository: https://github.com/cli/cli
• Scripting Guide: https://github.blog/engineering/engineering-principles/scripting-with-github-cli/