GitHub CLI (gh) - Comprehensive Guide

Introduction

GitHub CLI, commonly known as gh, is an official command-line tool that brings GitHub's features directly to your terminal. It allows developers to interact with repositories, issues, and pull requests without needing to switch to a web browser, significantly streamlining development workflows.

Built and maintained by GitHub, the tool is cross-platform and works seamlessly on Linux, macOS, and Windows.

---

Core Capabilities

With GitHub CLI, you can perform a wide range of tasks directly from the command line:

• Create and manage repositories.
• Handle issues and pull requests.
• Fork and clone repositories.
• View repository details and status.
• Extend functionality through community-built extensions.

---

Installation

Linux (Ubuntu/Debian)

To install GitHub CLI on Ubuntu or Debian-based systems, run:

sudo apt update sudo apt install gh -y  

macOS

On macOS, you can use Homebrew:

brew install gh  

Windows

For Windows users, installation is available via WinGet:

winget install GitHub.cli  

Verifying Installation

To ensure the CLI is installed correctly, check the version:

gh --version  

---

Authentication

Authentication is required to interact with your GitHub account.

Login

Execute the following command to start the authentication process:

gh auth login  

During the process, you will be prompted to choose:

• The account type (GitHub.com or GitHub Enterprise).
• Preferred protocol (HTTPS or SSH).
• Authentication method (Web browser or personal access token).

Authentication Status

To verify your current login status, use:

gh auth status  

Note: HTTPS is recommended for simplicity, while SSH is ideal if you already have SSH keys configured.

---

Repository Management

Create a New Repository

To create a new repository interactively:

gh repo create  

To create a repository non-interactively and push local code:

gh repo create my-repo --public --source=. --remote=origin --push  

Clone a Repository

To clone a repository to your local machine:

gh repo clone username/repository  

Fork a Repository

To fork a repository:

gh repo fork username/repository  

To fork and clone simultaneously:

gh repo fork username/repository --clone  

View Repository Info

To view information about the current repository:

gh repo view  

To open the repository page in your default browser:

gh repo view --web  

---

Issue Management

Create an Issue

To start an interactive issue creation process:

gh issue create  

To create an issue quickly with a title and body:

gh issue create --title "Bug in login" --body "Login fails on invalid token"  

List and View Issues

List open issues:

gh issue list  

Filter issues by state:

gh issue list --state open  

View a specific issue by its number:

gh issue view 12  

Use the --web flag to open the issue in your default browser:

gh issue view 12 --web  

Close an Issue

Once an issue is resolved, close it using its number:

gh issue close 12  

---

Pull Request Management

Create a Pull Request

To create a pull request interactively:

gh pr create  

To create a pull request quickly:

gh pr create --base main --head feature-branch --title "Add login feature" --body "Implemented login logic"  

Manage Pull Requests

List active pull requests:

gh pr list  

View and Checkout Pull Requests

View a specific pull request:

gh pr view 5  

View a pull request with its comments and status checks:

gh pr view 5 --comments  

Checkout a pull request locally for testing:

gh pr checkout 5  

Merge a Pull Request

To merge a pull request:

gh pr merge 5  

You can specify a merge method:

gh pr merge 5 --merge gh pr merge 5 --squash gh pr merge 5 --rebase  

Pull Request Status

To see a summary of pull requests relevant to you:

gh pr status  

---

Extensions

GitHub CLI can be extended with additional commands developed by the community.

Install an Extension

gh extension install owner/extension-name  

List Installed Extensions

gh extension list  

Uninstall an Extension

gh extension remove owner/extension-name  

See available extensions

Visit here: Extensions

Example: Notification Extension

Install Notification Extension

gh extension install meiji163/gh-notify  

Run Notification Extension

gh notify -s  

Uninstall Notification Extension

gh extension remove meiji163/gh-notify  

---

Performance Tips and Best Practices

Useful Commands

• gh status: Provides a quick overview of your work in the current repository.
• gh help: Accesses the built-in documentation for any command.
• -web: Most commands support this flag to transition to the browser when visual detail is needed.

Core Recommendations

• Always ensure you are authenticated before running commands.
• Run commands from within the local git repository to allow gh to automatically detect context.
• Use extensions to automate repetitive tasks specific to your workflow.

Custom Aliases

You can create custom shortcuts for frequently used commands:

gh alias set rl "repo list"  

Now, instead of gh repo list, you can simply run:

gh rl  

---

Limitations

While GitHub CLI is powerful, certain tasks are still better suited for the web interface:

• Large-scale visual code reviews.
• Managing complex organizational settings.
• Users who are entirely new to GitHub and prefer a purely graphical interface.

---

Conclusion

GitHub CLI is an essential tool for developers who prefer staying in the terminal. By mastering these commands, you can significantly reduce context switching and accelerate your development cycle. Try creating your next repository or pull request using gh to see the difference in your workflow.