---

name: gh-cli description: GitHub CLI (gh) command reference and usage patterns. Use when working with GitHub from the command line - PRs, issues, repos, workflows, releases, and API calls.

GitHub CLI (gh) Reference

GitHub CLI brings GitHub to your terminal. Use gh for pull requests, issues, repos, workflows, and more.

Quick Start

Copy# Authenticate
gh auth login

# Check status
gh auth status

Command Reference

Authentication (gh auth)

Pull Requests (gh pr)

Common PR workflows:

Copy# Create PR interactively
gh pr create

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

# Create draft PR
gh pr create --draft

# Merge with squash
gh pr merge --squash

# View PR in browser
gh pr view --web

Issues (gh issue)

Common issue workflows:

Copy# Create issue interactively
gh issue create

# Create with labels and assignee
gh issue create --title "Bug" --label "bug" --assignee "@me"

# List open bugs assigned to me
gh issue list --label "bug" --assignee "@me"

# Create branch from issue
gh issue develop 123 --checkout

Repositories (gh repo)

Common repo workflows:

Copy# Create new repo from current directory
gh repo create --source=. --push

# Create private repo
gh repo create my-project --private

# Clone and cd into repo
gh repo clone owner/repo -- --depth=1

# Sync fork with upstream
gh repo sync owner/fork

Workflows & Actions (gh workflow, gh run)

Workflows:

Runs:

Common workflow patterns:

Copy# Trigger workflow with inputs
gh workflow run deploy.yml -f environment=staging

# Watch current branch's latest run
gh run watch

# Download artifacts from run
gh run download <run-id>

# Re-run failed jobs only
gh run rerun <run-id> --failed

Releases (gh release)

Common release patterns:

Copy# Create release with auto-generated notes
gh release create v1.0.0 --generate-notes

# Create release with assets
gh release create v1.0.0 ./dist/*.tar.gz

# Download specific asset
gh release download v1.0.0 --pattern "*.tar.gz"

# Create draft release
gh release create v1.0.0 --draft

Search (gh search)

Search examples:

Copy# Find repos by topic
gh search repos --topic=cli --language=go

# Search issues across GitHub
gh search issues "memory leak" --state=open

# Search your PRs
gh search prs --author=@me --state=open

# Search code (requires auth)
gh search code "function authenticate" --repo=owner/repo

Codespaces (gh codespace / gh cs)

Secrets & Variables (gh secret, gh variable)

Secrets:

Variables:

Examples:

Copy# Set secret from prompt
gh secret set API_KEY

# Set secret from file
gh secret set CERT < cert.pem

# Set environment secret
gh secret set API_KEY --env production

# Set org-level variable
gh variable set NODE_ENV --org my-org -v "production"

API (gh api)

Make authenticated requests to GitHub's REST or GraphQL API.

Copygh api <endpoint> [flags]

Key flags:

Placeholders: {owner}, {repo}, {branch} auto-populate from current repo.

Examples:

Copy# Get current user
gh api user

# List repo issues
gh api repos/{owner}/{repo}/issues

# Create issue comment
gh api repos/{owner}/{repo}/issues/123/comments -f body="Comment text"

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

# Paginate and filter
gh api repos/{owner}/{repo}/issues --paginate -q '.[].title'

# POST with JSON body
gh api repos/{owner}/{repo}/labels -f name=bug -f color=ff0000

Other Commands

Global Flags

These work with most commands:

Environment Variables

Tips

1. Use --web or -w to open in browser: gh pr view --web
2. Use @me for current user: gh issue list --assignee @me
3. Use jq filtering for JSON output: gh api user -q '.login'
4. Tab completion - run gh completion and follow instructions
5. Aliases - create shortcuts: gh alias set pv 'pr view'
6. Extensions - extend functionality: gh extension install owner/repo

Resources

• Official Manual
• GitHub Docs
• CLI Repository