# GitHub CLI (gh) Complete Learning Guide

## Table of Contents
- [Getting Started](#getting-started)
- [Core Commands](#core-commands)
- [GitHub Actions Commands](#github-actions-commands)
- [Additional Commands](#additional-commands)

---

## Getting Started

### Installation Check
```bash
gh --version
```

### First Steps: Authentication
This is where you **must** start:

```bash
gh auth login
```

Follow the interactive prompts to:
1. Choose GitHub.com or GitHub Enterprise Server
2. Select HTTPS or SSH protocol
3. Authenticate via web browser or token

Check authentication status:
```bash
gh auth status
```

---

## Core Commands

### 1. gh auth - Authentication Management

**Purpose:** Manage GitHub authentication

#### Key Subcommands:
```bash
gh auth login          # Login to GitHub account
gh auth logout         # Logout from GitHub account
gh auth status         # Check authentication status
gh auth refresh        # Refresh authentication credentials
gh auth token          # Print the authentication token
```

#### Practical Examples:
```bash
# Login to GitHub Enterprise
gh auth login --hostname github.enterprise.com

# Get your current token
gh auth token

# Check which account you're logged in as
gh auth status
```

---

### 2. gh repo - Repository Operations

**Purpose:** Create, clone, view, and manage repositories

#### Key Subcommands:
```bash
gh repo create         # Create a new repository
gh repo clone          # Clone a repository
gh repo fork           # Fork a repository
gh repo list           # List repositories
gh repo view           # View repository details
gh repo delete         # Delete a repository
gh repo rename         # Rename a repository
gh repo archive        # Archive a repository
gh repo unarchive      # Unarchive a repository
gh repo sync           # Sync a fork
```

#### Practical Examples:
```bash
# Create a new public repository
gh repo create my-project --public

# Create a new private repository with description
gh repo create my-private-app --private --description "My awesome app"

# Clone a repository
gh repo clone owner/repo

# Clone your own repository (shorthand)
gh repo clone my-repo

# Fork a repository
gh repo fork owner/repo

# Fork and clone at the same time
gh repo fork owner/repo --clone

# List your repositories
gh repo list

# List repositories for a specific user/org
gh repo list microsoft --limit 10

# View repository details
gh repo view owner/repo

# View repository in browser
gh repo view owner/repo --web

# Create repo from current directory
cd my-project
git init
gh repo create --source=. --public
```

---

### 3. gh issue - Issue Management

**Purpose:** Manage GitHub issues

#### Key Subcommands:
```bash
gh issue create        # Create an issue
gh issue list          # List issues
gh issue view          # View issue details
gh issue edit          # Edit an issue
gh issue close         # Close an issue
gh issue reopen        # Reopen an issue
gh issue delete        # Delete an issue
gh issue comment       # Add a comment to an issue
gh issue status        # Show status of relevant issues
gh issue transfer      # Transfer issue to another repo
gh issue pin           # Pin an issue
gh issue unpin         # Unpin an issue
```

#### Practical Examples:
```bash
# Create an issue interactively
gh issue create

# Create an issue with flags
gh issue create --title "Bug: App crashes" --body "Description here"

# Create issue with label and assignee
gh issue create --title "Feature request" --label enhancement --assignee username

# List all open issues
gh issue list

# List issues with specific labels
gh issue list --label bug --label urgent

# List issues assigned to you
gh issue list --assignee @me

# List closed issues
gh issue list --state closed

# View an issue
gh issue view 123

# View issue in browser
gh issue view 123 --web

# Close an issue
gh issue close 123

# Close with a comment
gh issue close 123 --comment "Fixed in PR #124"

# Reopen an issue
gh issue reopen 123

# Add comment to issue
gh issue comment 123 --body "Working on this now"

# Show your issue status
gh issue status
```

---

### 4. gh pr - Pull Request Management

**Purpose:** Manage pull requests

#### Key Subcommands:
```bash
gh pr create           # Create a pull request
gh pr list             # List pull requests
gh pr view             # View pull request details
gh pr checkout         # Check out a pull request locally
gh pr diff             # View pull request diff
gh pr edit             # Edit a pull request
gh pr close            # Close a pull request
gh pr reopen           # Reopen a pull request
gh pr merge            # Merge a pull request
gh pr ready            # Mark pull request as ready for review
gh pr review           # Review a pull request
gh pr comment          # Add a comment to a pull request
gh pr checks           # Show CI status
gh pr status           # Show status of relevant PRs
```

#### Practical Examples:
```bash
# Create a PR interactively
gh pr create

# Create PR with title and body
gh pr create --title "Add new feature" --body "This PR adds..."

# Create PR with reviewers
gh pr create --title "Fix bug" --reviewer user1,user2

# Create draft PR
gh pr create --draft

# Create PR to specific branch
gh pr create --base develop

# List all open PRs
gh pr list

# List PRs by author
gh pr list --author username

# List PRs with specific label
gh pr list --label bug

# View a PR
gh pr view 42

# View PR in browser
gh pr view 42 --web

# View PR diff
gh pr diff 42

# Checkout a PR locally
gh pr checkout 42

# Check CI status
gh pr checks

# PR with specific status
gh pr list --state merged

# Review a PR (approve)
gh pr review 42 --approve

# Review with comment
gh pr review 42 --comment --body "Looks good!"

# Request changes
gh pr review 42 --request-changes --body "Please fix X"

# Merge a PR
gh pr merge 42

# Merge with squash
gh pr merge 42 --squash

# Merge and delete branch
gh pr merge 42 --merge --delete-branch

# Close a PR
gh pr close 42

# Mark draft PR as ready
gh pr ready 42
```

---

### 5. gh browse - Open Repository in Browser

**Purpose:** Quickly open repo/issue/PR in web browser

#### Examples:
```bash
# Open current repo in browser
gh browse

# Open specific repo
gh browse owner/repo

# Open specific issue
gh browse 123

# Open specific PR
gh browse 42

# Open settings page
gh browse --settings

# Open wiki
gh browse --wiki

# Open projects
gh browse --projects
```

---

### 6. gh gist - Gist Management

**Purpose:** Manage GitHub Gists

#### Key Subcommands:
```bash
gh gist create         # Create a new gist
gh gist list           # List gists
gh gist view           # View a gist
gh gist edit           # Edit a gist
gh gist delete         # Delete a gist
gh gist clone          # Clone a gist
```

#### Practical Examples:
```bash
# Create gist from file
gh gist create file.txt

# Create public gist
gh gist create file.txt --public

# Create gist with description
gh gist create file.txt -d "My code snippet"

# Create gist from stdin
echo "Hello World" | gh gist create -

# Create multi-file gist
gh gist create file1.txt file2.py

# List your gists
gh gist list

# List public gists only
gh gist list --public

# View a gist
gh gist view <gist-id>

# Clone a gist
gh gist clone <gist-id>

# Delete a gist
gh gist delete <gist-id>
```

---

### 7. gh release - Release Management

**Purpose:** Manage GitHub releases

#### Key Subcommands:
```bash
gh release create      # Create a release
gh release list        # List releases
gh release view        # View release details
gh release delete      # Delete a release
gh release download    # Download release assets
gh release upload      # Upload assets to a release
```

#### Practical Examples:
```bash
# Create a release
gh release create v1.0.0

# Create release with notes
gh release create v1.0.0 --notes "Release notes here"

# Create release from notes file
gh release create v1.0.0 --notes-file CHANGELOG.md

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

# Create pre-release
gh release create v1.0.0-beta --prerelease

# List releases
gh release list

# View specific release
gh release view v1.0.0

# Download release assets
gh release download v1.0.0

# Download from specific repo
gh release download v1.0.0 --repo owner/repo

# Upload assets to existing release
gh release upload v1.0.0 ./new-asset.zip

# Delete a release
gh release delete v1.0.0
```

---

### 8. gh codespace - Codespaces Management

**Purpose:** Manage GitHub Codespaces

#### Key Subcommands:
```bash
gh codespace create    # Create a codespace
gh codespace list      # List codespaces
gh codespace delete    # Delete a codespace
gh codespace code      # Open codespace in VS Code
gh codespace ssh       # SSH into a codespace
gh codespace logs      # View codespace logs
gh codespace ports     # Manage codespace ports
```

#### Practical Examples:
```bash
# Create a codespace
gh codespace create

# Create for specific repo
gh codespace create --repo owner/repo

# List your codespaces
gh codespace list

# Open codespace in VS Code
gh codespace code

# SSH into codespace
gh codespace ssh

# Delete a codespace
gh codespace delete
```

---

### 9. gh org - Organization Management

**Purpose:** Manage organization memberships and settings

#### Key Subcommands:
```bash
gh org list            # List organizations
```

#### Practical Examples:
```bash
# List organizations you belong to
gh org list
```

---

### 10. gh project - Project Management

**Purpose:** Manage GitHub Projects (beta)

#### Key Subcommands:
```bash
gh project create      # Create a project
gh project list        # List projects
gh project view        # View project details
gh project edit        # Edit project
gh project delete      # Delete project
gh project item-add    # Add item to project
gh project item-create # Create and add item
gh project item-list   # List project items
```

#### Practical Examples:
```bash
# List projects
gh project list

# List org projects
gh project list --owner org-name

# Create a project
gh project create --title "My Project"

# View project
gh project view 1

# Add issue to project
gh project item-add 1 --issue 123

# List project items
gh project item-list 1
```

---

## GitHub Actions Commands

### 11. gh workflow - Workflow Management

**Purpose:** View and manage GitHub Actions workflows

#### Key Subcommands:
```bash
gh workflow list       # List workflows
gh workflow view       # View workflow details
gh workflow run        # Trigger a workflow
gh workflow enable     # Enable a workflow
gh workflow disable    # Disable a workflow
```

#### Practical Examples:
```bash
# List all workflows
gh workflow list

# View specific workflow
gh workflow view "CI"

# Manually trigger a workflow
gh workflow run "CI"

# Run workflow on specific branch
gh workflow run "Deploy" --ref develop

# Enable a workflow
gh workflow enable "CI"

# Disable a workflow
gh workflow disable "Old Workflow"
```

---

### 12. gh run - Workflow Run Management

**Purpose:** View and manage workflow runs

#### Key Subcommands:
```bash
gh run list            # List workflow runs
gh run view            # View run details
gh run watch           # Watch a run in progress
gh run rerun           # Rerun a workflow run
gh run cancel          # Cancel a workflow run
gh run download        # Download run artifacts
gh run delete          # Delete a workflow run
```

#### Practical Examples:
```bash
# List recent workflow runs
gh run list

# List runs for specific workflow
gh run list --workflow="CI"

# List failed runs
gh run list --status=failure

# View specific run
gh run view 123456

# View run in browser
gh run view 123456 --web

# Watch run in real-time
gh run watch

# Rerun a failed run
gh run rerun 123456

# Rerun only failed jobs
gh run rerun 123456 --failed

# Cancel a run
gh run cancel 123456

# Download artifacts
gh run download 123456

# Delete old runs
gh run delete 123456
```

---

### 13. gh cache - Actions Cache Management

**Purpose:** Manage GitHub Actions caches

#### Key Subcommands:
```bash
gh cache list          # List caches
gh cache delete        # Delete a cache
```

#### Practical Examples:
```bash
# List all caches
gh cache list

# Delete specific cache
gh cache delete <cache-id>

# Delete all caches (using key pattern)
gh cache delete --all
```

---

## Additional Commands

### 14. gh agent-task - AI Agent Tasks (Preview)

**Purpose:** Work with GitHub AI agent tasks (Preview feature)

⚠️ **Note:** This feature is in preview and subject to change.

#### Key Subcommands:
```bash
gh agent-task create   # Create a new agent task
gh agent-task list     # List agent tasks
gh agent-task view     # View agent task details
```

#### Aliases:
```bash
gh agent               # Alias for gh agent-task
gh agents              # Alias for gh agent-task
gh agent-tasks         # Alias for gh agent-task
```

#### Practical Examples:
```bash
# List your most recent agent tasks
gh agent-task list

# Create a new agent task on the current repository
gh agent-task create "Improve the performance of the data processing pipeline"

# View details about agent tasks associated with a pull request
gh agent-task view 123

# View details about a specific agent task by ID
gh agent-task view 12345abc-12345-12345-12345-12345abc

# Using alias
gh agent list
```

---

### 15. gh preview - Preview/Experimental Commands

**Purpose:** Access experimental and preview features

⚠️ **Note:** Preview commands are unstable and can change at any time. They are for testing and development purposes only.

#### Available Commands:
```bash
gh preview prompter    # Interactive prompter (experimental)
```

#### Practical Examples:
```bash
# Use the experimental prompter
gh preview prompter

# Note: Preview commands are subject to change
# Check the latest documentation for current features
```

---

### 16. gh alias - Command Aliases

**Purpose:** Create shortcuts for commonly used commands

#### Key Subcommands:
```bash
gh alias set           # Create an alias
gh alias list          # List aliases
gh alias delete        # Delete an alias
```

#### Practical Examples:
```bash
# Create an alias
gh alias set pv 'pr view'

# Now you can use
gh pv 42

# Create complex alias for PR creation
gh alias set pc 'pr create --fill'

# List all aliases
gh alias list

# Delete an alias
gh alias delete pv

# Useful aliases to create:
gh alias set co 'pr checkout'
gh alias set bugs 'issue list --label=bug'
gh alias set prs 'pr list --author=@me'
```

---

### 17. gh api - Direct API Access

**Purpose:** Make authenticated GitHub API requests

#### Practical Examples:
```bash
# Get user info
gh api user

# Get repo info
gh api repos/owner/repo

# List issues via API
gh api repos/owner/repo/issues

# POST request to create issue
gh api repos/owner/repo/issues -f title="Bug report"

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

# Paginate through results
gh api --paginate repos/owner/repo/issues
```

---

### 18. gh search - Search GitHub

**Purpose:** Search for repositories, issues, PRs, and code

#### Key Subcommands:
```bash
gh search repos        # Search repositories
gh search issues       # Search issues
gh search prs          # Search pull requests
gh search code         # Search code
```

#### Practical Examples:
```bash
# Search repositories
gh search repos "machine learning" --language=python

# Search by stars
gh search repos "kubernetes" --stars=">10000"

# Search issues
gh search issues "bug" --repo=owner/repo

# Search open issues with label
gh search issues "performance" --label=bug --state=open

# Search PRs
gh search prs "fix" --author=username

# Search code
gh search code "import tensorflow" --language=python

# Search in specific org
gh search repos --owner=microsoft --limit 5
```

---

### 19. gh secret - Secrets Management

**Purpose:** Manage GitHub Actions secrets

#### Key Subcommands:
```bash
gh secret list         # List secrets
gh secret set          # Create or update a secret
gh secret delete       # Delete a secret
```

#### Practical Examples:
```bash
# List repository secrets
gh secret list

# Set a secret (will prompt for value)
gh secret set SECRET_NAME

# Set secret from value
gh secret set API_KEY --body "secret-value"

# Set secret from file
gh secret set PRIVATE_KEY &lt; private-key.pem

# Set org secret
gh secret set SECRET_NAME --org my-org

# Delete a secret
gh secret delete SECRET_NAME
```

---

### 20. gh variable - Variables Management

**Purpose:** Manage GitHub Actions variables

#### Key Subcommands:
```bash
gh variable list       # List variables
gh variable set        # Create or update a variable
gh variable get        # Get a variable value
gh variable delete     # Delete a variable
```

#### Practical Examples:
```bash
# List variables
gh variable list

# Set a variable
gh variable set ENV_NAME --body "production"

# Get variable value
gh variable get ENV_NAME

# Delete variable
gh variable delete ENV_NAME
```

---

### 21. gh label - Label Management

**Purpose:** Manage issue and PR labels

#### Key Subcommands:
```bash
gh label list          # List labels
gh label create        # Create a label
gh label edit          # Edit a label
gh label delete        # Delete a label
gh label clone         # Clone labels from another repo
```

#### Practical Examples:
```bash
# List labels
gh label list

# Create a label
gh label create "priority:high" --color ff0000 --description "High priority"

# Edit label
gh label edit bug --color ee0701

# Delete label
gh label delete "old-label"

# Clone labels from another repo
gh label clone owner/source-repo
```

---

### 22. gh config - Configuration

**Purpose:** Manage gh configuration

#### Key Subcommands:
```bash
gh config get          # Get config value
gh config set          # Set config value
gh config list         # List config values
```

#### Practical Examples:
```bash
# Set default editor
gh config set editor vim

# Set default git protocol
gh config set git_protocol ssh

# Set default pager
gh config set pager less

# Get config value
gh config get editor

# List all config
gh config list
```

---

### 23. gh extension - Extension Management

**Purpose:** Manage gh CLI extensions

#### Key Subcommands:
```bash
gh extension install   # Install an extension
gh extension list      # List installed extensions
gh extension upgrade   # Upgrade extensions
gh extension remove    # Remove an extension
gh extension create    # Create a new extension
gh extension browse    # Browse available extensions
```

#### Practical Examples:
```bash
# Browse available extensions
gh extension browse

# Install an extension
gh extension install owner/gh-extension-name

# List installed extensions
gh extension list

# Upgrade all extensions
gh extension upgrade --all

# Remove extension
gh extension remove gh-extension-name

# Popular extensions to try:
gh extension install github/gh-copilot
gh extension install dlvhdr/gh-dash
```

---

### 24. gh copilot - GitHub Copilot CLI

**Purpose:** Get command suggestions using AI (requires Copilot subscription)

#### Key Subcommands:
```bash
gh copilot explain     # Explain a command
gh copilot suggest     # Get command suggestions
```

#### Practical Examples:
```bash
# Get suggestion for a task
gh copilot suggest "list all running docker containers"

# Explain a command
gh copilot explain "git rebase -i HEAD~3"
```

---

### 25. gh status - Status Overview

**Purpose:** View status of your work across GitHub

#### Practical Examples:
```bash
# Show your status (assigned issues, PRs, etc.)
gh status

# Show status for specific org
gh status --org my-org
```

---

### 26. gh ssh-key - SSH Key Management

**Purpose:** Manage SSH keys

#### Key Subcommands:
```bash
gh ssh-key list        # List SSH keys
gh ssh-key add         # Add SSH key
gh ssh-key delete      # Delete SSH key
```

#### Practical Examples:
```bash
# List SSH keys
gh ssh-key list

# Add new SSH key
gh ssh-key add ~/.ssh/id_ed25519.pub --title "My laptop"

# Delete SSH key
gh ssh-key delete <key-id>
```

---

### 27. gh gpg-key - GPG Key Management

**Purpose:** Manage GPG keys for commit signing

#### Key Subcommands:
```bash
gh gpg-key list        # List GPG keys
gh gpg-key add         # Add GPG key
gh gpg-key delete      # Delete GPG key
```

#### Practical Examples:
```bash
# List GPG keys
gh gpg-key list

# Add GPG key
gh gpg-key add key.asc

# Delete GPG key
gh gpg-key delete <key-id>
```

---

### 28. gh completion - Shell Completion

**Purpose:** Generate shell completion scripts

#### Practical Examples:
```bash
# Install bash completion
gh completion -s bash > /usr/local/etc/bash_completion.d/gh

# Install zsh completion
gh completion -s zsh > /usr/local/share/zsh/site-functions/_gh

# Install fish completion
gh completion -s fish > ~/.config/fish/completions/gh.fish
```

---

### 29. gh ruleset - Repository Rulesets

**Purpose:** Manage repository rulesets

#### Key Subcommands:
```bash
gh ruleset list        # List rulesets
gh ruleset view        # View ruleset details
```

#### Practical Examples:
```bash
# List rulesets
gh ruleset list

# View specific ruleset
gh ruleset view <ruleset-id>
```

---

### 30. gh attestation - Artifact Attestations

**Purpose:** Work with artifact attestations

#### Practical Examples:
```bash
# Verify an artifact
gh attestation verify artifact.zip
```

---

## Common Workflows

### Workflow 1: Starting Work on an Issue
```bash
# 1. Find an issue
gh issue list --label "good first issue"

# 2. View the issue
gh issue view 42

# 3. Create a branch and start working
git checkout -b fix/issue-42

# 4. Make changes, commit

# 5. Create a PR
gh pr create --title "Fix: Issue #42" --body "Fixes #42"
```

### Workflow 2: Reviewing a PR
```bash
# 1. List PRs needing review
gh pr list --assignee @me

# 2. Checkout the PR
gh pr checkout 123

# 3. View changes
gh pr diff 123

# 4. Test locally

# 5. Review
gh pr review 123 --approve
# or
gh pr review 123 --request-changes --body "Please fix X"
```

### Workflow 3: Quick Repository Setup
```bash
# 1. Create repo
gh repo create my-project --public --clone

# 2. Navigate to it
cd my-project

# 3. Add some code
echo "# My Project" > README.md

# 4. Commit
git add .
git commit -m "Initial commit"
git push -u origin main

# 5. Open in browser
gh browse
```

### Workflow 4: Managing Releases
```bash
# 1. Tag your code
git tag v1.0.0

# 2. Push tag
git push origin v1.0.0

# 3. Create release with built artifacts
gh release create v1.0.0 ./dist/* --notes "Release v1.0.0"
```

### Workflow 5: Working with GitHub Actions
```bash
# 1. List workflows
gh workflow list

# 2. Trigger a workflow
gh workflow run "Deploy" --ref main

# 3. Watch it run
gh run watch

# 4. If it fails, check logs
gh run view --log

# 5. Rerun failed jobs
gh run rerun --failed
```

---

## Pro Tips & Best Practices

### 1. Use Aliases for Common Commands
```bash
gh alias set prc 'pr create --fill'
gh alias set prv 'pr view --web'
gh alias set il 'issue list --assignee @me'
gh alias set mypr 'pr list --author @me'
```

### 2. Chain Commands with Bash
```bash
# Create issue and open in browser
gh issue create --title "New feature" && gh issue view --web

# Create PR and watch checks
gh pr create && gh pr checks --watch
```

### 3. Use JSON Output for Scripting
```bash
# Get PR number as JSON
gh pr view --json number

# List issues as JSON
gh issue list --json number,title,author

# Use jq to process
gh issue list --json number,title | jq '.[] | select(.title | contains("bug"))'
```

### 4. Default Repository Flag
```bash
# Work with any repo without being in its directory
gh issue list --repo owner/repo
gh pr create --repo owner/repo
```

### 5. Interactive Mode
```bash
# Most commands support interactive mode if you omit required args
gh pr create        # Interactive prompts
gh issue create     # Interactive prompts
gh release create   # Interactive prompts
```

---

## Quick Reference Card

### Most Used Commands
```bash
# Authentication
gh auth login

# Repository
gh repo clone owner/repo
gh repo create my-project
gh repo view

# Issues
gh issue create
gh issue list
gh issue view 123

# Pull Requests
gh pr create
gh pr list
gh pr checkout 123
gh pr merge 123

# Actions
gh workflow run "workflow-name"
gh run list
gh run view 123

# Utilities
gh browse
gh status
gh search repos "query"
```

### Global Flags (work with most commands)
```bash
--repo owner/repo    # Specify repository
--json fields        # Output as JSON
--jq expression      # Filter JSON output
--web                # Open in browser
--help               # Show help
```

---

## Learning Path Recommendation

1. **Week 1: Basics**
   - `gh auth login`
   - `gh repo` commands
   - `gh browse`

2. **Week 2: Issues & PRs**
   - `gh issue` commands
   - `gh pr` commands
   - Practice creating and managing issues/PRs

3. **Week 3: GitHub Actions**
   - `gh workflow` commands
   - `gh run` commands
   - Learn to trigger and monitor workflows

4. **Week 4: Advanced**
   - `gh api` for custom requests
   - `gh alias` for productivity
   - `gh extension` for extra features
   - `gh search` for finding resources

---

## Resources

- **Official Manual:** https://cli.github.com/manual/
- **GitHub:** https://github.com/cli/cli
- **Discussions:** https://github.com/cli/cli/discussions
- **Extensions:** https://github.com/topics/gh-extension

---

*Last Updated: February 10, 2026*
