GitHub CLI - Stop Alt-Tabbing to GitHub Every 5 Minutes

GitHub CLI (gh) is the command-line tool that saves you from constantly switching between your terminal and GitHub's web interface. It's open source, free, and honestly one of the most useful developer tools GitHub has ever shipped.

You're already living in your terminal anyway. You run git commands, execute tests, start dev servers. But the moment you need to create a PR or check why CI failed, you're alt-tabbing to your browser, clicking through GitHub's interface, then context-switching back to code. It's like trying to cook dinner while switching between your kitchen and the neighbor's house every 5 minutes.

What It Actually Does (And What Breaks)

GitHub CLI lets you create pull requests with gh pr create, check CI status with gh pr checks, and merge with gh pr merge - all without leaving terminal. The latest version is 2.78.0 from September 2024, and it's surprisingly solid for a GitHub product.

Pull requests: You can create them fast with `gh pr create`, but reviewing code diffs in the terminal sucks. Use it for quick operations, browser for actual code review. The `gh pr diff` output is harder to read than raw git diff, which is saying something.

Issues: `gh issue create` works great for quick bug reports. Assigning and labeling issues is smooth. The search functionality (`gh issue list`) is decent but GitHub's web search is still better for complex queries.

Actions: `gh run watch` is genuinely useful for watching CI/CD in real-time. Much better than refreshing the browser. But debugging failed workflows? You're back to the web interface because the CLI output is too minimal.

Authentication: The auth flow is decent but you'll probably need to re-auth every few months. `gh auth status` will lie to you sometimes - says you're authenticated but commands still fail with "Error: HTTP 401: Bad credentials (https://api.github.com)". When this happens, just run `gh auth login` again.

Real-World Performance Issues

GitHub CLI is fast for simple operations but has some gotchas:

• Large repos take forever to clone with gh repo clone vs regular git clone (learned this the hard way trying to clone the Linux kernel repo - took 3x longer than standard git)
• gh pr list times out on repos with thousands of PRs (our monorepo breaks it completely after 30 seconds)
• JSON output format changes randomly between versions, so pin your CLI version in Docker images (some update around 2.75 broke all our deployment scripts)
• The pagination on list commands is inconsistent - sometimes 30 items, sometimes 100, sometimes it just gives up and shows 5

Automation Reality Check

Great for CI/CD scripts, but the JSON output format changes randomly between versions, so pin your CLI version in Docker images. Most teams use it for:

• Automated PR creation from release scripts
• CI status checks in deployment pipelines
• Issue creation from monitoring alerts
• Release automation (works well once set up)

Authentication in CI is straightforward with GITHUB_TOKEN, but GitHub Enterprise users get weird permissions issues that'll make you question your career choices. I spent an entire weekend debugging why Enterprise OAuth was rejecting valid tokens - turned out the admin had misconfigured the OAuth app and nobody bothered to document it.

The Truth About Alternatives

GitHub CLI killed the older Hub CLI (which was already half-broken). GitHub Desktop looks nice but falls apart faster than wet cardboard the moment you need anything beyond basic commits. Most serious developers end up using both GitHub CLI and the web interface - CLI for speed, web for detailed work.

It's free, which is weird for GitHub. Works fine with private repos and Enterprise Server, though Enterprise will make you hate your life for 2 days straight while you debug OAuth configurations that work about as well as a chocolate teapot.

Here's what actually breaks:

Installation Reality Check

macOS: `brew install gh` works fine most of the time. ARM Macs (M1/M2) should get the right version automatically, but double-check with `gh --version`. If you downloaded the Intel version by mistake, it'll work but be slower.

Windows: `winget install --id GitHub.cli` is your best bet if you're on Windows 10/11. Chocolatey works too (choco install gh) but sometimes lags behind on versions. The MSI installer is fine but you'll have to manually update it. If you're using WSL2, install the Linux version inside WSL instead of the Windows version - it avoids auth weirdness.

Linux: Package managers work but often have old versions. Ubuntu/Debian users can add GitHub's APT repo for current releases. Otherwise grab the binary and throw it in /usr/local/bin.

Authentication (Where Everything Goes Wrong)

Run gh auth login and prepare for 10 minutes of OAuth hell. The web browser flow usually works, but:

• Browser flow: Opens GitHub, you click authorize, browser shows "success" but CLI throws "Error: authentication failed" anyway. Happens about 20% of the time because OAuth is apparently held together with duct tape and wishful thinking. Just run gh auth login again.
• Personal access token: More reliable but requires creating tokens at github.com/settings/tokens. Make sure you select repo, workflow, and user scopes or you'll get permission errors later.
• SSH keys: Works if you already have SSH set up with GitHub, but pointless since you still need HTTPS auth for the API calls.

Windows WSL2 users: The browser redirect often breaks. Use gh auth login --with-token and paste a PAT instead.

GitHub Enterprise users: Use gh auth login --hostname your-github-enterprise-url and expect additional pain. Your admin probably didn't configure OAuth apps properly.

Commands That Actually Work

Repository stuff: `gh repo clone` is just a wrapper around git clone but shows you fork info. `gh repo create` is genuinely useful for making new repos without clicking through GitHub's UI. `gh repo view` shows README content in your terminal which is... fine.

Pull requests: gh pr create saves time but always double-check the branch and title before submitting. gh pr list shows your PRs quickly. gh pr merge works but web interface is better for reviewing the actual changes first. gh pr checks is clutch for CI status.

Issues: gh issue create is fast for bug reports. gh issue list is good with filters like --assignee @me or --state open. The search isn't as good as GitHub's web search for finding old issues.

Team Adoption (The Hard Way)

Getting a team to use GitHub CLI is like herding cats. Some devs love it, others prefer clicking through the web interface.

What works for teams:

• Use it in CI/CD scripts for creating releases and updating PRs
• Standard workflow scripts that create PRs with proper templates
• Checking build status without opening browsers
• Issue creation from monitoring alerts

What doesn't work:

• Forcing everyone to use it for code review (web interface is better)
• Expecting perfect consistency across different machines (auth breaks randomly)
• Using it for complex GitHub admin tasks (permissions, teams, etc.)

Enterprise gotchas: Enterprise Server is where GitHub CLI goes to die a slow, painful death. Different API endpoints, bizarre rate limits, and auth so fragile it shatters if you breathe on it funny. I once burned 6 hours debugging why gh pr create worked fine on my laptop but threw "Error: Resource not accessible by integration" in CI - turns out our admin had configured the OAuth app while apparently drunk, and nobody documented the weird token requirements.

JSON output is solid for scripting once you figure out the structure, but it changes between versions so pin your CLI version in Docker images.

That's the setup. Next up: where to find help when this inevitably breaks.