gh-cli

<!-- TOC: Quick Start | THE EXACT PROMPT | Essential Commands | AGENTS.md Blurb | When to Use | References -->

gh-cli — GitHub CLI

Core Capability: Interact with GitHub repositories and services from the command line using gh.

Quick Start

# Install
# macOS
brew install gh

# Linux (Debian/Ubuntu)
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt update && sudo apt install gh

# Check auth
gh auth status

# Login
gh auth login

# Clone repo
gh repo clone owner/repo

THE EXACT PROMPT — Pull Request Workflow

# Create PR from current branch
gh pr create --fill

# Create PR with title/body
gh pr create --title "Add feature" --body "Description"

# View PR
gh pr view 45
gh pr view 45 --web

# Checkout PR locally
gh pr checkout 45

# Review PR
gh pr review 45 --approve
gh pr review 45 --request-changes --body "Please fix X"

# Merge PR
gh pr merge 45 --squash
gh pr merge 45 --merge --delete-branch

THE EXACT PROMPT — Issues

# List issues
gh issue list

# Create issue
gh issue create --title "Bug: Login fails" --body "Description"

# View issue
gh issue view 123

# Close issue
gh issue close 123

# Comment on issue
gh issue comment 123 --body "Working on this"

# Add labels
gh issue edit 123 --add-label "bug,priority:high"

THE EXACT PROMPT — Actions (CI/CD)

# List workflow runs
gh run list

# View run details
gh run view 12345

# Watch run in progress
gh run watch 12345

# View logs
gh run view 12345 --log

# Rerun failed jobs
gh run rerun 12345 --failed

# Run workflow manually
gh workflow run deploy.yml -f environment=production

THE EXACT PROMPT — Releases

# Create release
gh release create v1.0.0 --title "Version 1.0" --generate-notes

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

# Download assets
gh release download v1.0.0

Essential Commands

| Category | Command | Description | |----------|---------|-------------| | Repo | gh repo clone owner/repo | Clone repository | | Repo | gh repo create my-repo --public | Create new repo | | PR | gh pr create --fill | Create PR from branch | | PR | gh pr checkout 45 | Checkout PR locally | | PR | gh pr merge 45 --squash | Merge with squash | | Issue | gh issue create --title "X" | Create issue | | Issue | gh issue list | List issues | | Actions | gh run list | List workflow runs | | Actions | gh run watch | Watch current run | | Release | gh release create v1.0 | Create release |

Quick PR Workflow

# Create branch, commit, push, create PR
git checkout -b feature/my-feature
# ... make changes ...
git add . && git commit -m "Add feature"
git push -u origin feature/my-feature
gh pr create --fill

# Review and merge
gh pr checkout 45
gh pr review --approve
gh pr merge --squash --delete-branch

AGENTS.md Blurb

Copy this to your project's AGENTS.md:

### GitHub CLI (gh)

The `gh` CLI is configured and authenticated.

Common tasks:

- Create PR: `gh pr create --fill`
- List open PRs: `gh pr list`
- Check CI status: `gh pr checks`
- Create issue: `gh issue create --title "..." --body "..."`

Repo: `https://github.com/<OWNER>/<REPO>`

When to Use

• Creating PRs without leaving the terminal
• Automating issue creation in scripts
• Checking CI status: gh pr checks
• Viewing PR comments: gh pr view 123 --comments
• Watching actions run: gh run watch

References

| Topic | Reference | |-------|-----------| | Full command reference | [COMMANDS.md](references/COMMANDS.md) | | API & GraphQL | [API.md](references/API.md) | | Common workflows | [WORKFLOWS.md](references/WORKFLOWS.md) |