github_cli_guide.md

GitHub CLI (gh) User Guide

Table of Contents

• Introduction
• Installation
• Authentication
• Repository Management
• Pull Requests
• Issues
• GitHub Actions
• Gists
• Advanced Features
• Tips and Tricks

Introduction

GitHub CLI (gh) is a command-line tool that brings GitHub functionality to your terminal. It allows you to work with GitHub features like repositories, issues, and pull requests directly from your command line.

Installation

macOS

brew install gh

Windows

winget install --id GitHub.cli
# or with Chocolatey
choco install gh

Linux

# Debian/Ubuntu
sudo apt install gh

# Fedora
sudo dnf install gh

Authentication

Before using GitHub CLI, you need to authenticate with your GitHub account.

# Start the authentication process
gh auth login

# Check authentication status
gh auth status

# Log out
gh auth logout

During authentication, you'll be asked:

1. Which GitHub host to use (github.com or enterprise)
2. Authentication protocol (HTTPS or SSH)
3. Authentication method (web browser, token, or SSH key)

Repository Management

Creating Repositories

# Create a new repository (interactive)
gh repo create

# Create a new public repository with a specific name
gh repo create my-project --public

# Create a repository from an existing local directory
gh repo create my-project --source=. --private

Cloning Repositories

# Clone your own repository
gh repo clone my-project

# Clone someone else's repository
gh repo clone username/repo-name

# Clone with specific branch
gh repo clone username/repo-name -- -b branch-name

Repository Information

# View repository details
gh repo view

# View repository details of a specific repo
gh repo view username/repo-name

# Open repository in browser
gh repo view --web

# List your repositories
gh repo list

# List repositories of an organization
gh repo list organization-name

Repository Actions

# Fork a repository
gh repo fork username/repo-name

# Archive a repository
gh repo archive username/repo-name

# Delete a repository (requires confirmation)
gh repo delete username/repo-name

Pull Requests

Creating Pull Requests

# Create a pull request (interactive)
gh pr create

# Create a pull request with title and body
gh pr create --title "Fix bug" --body "This PR fixes a critical bug"

# Create a draft pull request
gh pr create --draft

# Create a pull request targeting a specific branch
gh pr create --base develop

Managing Pull Requests

# List pull requests
gh pr list

# View a specific pull request
gh pr view 123

# Check out a pull request locally
gh pr checkout 123

# Approve a pull request
gh pr review 123 --approve

# Request changes on a pull request
gh pr review 123 --comment -b "Please fix these issues"

# Merge a pull request
gh pr merge 123

# Close a pull request without merging
gh pr close 123

Pull Request Status

# Check PR status
gh pr status

# View CI status for a pull request
gh pr checks 123

Issues

Creating Issues

# Create an issue (interactive)
gh issue create

# Create an issue with title and body
gh issue create --title "Bug report" --body "Description of the bug"

# Create an issue with labels and assignees
gh issue create --label bug,urgent --assignee username1,username2

Managing Issues

# List issues
gh issue list

# List closed issues
gh issue list --state closed

# View a specific issue
gh issue view 456

# Close an issue
gh issue close 456

# Reopen an issue
gh issue reopen 456

# Assign an issue
gh issue edit 456 --add-assignee username

Issue Status

# Check issue status
gh issue status

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

GitHub Actions

# List workflows
gh workflow list

# View a specific workflow
gh workflow view workflow-name.yml

# Run a workflow
gh workflow run workflow-name.yml

# View workflow runs
gh run list

# View a specific run
gh run view run-id

# Download artifacts from a run
gh run download run-id

Gists

# Create a gist from a file
gh gist create file.txt

# Create a private gist
gh gist create file.txt --private

# List your gists
gh gist list

# View a specific gist
gh gist view gist-id

# Edit a gist
gh gist edit gist-id

Advanced Features

GitHub CLI Extensions

GitHub CLI supports extensions that add new functionality:

# List available extensions
gh extension list

# Install an extension
gh extension install owner/name

# Update extensions
gh extension upgrade

# Create your own extension
gh extension create extension-name

Aliases

Create custom shortcuts for common commands:

# Create an alias
gh alias set prc 'pr create --title "$1" --body "$2"'

# Use the alias
gh prc "Fix bug" "This fixes a critical bug"

# List aliases
gh alias list

# Delete an alias
gh alias delete prc

Environment Variables

GitHub CLI uses several environment variables:

• GH_TOKEN: Authentication token
• GH_HOST: GitHub hostname
• GH_REPO: Default repository
• GH_EDITOR: Editor for authoring content

API Access

Use the API command to make direct requests:

# GET request
gh api repos/owner/repo

# POST request with data
gh api repos/owner/repo/issues -F title="Bug" -F body="Description"

# PUT request
gh api repos/owner/repo/topics -F topics[]="topic1" -F topics[]="topic2"

Tips and Tricks

Output Formatting

Control output format for data:

# JSON output
gh issue list --json number,title,assignees

# Template-based output
gh issue list --json number,title --template '{{range .}}#{{.number}} {{.title}}{{end}}'

Configuration

Manage configuration:

# Set a configuration value
gh config set editor vim

# Get a configuration value
gh config get editor

# List configuration
gh config list

Searching

Search GitHub resources:

# Search repositories
gh search repos "machine learning"

# Search issues
gh search issues "bug in login"

# Search pull requests
gh search prs "fix documentation"

Copilot in CLI

If you have GitHub Copilot, use it in the CLI:

# Ask Copilot a question
gh copilot suggest "How do I create a new branch?"

# Get command explanations
gh copilot explain "git rebase -i HEAD~3"

---

For more information, visit the GitHub CLI documentation or run gh help for command-specific help.