GitHub CLI Setup Guide

Prerequisite 3 of 3. You have a GitHub account and Git installed. This guide installs the GitHub CLI and logs it in, so your computer — and the AI tools on it — can reach GitHub as you.

What Is the GitHub CLI?

The GitHub CLI (gh) is a small program that lets your computer talk to GitHub. You sign in through it once, and from then on Git and the AI code editors and coding agents on your machine can send your files to GitHub and fetch them back (Git calls this push and pull) without asking for a password every time. CLI means “command line interface” — you use it by typing commands in a terminal rather than clicking in a browser.

The official home of the GitHub CLI is cli.github.com.

On a company laptop?

You may need admin rights or IT approval to run an installer. Ask IT before you start. If commands work at home but fail at work, see Corporate Networks in the Git guide.

Step 1: Install the GitHub CLI

Follow the section for your computer, then continue to Step 2.

macOS

1. Open the GitHub CLI releases page.
2. Scroll down to Assets. If you only see a few files, click Show all assets.
3. Press Cmd + F, type universal.pkg, and click the file it highlights — it’s named like gh_2.101.0_macOS_universal.pkg (the number changes with each release). It downloads.
4. Open your Downloads folder and double-click the file. Click Continue → Install, enter your Mac password when asked, then Close.
5. If Terminal is already open, quit it (Cmd + Q) — you’ll open a fresh one in Step 2.

Why not cli.github.com? It’s the official home of the GitHub CLI, but its Mac download is a bare program file, not an installer — it won’t work with a double-click. Its Windows download is fine.

Already have Homebrew? brew install gh does the same thing. Don’t install Homebrew just for this.

Windows

1. Go to cli.github.com.
2. Click the dropdown button next to the green Copy button (on Windows it reads Install with WinGet) and choose Windows — Download MSI. The installer downloads.
3. Open your Downloads folder and double-click the file. Click Next, then Install — approve the Windows security prompt if one appears — then Finish.
4. If PowerShell is already open, close it — you’ll open a fresh one in Step 2.

Prefer a command? In PowerShell, run winget install --id GitHub.cli. The first time you use winget it asks Do you agree to all the source agreements terms? — type Y and press Enter. If PowerShell says winget is not recognized, use the MSI above instead.

Step 2: Open Your Terminal

Every remaining command is typed into a terminal — a window where you type instructions instead of clicking them. Open a new window now, even if you had one open before: a terminal only notices newly installed programs when it starts.

1. macOS: press Cmd + Space, type Terminal, press Enter.
2. Windows: press Start, type PowerShell, press Enter.

Never used a terminal before? The Terminal Basics primer is about 15 minutes and covers everything this guide assumes.

Step 3: Log In

Run:

gh auth login

Before it opens your browser, gh asks four questions in the terminal. Use the arrow keys to choose (or type the answer) and press Enter:

Question	Choose
Where do you use GitHub?	GitHub.com
What is your preferred protocol for Git operations on this host?	HTTPS
Authenticate Git with your GitHub credentials?	Yes — type Y, or just press Enter
How would you like to authenticate GitHub CLI?	Login with a web browser

The exact wording shifts slightly between gh versions, but the questions come in this order and these are the answers to give. Answering Yes to the third question is what lets Git push and pull without ever asking you for a password.

Then, in order:

1. The terminal says First copy your one-time code: followed by a code like A1B2-C3D4, then Press Enter to open github.com in your browser… — note the code, then press Enter.
2. Your browser opens a GitHub page asking for the code. Type it in and click Continue.
3. GitHub shows Authorize GitHub CLI. Click it. It may ask for your password or a two-factor code first — that’s normal.
4. The browser shows Congratulations, you’re all set! You can close that tab.
5. Back in the terminal, the last line reads ✓ Logged in as your-username.

Done When

Prerequisite	Done when
3. GitHub CLI installed and logged in	gh --version prints a version number, and gh auth status prints ✓ Logged in to github.com account <your-username>

Run both now:

gh --version
gh auth status

The output looks like this (your version number and username will differ):

gh version 2.101.0 (2026-09-15)
github.com
  ✓ Logged in to github.com account your-username (keyring)
  - Active account: true
  - Git operations protocol: https

If you see both, all three prerequisites are done. Next: Create and clone your first repository — the end-to-end proof that your account, Git, and the CLI all work together.

---

Troubleshooting

gh is not recognized / command not found after installing?

• Close and reopen your terminal, then run gh --version again — a terminal only picks up newly installed programs when it starts

Downloaded a .zip from cli.github.com on a Mac?

• Delete it. That file is a bare program, not an installer. Follow the macOS steps in Step 1 to get the .pkg from the releases page instead

gh auth login fails or hangs?

• Make sure you have a browser available to complete the flow
• Try gh auth login --web to force the browser-based flow
• Check gh auth status afterward to confirm

gh auth status says “You are not logged into any GitHub hosts”?

• The browser step didn’t finish. Run gh auth login again and make sure you reach the Congratulations, you’re all set! page before returning to the terminal

Ask AI for help

If you’re stuck, paste this into ChatGPT, Claude, or Gemini:

I’m installing the GitHub CLI (gh) on [Mac / Windows] and logging in with gh auth login, and I’m getting this error: [paste the error message]. What should I try?

Resources

• GitHub CLI — official home and downloads
• GitHub CLI manual