GitHub

Website: https://github.com CLI Tool: gh Authentication: gh auth login

Description

GitHub is the world's leading platform for version control and collaboration. Use the gh CLI for repository management, issues, pull requests, and more. AI agents can interact with GitHub programmatically via CLI commands or REST API.

Commands

Clone Repository

gh repo clone <owner>/<repo>

Clone a GitHub repository to your local machine.

Create Repository

gh repo create <name> [--public|--private] [--description "desc"]

Create a new GitHub repository. Use --public for public repos or --private for private repos.

View Repository

gh repo view [<owner>/<repo>] [--json] [--web]

View repository details. Omit repo name to view current repo. Use --json for structured output.

List Issues

gh issue list [--repo <owner>/<repo>] [--state open|closed|all] [--label <label>] [--json]

List issues in a repository. Filter by state or labels. Use --json for machine-readable output.

Create Issue

gh issue create --title "Issue title" --body "Issue description" [--label <label>] [--assignee <user>]

Create a new issue in the current repository.

View Issue

gh issue view <issue-number> [--json] [--web]

View details of a specific issue. Use --json for structured output.

Close Issue

gh issue close <issue-number> [--comment "Closing comment"]

Close an issue with an optional comment.

Create Pull Request

gh pr create --title "PR title" --body "PR description" [--base <branch>] [--draft]

Create a pull request. Use --draft for draft PRs. Base branch defaults to main/master.

List Pull Requests

gh pr list [--repo <owner>/<repo>] [--state open|closed|merged|all] [--json]

List pull requests with optional filters.

Review Pull Request

gh pr review <pr-number> [--approve|--request-changes|--comment] [--body "comment"]

Review a pull request. Choose one: approve, request changes, or comment only.

Merge Pull Request

gh pr merge <pr-number> [--squash|--merge|--rebase] [--delete-branch]

Merge a pull request. Choose merge strategy: squash, merge, or rebase.

Check PR Status

gh pr status [--json]

Show status of relevant pull requests (created, assigned, or need review).

View PR Diff

gh pr diff <pr-number>

View the diff of a pull request.

Check API Rate Limit

gh api rate_limit [--json]

Check your current API rate limit status. Use --json for structured output.

Search Repositories

gh search repos <query> [--limit <n>] [--json]

Search GitHub repositories matching the query.

Search Issues

gh search issues <query> [--repo <owner>/<repo>] [--limit <n>] [--json]

Search issues and pull requests across GitHub.

Run Workflow

gh workflow run <workflow-name> [--ref <branch>]

Trigger a GitHub Actions workflow.

View Workflow Runs

gh run list [--workflow <workflow-name>] [--limit <n>] [--json]

List recent workflow runs.

Examples

Clone and Create PR Workflow

# Clone repository
gh repo clone owner/repo
cd repo

# Create feature branch
git checkout -b feature/new-feature

# Make changes
echo "new feature" > feature.txt
git add feature.txt
git commit -m "feat: add new feature"

# Push and create PR
git push origin feature/new-feature
gh pr create --title "Add new feature" --body "This PR adds a new feature" --base main

Bug Fix Workflow

# Create fix branch
git checkout -b fix/bug-description

# Fix the bug
# ... make changes ...
git add .
git commit -m "fix: description of fix"

# Push and create PR
git push origin fix/bug-description
gh pr create --title "Fix: bug description" --body "Fixes #123"

Review and Merge PR Workflow

# List open PRs
gh pr list --state open

# Review a PR
gh pr view 42
gh pr diff 42
gh pr checks 42

# Approve and merge
gh pr review 42 --approve --body "LGTM!"
gh pr merge 42 --squash --delete-branch

Issue Management Workflow

# List open issues
gh issue list --state open --json number,title,labels

# Create issue
gh issue create --title "Bug: something is broken" --body "Description of the bug" --label bug

# Close issue when fixed
gh issue close 123 --comment "Fixed in PR #456"

Repository Setup Workflow

# Create new repository
gh repo create my-project --public --description "My new project"

# Clone and setup
gh repo clone my-project
cd my-project
echo "# My Project" > README.md
git add README.md
git commit -m "Initial commit"
git push origin main

Notes

• Rate Limits: GitHub API has rate limits. Authenticated users get 5,000 requests/hour, unauthenticated get 60. Check with gh api rate_limit
• JSON Output: Most gh commands support --json flag for machine-readable structured output, ideal for AI agents
• Authentication: Use gh auth login to authenticate. Set GITHUB_TOKEN environment variable for API access
• Help: Every command supports --help flag for detailed usage information
• Configuration: GitHub CLI respects .gitconfig settings and can be configured with gh config set
• Web Interface: Use --web flag on many commands to open the web interface in your browser
• Default Repository: Many commands work on the current directory's repository automatically
• Branch Protection: Some operations may be restricted by branch protection rules
• GraphQL API: For advanced queries, use gh api graphql -f query='...'
• REST API Access: Use gh api <endpoint> to access any GitHub REST API endpoint directly