1. What is gh?
gh is the official GitHub command-line interface. It brings GitHub features such as repositories, pull requests, issues, GitHub Actions, Codespaces, releases, secrets, variables, and API access into your terminal, right next to where you already use git. GitHub describes it nicely: gh lets you work with GitHub from the command line and avoid constantly switching between terminal and browser. (GitHub)
A simple way to remember it:
git # works with Git: commits, branches, remotes, merges
gh # works with GitHub: PRs, issues, Actions, releases, repos, APIs
Example:
git status
git add .
git commit -m "Add login page"
gh pr create
So git handles your source-control work, while gh handles the GitHub workflow around it.
2. Install gh on Windows, macOS, and Linux
Windows installation
The official recommended Windows method is WinGet. GitHub notes that the Windows installer modifies PATH, so after installing, open a new Windows Terminal window, not only a new tab. (GitHub)
winget install --id GitHub.cli --source winget
Upgrade:
winget upgrade --id GitHub.cli --source winget
Community alternatives include Chocolatey, Scoop, Conda, and Webi, but the official recommendation is WinGet. (GitHub)
macOS installation
The official recommended macOS method is Homebrew. (GitHub)
brew install gh
Upgrade:
brew upgrade gh
GitHub also provides precompiled binaries for macOS amd64 and arm64, plus a universal installer. (GitHub)
Linux installation
For Ubuntu, Debian, and Raspberry Pi OS, GitHub recommends the official Debian-style package repository. GitHub’s Linux packages and repository metadata are signed, and the install docs list PGP key fingerprints for verification. (GitHub)
(type -p wget >/dev/null || (sudo apt update && sudo apt install wget -y)) \
&& sudo mkdir -p -m 755 /etc/apt/keyrings \
&& out=$(mktemp) && wget -nv -O$out https://cli.github.com/packages/githubcli-archive-keyring.gpg \
&& cat $out | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \
&& sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
&& sudo mkdir -p -m 755 /etc/apt/sources.list.d \
&& echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
| sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
&& sudo apt update \
&& sudo apt install gh -y
Upgrade:
sudo apt update
sudo apt install gh
For Fedora/RHEL/CentOS-style systems using DNF5:
sudo dnf install dnf5-plugins
sudo dnf config-manager addrepo --from-repofile=https://cli.github.com/packages/rpm/gh-cli.repo
sudo dnf install gh
For DNF4:
sudo dnf install 'dnf-command(config-manager)'
sudo dnf config-manager --add-repo https://cli.github.com/packages/rpm/gh-cli.repo
sudo dnf install gh
For openSUSE/SUSE:
sudo zypper addrepo https://cli.github.com/packages/rpm/gh-cli.repo
sudo zypper ref
sudo zypper install gh
GitHub’s docs also mention Homebrew on Linux, precompiled binaries, and several community-maintained package options. They specifically discourage using Snap for GitHub CLI. (GitHub)
3. Verify installation
After installing, check the version:
gh --version
Then authenticate:
gh auth login
The login flow asks whether you use GitHub.com or another GitHub Enterprise host, then walks you through browser-based authentication. If you choose HTTPS for Git operations, GitHub CLI can also store Git credentials so commands like git push and git pull work without separate credential setup. (GitHub Docs)
Check login status:
gh auth status
4. Basic gh command structure
Most commands follow this pattern:
gh <area> <action> [options]
Examples:
gh repo view
gh repo clone owner/repo
gh issue list
gh pr create
gh workflow list
gh run list
gh release create
To see all top-level commands:
gh
To see subcommands:
gh repo
gh pr
gh issue
To get help:
gh pr create --help
gh repo clone --help
GitHub’s reference says you can use gh without arguments for top-level commands, gh COMMAND for subcommands, and --help for details on any command. (GitHub Docs)
5. Main capabilities of the gh command line
GitHub CLI has a surprisingly wide command surface. The current manual includes core commands for auth, repositories, issues, pull requests, organizations, projects, releases, gists, Codespaces, and GitHub Actions, plus additional commands for API calls, aliases, completions, config, extensions, GPG keys, labels, rulesets, search, secrets, SSH keys, status, and variables. (GitHub CLI)
Repository management
gh repo clone owner/repo
gh repo view owner/repo
gh repo create
gh repo fork owner/repo
Real use case: You join a new project and need to clone the repo quickly.
gh repo clone kubernetes/kubernetes
cd kubernetes
gh repo view --web
Issue management
gh issue list
gh issue view 42
gh issue create
gh issue close 42
Real use case: A tester finds a bug and creates an issue from the terminal.
gh issue create \
--title "Login button disabled after password reset" \
--body "Steps: reset password, log out, try to log in again. Expected: login button active. Actual: button remains disabled." \
--label bug
Pull request workflow
gh pr list
gh pr create
gh pr checkout 123
gh pr view 123
gh pr review 123
gh pr merge 123
Real use case: You finish a feature branch and create a PR without opening GitHub in the browser.
git checkout -b feature/add-profile-page
git add .
git commit -m "Add profile page"
git push -u origin feature/add-profile-page
gh pr create \
--title "Add profile page" \
--body "Adds a user profile page with editable display name and avatar."
GitHub Actions
gh workflow list
gh workflow run ci.yml
gh run list
gh run view
gh run watch
gh run download
Real use case: You push code and want to watch CI from the terminal.
gh run list
gh run watch
The gh run command supports listing, viewing, watching, canceling, deleting, downloading logs/artifacts, and rerunning workflow runs. (GitHub CLI)
Releases
gh release list
gh release view v1.0.0
gh release create v1.0.0
gh release upload v1.0.0 ./dist/app.zip
Real use case: You build a CLI tool and publish a release with binaries.
gh release create v1.0.0 ./dist/myapp-linux.tar.gz ./dist/myapp-macos.zip \
--title "v1.0.0" \
--notes "First stable release."
Secrets and variables
gh secret set DOCKER_TOKEN
gh secret list
gh variable set APP_ENV --body production
gh variable list
Real use case: You need to add a deployment token for GitHub Actions.
gh secret set DOCKERHUB_TOKEN
Then paste the secret value when prompted.
GitHub API access
gh api repos/OWNER/REPO
gh api user
gh api graphql
Real use case: You want to script a GitHub operation that does not have a dedicated high-level gh command.
gh api repos/OWNER/REPO/issues
This is one of the sleeper superpowers of gh: it gives you authenticated API access without manually managing tokens in every script.
Codespaces
gh codespace list
gh codespace create
gh codespace ssh
gh codespace code
Real use case: You are on a lightweight laptop and want to develop inside a cloud dev environment.
gh codespace create
gh codespace code
GitHub’s quickstart shows gh codespace create, gh codespace list, and gh codespace code -w as common Codespaces commands. (GitHub Docs)
Search
gh search repos "language:go stars:>1000"
gh search issues "is:open label:bug"
gh search prs "review-requested:@me state:open"
Real use case: You want to find all open PRs awaiting your review.
gh search prs --review-requested=@me --state=open
GitHub’s quickstart uses this exact pattern for PR review discovery. (GitHub Docs)
Aliases and customization
gh alias set co "pr checkout"
gh alias set prd "pr create --draft"
Then use:
gh co 123
gh prd
GitHub’s docs mention aliases and extensions as ways to customize the CLI for your workflow. (GitHub Docs)
6. End-to-end real-world workflows
Workflow 1: New developer joining a project
Scenario: You are assigned to a repository and need to clone it, inspect it, and check assigned work.
gh auth login
gh repo clone my-org/my-app
cd my-app
gh repo view
gh issue list --assignee "@me"
gh pr list
Why this is useful: onboarding becomes faster. You can see the README, issues, and PRs without bouncing between browser tabs.
Workflow 2: Create a bug report from terminal
Scenario: You are testing an app and discover a bug.
gh issue create \
--title "Checkout fails when coupon code is empty" \
--body "Steps to reproduce:
1. Open checkout page
2. Leave coupon code empty
3. Click Apply
Expected: no error
Actual: checkout form crashes" \
--label bug
Then list bugs:
gh issue list --label bug
Workflow 3: Create a pull request
Scenario: You fixed an issue and want to open a PR.
git checkout -b fix/checkout-empty-coupon
git add .
git commit -m "Fix checkout crash for empty coupon"
git push -u origin fix/checkout-empty-coupon
gh pr create \
--title "Fix checkout crash for empty coupon" \
--body "Fixes validation when coupon field is empty."
Open the PR in browser only when needed:
gh pr view --web
Workflow 4: Review someone else’s PR locally
Scenario: A teammate asks you to review PR #58.
gh pr checkout 58
npm test
gh pr view
gh pr review 58 --comment --body "Tested locally. Left one small suggestion."
Approve:
gh pr review 58 --approve
Merge:
gh pr merge 58 --squash --delete-branch
Tiny quality-of-life upgrade, huge time saver.
Workflow 5: Watch CI/CD after pushing code
Scenario: You pushed a branch and want to see whether GitHub Actions passed.
gh run list
gh run watch
View logs for a failed run:
gh run view --log
Rerun failed jobs:
gh run rerun --failed
This is especially useful in DevOps, platform engineering, and CI/CD-heavy teams.
Workflow 6: Trigger a deployment workflow manually
Scenario: Your repo has a deployment workflow that supports manual runs.
gh workflow list
gh workflow run deploy.yml
gh run watch
With inputs:
gh workflow run deploy.yml \
-f environment=staging \
-f version=v1.2.3
Workflow 7: Publish a release
Scenario: You built version v1.0.0 of your app.
git tag v1.0.0
git push origin v1.0.0
gh release create v1.0.0 \
./dist/app-linux-amd64.tar.gz \
./dist/app-darwin-arm64.zip \
--title "v1.0.0" \
--notes "Initial production release."
View releases:
gh release list
Workflow 8: Use gh inside automation scripts
Scenario: You want to script GitHub tasks.
#!/usr/bin/env bash
set -e
REPO="my-org/my-app"
echo "Open issues:"
gh issue list --repo "$REPO" --state open
echo "Open PRs:"
gh pr list --repo "$REPO" --state open
For structured output, many gh commands support JSON output:
gh pr list --json number,title,author,state
That makes gh handy for shell scripts, dashboards, reports, and automation.
7. Handy commands cheat sheet
| Task | Command |
|---|---|
| Login | gh auth login |
| Check login | gh auth status |
| Clone repo | gh repo clone owner/repo |
| View repo | gh repo view |
| Create repo | gh repo create |
| List issues | gh issue list |
| Create issue | gh issue create |
| List PRs | gh pr list |
| Create PR | gh pr create |
| Checkout PR | gh pr checkout 123 |
| Review PR | gh pr review 123 |
| Merge PR | gh pr merge 123 |
| List workflows | gh workflow list |
| Run workflow | gh workflow run workflow.yml |
| List workflow runs | gh run list |
| Watch workflow run | gh run watch |
| Create release | gh release create v1.0.0 |
| Set secret | gh secret set NAME |
| Set variable | gh variable set NAME --body value |
| Open repo/PR/page in browser | gh browse |
| Call GitHub API | gh api ... |
| Create alias | gh alias set name "command" |
| Install extension | gh extension install owner/gh-extension |
8. Recommended beginner practice lab
Try this safe practice workflow on a test repository.
gh auth login
gh repo create gh-practice-demo --public --clone
cd gh-practice-demo
echo "# GH Practice Demo" > README.md
git add README.md
git commit -m "Add README"
git push origin main
Create an issue:
gh issue create \
--title "Add installation instructions" \
--body "The README should include setup steps."
Create a branch and PR:
git checkout -b docs/install-steps
echo "" >> README.md
echo "## Installation" >> README.md
echo "Run the app setup commands here." >> README.md
git add README.md
git commit -m "Add installation section"
git push -u origin docs/install-steps
gh pr create \
--title "Add installation section" \
--body "Adds basic installation instructions to README."
Merge it:
gh pr merge --squash --delete-branch
Clean up:
git checkout main
git pull
9. Best practices
Use gh auth status when commands fail mysteriously. A lot of “why is GitHub rejecting me?” problems are just expired or missing auth.
Use --help aggressively:
gh pr create --help
gh workflow run --help
gh release create --help
Use aliases for commands you repeat often:
gh alias set mine "issue list --assignee @me"
gh alias set reviews "search prs --review-requested=@me --state=open"
Use gh pr checkout instead of manually finding branches from forks. It is cleaner and less error-prone.
Use gh run watch right after pushing a PR. It keeps your feedback loop tight.
For Linux, prefer GitHub’s official package repositories over stale distro packages when available. GitHub’s own Linux install docs warn that some community Debian/Ubuntu packages had broken older versions due to deprecated GitHub APIs as of November 2025. (GitHub)
10. Final summary
gh is one of those tools that feels small at first, then quietly takes over your workflow. For developers, it speeds up cloning repos, creating issues, opening PRs, reviewing code, and checking CI. For DevOps teams, it helps trigger workflows, inspect GitHub Actions, manage secrets, publish releases, and script GitHub operations. For open-source maintainers, it makes triage and PR review dramatically faster.
Start with these five commands:
gh auth login
gh repo clone owner/repo
gh issue list
gh pr create
gh run watch
Once those feel natural, add releases, secrets, API calls, aliases, and workflow automation. That is where gh turns from “nice CLI tool” into a proper GitHub power tool.
