Installing GitHub CLI (And Why It's Worth the Inevitable Headache)

Look, we've all been there. You're deep in terminal work, need to create a PR, and suddenly you're clicking through GitHub's web interface like some kind of peasant. GitHub CLI fixes this shit.

GitHub CLI (the gh command) lets you do GitHub stuff without leaving your terminal. It's been around since 2020, has 40.5k GitHub stars, and actually works unlike most CLI tools that promise the moon.

Prerequisites (the boring stuff)

• GitHub account (obviously)
• Terminal access (duh)
• Admin rights to install stuff

What you actually get

• Create PRs from terminal: gh pr create
• Clone repos fast: gh repo clone owner/repo
• Check CI status: gh pr checks
• Create issues: gh issue create
• Browse repos: gh repo view

Installation should take 5 minutes but Windows will definitely find new ways to fuck this up. Authentication is where most people get stuck because OAuth flows are garbage half the time, but we'll get through it.

The official CLI docs are decent but dry as hell. The GitHub CLI repo has better examples if you need to see real usage. Works with GitHub Enterprise too, assuming your IT department isn't running something ancient.

Real talk on timing

• macOS with Homebrew: Actually works in 2 minutes
• Windows with chocolatey: 5-10 minutes if you're lucky
• Ubuntu/Debian: 10-15 minutes because package repositories are a mess
• WSL2: Add another hour for mysterious networking issues

When you get stuck, check these

• GitHub CLI issues for actual examples and known issues
• Stack Overflow github-cli tag for real problems people hit
• GitHub CLI discussions if the error is weird enough
• Authentication troubleshooting guide for token problems
• GitHub Community discussions where people share real installation pain points

GitHub CLI brings your workflow to the terminal

Windows Installation (Prepare for Pain)

Windows Terminal - where your GitHub CLI will live

Method 1: Winget (If You're Lucky)

## First check if Windows actually has winget installed
winget --version

## If that worked, try this:
winget install --id GitHub.cli

If winget gives you grief (and it will), you'll get errors like "Failed to install package" or "Package not found" or my personal favorite, "This app could not be installed" with zero explanation. Just move on to chocolatey.

Method 2: Chocolatey (The Reliable One)

## Install chocolatey if you haven't already (check chocolatey.org)
choco install gh

Chocolatey works better than winget but installs extra crap sometimes. If you see warnings about dependencies, just let it install them. They're probably important.

Method 3: Manual MSI (When All Else Fails)

1. Go to GitHub CLI releases
2. Download the .msi file for Windows
3. Run as administrator (Windows will definitely ask for this)
4. Click through the installer like it's 1999

The MSI route always works but you'll have to update manually. Pain in the ass but at least it's predictable.

macOS Installation (Actually Works)

Method 1: Homebrew (The Right Way)

## If you don't have homebrew yet, get it first
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

## Install GitHub CLI - this actually works reliably
brew install gh

## Check it worked
gh --version

Homebrew on macOS is like apt on Linux - it just works. If you're on Apple Silicon (M1/M2/etc), homebrew handles the architecture automatically. No bullshit.

Method 2: MacPorts (Why Though?)

sudo port install gh

MacPorts exists but nobody uses it anymore. Stick with homebrew unless you enjoy pain.

Linux Installation (Distribution Hell)

Bash - your Linux terminal of choice

Ubuntu/Debian - The Long Way

The official repository method involves adding GPG keys and custom sources - it's complicated as hell and breaks on WSL2 about 60% of the time. Skip the nightmare and just download the .deb file from GitHub releases and install it like a normal person:

## Much easier
wget https://github.com/cli/cli/releases/download/v2.78.0/gh_2.78.0_linux_amd64.deb
sudo dpkg -i gh_2.78.0_linux_amd64.deb

Fedora/RHEL - Actually Simple

sudo dnf install gh

This just works. Fedora/RHEL got their shit together.

Arch Linux - Obviously

sudo pacman -S github-cli

Arch users already know this. If you're using Arch, you probably compiled it from source already.

Verification (Did It Actually Work?)

## Check if it installed
gh --version

You should see something like gh version 2.78.0. If you get "command not found", restart your terminal first (Windows users especially). On Windows 11, you might need to restart the entire terminal app, not just close the tab because Microsoft's PATH updating is broken. Still nothing? The install failed - check PATH or try a different install method.

Authentication (Where Everyone Gets Stuck)

Authentication - the step that breaks everything

Interactive Login (Usually Works)

gh auth login

This opens your browser and does OAuth. It's the path of least resistance:

1. Pick GitHub.com (unless you're corporate)
2. Choose HTTPS (SSH is fine but HTTPS has fewer problems)
3. Let it open your browser and click allow
4. Come back to terminal, should say "Logged in as..."

Token Login (When Browser Auth Fails)
The browser flow fails on headless servers, WSL2 networking weirdness, corporate firewalls, or if your company has ridiculous proxy settings. Make a personal access token instead:

## Set it as environment variable
export GITHUB_TOKEN=ghp_your_token_here

## Or pipe it in
echo "ghp_your_token_here" | gh auth login --with-token

Test It Works

## Check login status
gh auth status

## Try listing your repos - should work without browser
gh repo list

If gh auth status shows you're logged in but commands fail with 404s, your token doesn't have enough permissions. Go back to GitHub settings and give it more scopes.

If things go sideways:

• Check GitHub CLI releases page for direct downloads
• WSL2 users: search the GitHub CLI issues for "wsl" - there's always something broken
• Token problems: make sure your token has `repo` and `user` scopes at minimum