github-cli

GitHub CLI Workflows

Advanced reference for GitHub CLI operations. Requires gh to be installed and authenticated.

Documentation: https://cli.github.com/manual/

For basic commands (create/list/view PRs, issues, repos, releases), see references/basic-commands.md.

Prerequisites

If gh is not installed or not authenticated, instruct the user to run:

# Install: brew install gh (macOS) or see https://github.com/cli/cli/blob/trunk/docs/install_linux.md
gh auth login
gh auth status

PR Review & Inspection

# Review actions
gh pr review 123 --approve
gh pr review 123 --request-changes --body "Please fix..."
gh pr review 123 --comment --body "Looks good but..."

# Merge
gh pr merge 123 --squash --delete-branch

# Checks, diff, comments
gh pr checks 123
gh pr diff 123
gh api repos/{owner}/{repo}/pulls/123/comments

Actions / Workflows

# List runs (optionally filter by workflow)
gh run list
gh run list --workflow build.yml

# Inspect a run
gh run view 12345
gh run view 12345 --log

# Re-run failures
gh run rerun 12345 --failed

# Watch a running workflow
gh run watch 12345

API Access

# REST
gh api repos/{owner}/{repo}
gh api repos/{owner}/{repo}/issues --method POST --field title="New issue" --field body="Description"

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

# Pagination
gh api repos/{owner}/{repo}/pulls --paginate

Search

gh search code "function_name" --repo owner/repo
gh search issues "bug" --repo owner/repo --state open
gh search prs "feature" --repo owner/repo --state open

Tips

• Use --json flag with --jq for structured output: gh pr list --json number,title --jq '.[].title'
• Use --web to open any resource in your browser
• Set GH_REPO environment variable to avoid specifying --repo each time
• Use gh alias set to create custom shortcuts
• GitHub CLI respects GITHUB_TOKEN environment variable for authentication