Run GitHub from Your Terminal with the Official gh CLI

// Before you start

What you need

A GitHub account (free is fine)
Mac, Windows, or Linux computer
Internet connection
Admin rights to install software on your machine

Step 1 of 6

Install gh on your operating system

3 min

Pick the command for your OS and run it. This downloads and installs the official gh binary. You only need to do this once. On Mac we use Homebrew (a free package manager). On Windows we use WinGet (built into Windows 10/11). On Ubuntu/Debian Linux we add GitHub's package source first.

Terminal · mac

$ # Mac (requires Homebrew — get it at brew.sh if you don't have it):

$ brew install gh

$ # Windows (WinGet is built into Windows 10/11):

$ winget install --id GitHub.cli

$ # Ubuntu / Debian / Raspberry Pi:

$ (type -p wget >/dev/null || (sudo apt update && sudo apt-get 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 \

$ && 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

What you should see

Installation finishes with no errors. The last line typically says something like 'gh 2.x.x' or 'Successfully installed'.

This might happen

Mac: 'brew: command not found'

Install Homebrew first by visiting brew.sh and pasting the one-liner shown there into your terminal.

Step 2 of 6

Confirm gh is installed

1 min

Ask gh to print its version number. If you see a version, the install worked. If you get 'command not found', the installer did not finish correctly — try closing and reopening your terminal first.

Terminal · mac

$ gh --version

What you should see

gh version 2.x.x (2025-xx-xx)

This might happen

'command not found' after install

Close your terminal completely, reopen it, and run the command again. On Windows you may need to restart the whole session.

Step 3 of 6

Log in to your GitHub account

3 min

gh needs permission to act on your behalf. Running 'gh auth login' starts an interactive wizard. Choose 'GitHub.com', then 'HTTPS', then 'Login with a web browser'. It will give you a one-time code. Paste that code into the browser page that opens, click Authorize, and you're done. Your credentials are saved locally — you won't need to do this again.

Terminal · mac

$ gh auth login

What you should see

The wizard asks a few questions, opens your browser, and ends with: '✓ Logged in as YOUR_USERNAME'

This might happen

Browser doesn't open automatically

Copy the URL printed in the terminal and paste it manually into any browser. Enter the one-time code shown in the terminal.

Step 4 of 6

Try a real command — list your repos

1 min

This command asks GitHub to list all repositories you own. It's a quick smoke-test that proves your login works and gh can talk to the API.

Terminal · mac

$ gh repo list

What you should see

A table of your repositories with names, visibility (public/private), and last-updated dates.

This might happen

Output is empty

You may not have any repos yet. Create one at github.com/new, then run the command again.

Step 5 of 6

Create a GitHub issue from the terminal

2 min

Navigate into any local git folder that is connected to a GitHub repo, then run this command. gh opens an interactive prompt for title and body. Fill them in, press Enter, and the issue appears on GitHub instantly — no browser needed.

Terminal · mac

$ cd /path/to/your/local/repo

$ gh issue create

What you should see

gh asks for a title and body, then prints: 'https://github.com/YOUR_USERNAME/REPO/issues/1'

This might happen

'not a git repository' error

You must be inside a folder that was cloned from GitHub. Run 'gh repo clone YOUR_USERNAME/REPO_NAME' first to get one.

Step 6 of 6

Explore what else gh can do

2 min

gh covers pull requests, releases, Actions workflows, gists, SSH keys, and more. The built-in help lists every command. Nothing to install — it's all already there.

Terminal · mac

$ gh help

What you should see

A categorized list of all available commands: repo, issue, pr, release, workflow, gist, auth, and more.

// Status

cooked. baked. worked.

gh is installed, you are logged in, and you can create issues, list repos, and manage pull requests entirely from your terminal without opening a browser.

// the honest bit

The honest part

gh is a power tool for people who already use git and GitHub. If you have never used git before, gh will feel confusing because most commands require you to be inside a git repository. It does not replace learning git — it just saves you from switching to the browser for GitHub-specific tasks like issues and pull requests. Enterprise Server users need version 2.20 or newer on their server.