GitHub CLI (gh) Complete Learning Guide

gh --version

gh auth login

gh auth status

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

# 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

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

# 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

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

# 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

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

# 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

# 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

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

# 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>

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

# 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

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

# 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

gh org list            # List organizations

# List organizations you belong to
gh org list

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

# 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

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

# 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"

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

# 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

gh cache list          # List caches
gh cache delete        # Delete a cache

# List all caches
gh cache list
 
# Delete specific cache
gh cache delete <cache-id>
 
# Delete all caches (using key pattern)
gh cache delete --all

gh agent-task create   # Create a new agent task
gh agent-task list     # List agent tasks
gh agent-task view     # View agent task details

gh agent               # Alias for gh agent-task
gh agents              # Alias for gh agent-task
gh agent-tasks         # Alias for gh agent-task

# 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

gh preview prompter    # Interactive prompter (experimental)

# Use the experimental prompter
gh preview prompter
 
# Note: Preview commands are subject to change
# Check the latest documentation for current features

gh alias set           # Create an alias
gh alias list          # List aliases
gh alias delete        # Delete an alias

# 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'

# 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

gh search repos        # Search repositories
gh search issues       # Search issues
gh search prs          # Search pull requests
gh search code         # Search code

# 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

gh secret list         # List secrets
gh secret set          # Create or update a secret
gh secret delete       # Delete a secret

# 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 < private-key.pem
 
# Set org secret
gh secret set SECRET_NAME --org my-org
 
# Delete a secret
gh secret delete SECRET_NAME

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

# 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

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

# 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

gh config get          # Get config value
gh config set          # Set config value
gh config list         # List config values

# 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

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

# 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

gh copilot explain     # Explain a command
gh copilot suggest     # Get command suggestions

# Get suggestion for a task
gh copilot suggest "list all running docker containers"
 
# Explain a command
gh copilot explain "git rebase -i HEAD~3"

# Show your status (assigned issues, PRs, etc.)
gh status
 
# Show status for specific org
gh status --org my-org

gh ssh-key list        # List SSH keys
gh ssh-key add         # Add SSH key
gh ssh-key delete      # Delete SSH key

# 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>

gh gpg-key list        # List GPG keys
gh gpg-key add         # Add GPG key
gh gpg-key delete      # Delete GPG key

# 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>

# 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

gh ruleset list        # List rulesets
gh ruleset view        # View ruleset details

# List rulesets
gh ruleset list
 
# View specific ruleset
gh ruleset view <ruleset-id>

# Verify an artifact
gh attestation verify artifact.zip

# 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"

# 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"

# 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

# 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"

# 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

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'

# 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

# 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"))'

# Work with any repo without being in its directory
gh issue list --repo owner/repo
gh pr create --repo owner/repo

# 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

# 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"

--repo owner/repo    # Specify repository
--json fields        # Output as JSON
--jq expression      # Filter JSON output
--web                # Open in browser
--help               # Show help