Skip to content

appendix ac github cli

Jump to bottom
github-actions[bot] edited this page Mar 8, 2026 · 1 revision

Appendix AC: GitHub CLI Reference

Episode coming soon: GitHub CLI Reference - a conversational audio overview of this appendix. Listen before reading to preview the concepts, or after to reinforce what you learned.

Your Terminal, Supercharged for GitHub

Who this is for: You want to manage GitHub — issues, pull requests, repos, releases — from your terminal without opening a browser. The GitHub CLI (gh) gives you full access to GitHub from the command line, with clean plain-text output that works beautifully with screen readers.

gh handles the GitHub side of things (issues, PRs, repos, releases). git handles the local version control side (commits, branches, history). You use both together.

Table of Contents

  1. Installing and Authenticating
  2. Repos — Clone, Fork, Create, View
  3. Issues — Create, List, View, Comment, Close
  4. Pull Requests — Create, Review, Merge, Check
  5. Releases — Create, List, Upload
  6. Search — Issues, PRs, Repos, Code
  7. Labels and Milestones
  8. Output Formatting — JSON, jq, Templates
  9. Aliases — Create Your Own Shortcuts
  10. Extensions — Adding New Commands
  11. Copilot in the CLI
  12. Screen Reader Tips
  13. Quick Reference Card

1. Installing and Authenticating

Installing

Windows

winget install GitHub.cli

Or download the installer from cli.github.com.

macOS

brew install gh

Linux (Debian/Ubuntu)

(type -p wget >/dev/null || (sudo apt update && sudo apt-get install wget -y)) \
&& sudo mkdir -p -m 755 /etc/apt/keyrings \
&& wget -qO- https://cli.github.com/packages/githubcli-archive-keyring.gpg | 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

Verify installation

gh --version

Authenticating

gh auth login

Follow the prompts:

  • Where do you use GitHub? → GitHub.com (or Enterprise)
  • Preferred protocol? → HTTPS (or SSH)
  • Authenticate with browser? → Yes — your browser opens for OAuth sign-in

After signing in, return to the terminal. You're done.

# Check your auth status at any time
gh auth status

# Log out
gh auth logout

# Refresh credentials / add new scopes
gh auth refresh

Screen reader tip: gh auth login is an interactive prompt — navigate with Arrow keys, confirm with Enter. All prompts are plain text and read naturally. The browser step opens automatically; switch back to the terminal when the browser confirms success.

2. Repos — Clone, Fork, Create, View

# Clone a repository (automatically sets up the remote)
gh repo clone owner/repo-name

# Fork a repo and clone your fork in one step
gh repo fork owner/repo-name --clone

# Fork without cloning (creates the fork on GitHub only)
gh repo fork owner/repo-name

# Create a brand new repository
gh repo create my-new-project
gh repo create my-new-project --public --description "My project description"
gh repo create my-new-project --private

# View a repository's details
gh repo view
gh repo view owner/repo-name

# Open the repo in your browser
gh repo view --web

# List your repositories
gh repo list
gh repo list --limit 50

# List repos for an org
gh repo list my-org --limit 100

# Archive a repository
gh repo archive owner/repo-name

# Delete a repository (careful!)
gh repo delete owner/repo-name --confirm

# Sync your fork with upstream
gh repo sync
gh repo sync --branch main

3. Issues — Create, List, View, Comment, Close

Creating issues

# Create an issue interactively (opens a prompt for title, body, labels, etc.)
gh issue create

# Create with all details inline
gh issue create \
  --title "Screen reader can't navigate the settings menu" \
  --body "When using NVDA with Firefox, the Settings menu items are not announced..." \
  --label "bug,accessibility" \
  --assignee "@me"

# Create from a Markdown file (great for detailed bug reports)
gh issue create --title "Accessibility audit findings" --body-file ./report.md

Listing and filtering issues

# List open issues (current repo)
gh issue list

# List issues with filters
gh issue list --label "accessibility"
gh issue list --label "good first issue"
gh issue list --assignee "@me"
gh issue list --state closed
gh issue list --limit 50

# Search issues by keyword
gh issue list --search "screen reader"

# List issues across all repos you watch
gh issue list --repo owner/repo-name

Viewing issues

# View an issue (renders Markdown as plain text in the terminal)
gh issue view 42

# Open the issue in your browser
gh issue view 42 --web

# View comments on an issue
gh issue view 42 --comments

Screen reader tip: gh issue view 42 outputs clean plain text — title, metadata, and body all formatted without noise. Read line by line with Arrow keys. Much faster than navigating a browser page with a screen reader.

Commenting and updating

# Add a comment to an issue
gh issue comment 42 --body "I can reproduce this on Windows 11 with NVDA 2024.1."

# Comment from a file
gh issue comment 42 --body-file ./my-comment.md

# Edit an issue (title, body, labels, assignees)
gh issue edit 42 --title "Updated title"
gh issue edit 42 --add-label "needs-reproduction"
gh issue edit 42 --remove-label "bug"
gh issue edit 42 --add-assignee username

# Close an issue
gh issue close 42
gh issue close 42 --comment "Fixed in PR #56."
gh issue close 42 --reason "not planned"

# Reopen a closed issue
gh issue reopen 42

Pinning and locking

# Pin an issue (shows at top of the Issues tab)
gh issue pin 42

# Lock an issue (prevents new comments)
gh issue lock 42 --reason "resolved"

4. Pull Requests — Create, Review, Merge, Check

Creating a PR

# Create a PR interactively (prompts for title, body, base branch, etc.)
gh pr create

# Create with all details inline
gh pr create \
  --title "Add keyboard navigation to settings menu" \
  --body "Closes #42. Adds Tab/arrow key support to the settings dropdown." \
  --base main \
  --label "accessibility,enhancement"

# Create as a draft
gh pr create --draft

# Create from a file
gh pr create --title "Accessibility improvements" --body-file ./pr-description.md

# Open the PR creation form in your browser
gh pr create --web

Listing and viewing PRs

# List open PRs
gh pr list

# List with filters
gh pr list --state closed
gh pr list --author "@me"
gh pr list --label "accessibility"
gh pr list --search "screen reader"

# View a PR (title, description, status, checks)
gh pr view 56

# View the diff of a PR
gh pr diff 56

# Open the PR in your browser
gh pr view 56 --web

# Check out a PR branch locally (to test it)
gh pr checkout 56

Reviewing PRs

# Approve a PR
gh pr review 56 --approve
gh pr review 56 --approve --body "Tested with NVDA — keyboard nav works perfectly. LGTM!"

# Request changes
gh pr review 56 --request-changes --body "The focus indicator disappears on the last menu item."

# Leave a comment review (no approval/rejection)
gh pr review 56 --comment --body "A few observations — see inline comments."

Checking CI status

# View all CI checks for a PR
gh pr checks 56

# Watch checks update in real time (refreshes every 10s)
gh pr checks 56 --watch

# View checks for the current branch
gh pr checks

Merging PRs

# Merge a PR (interactive — prompts for merge strategy)
gh pr merge 56

# Merge with a specific strategy
gh pr merge 56 --merge          # Creates a merge commit
gh pr merge 56 --squash         # Squashes all commits into one
gh pr merge 56 --rebase         # Rebases commits onto base branch

# Auto-merge when checks pass (great for PRs waiting on CI)
gh pr merge 56 --auto --squash

# Delete the branch after merging
gh pr merge 56 --squash --delete-branch

Other PR operations

# Convert a draft PR to ready for review
gh pr ready 56

# Mark a ready PR back as draft
gh pr ready 56 --undo

# Update your PR branch with the latest from base (equivalent to "Update branch" button)
gh pr update-branch 56
gh pr update-branch 56 --rebase

# Close a PR without merging
gh pr close 56
gh pr close 56 --comment "Superseded by #58."

# Reopen a closed PR
gh pr reopen 56

# Add a comment to a PR
gh pr comment 56 --body "Thanks for the thorough review! Addressing feedback now."

5. Releases — Create, List, Upload

# Create a release interactively
gh release create v1.2.0

# Create with all details
gh release create v1.2.0 \
  --title "Version 1.2.0 — Accessibility Improvements" \
  --notes "- Fixed keyboard navigation in settings\n- Added ARIA labels to all form inputs"

# Create from a notes file
gh release create v1.2.0 --notes-file ./CHANGELOG.md

# Create a pre-release
gh release create v1.2.0-beta.1 --prerelease

# Create a draft release (not published yet)
gh release create v1.2.0 --draft

# Upload files to a release
gh release upload v1.2.0 ./dist/app.zip ./dist/app.tar.gz

# List releases
gh release list

# View a release
gh release view v1.2.0

# Download release assets
gh release download v1.2.0
gh release download v1.2.0 --pattern "*.zip"

# Delete a release
gh release delete v1.2.0

See also: Appendix H: Releases, Tags, and Insights for the GitHub.com interface side of releases.

6. Search — Issues, PRs, Repos, Code

# Search issues across all of GitHub
gh search issues "screen reader navigation" --label accessibility
gh search issues "keyboard shortcut" --repo owner/repo-name
gh search issues "help wanted" --language javascript --limit 20

# Search pull requests
gh search prs "accessibility fix" --state open
gh search prs "WCAG" --author username

# Search repositories
gh search repos "accessible markdown editor" --language python --stars ">100"
gh search repos "screen reader" --topic accessibility

# Search code
gh search code "aria-label" --repo owner/repo-name
gh search code "git cherry-pick" --language markdown

7. Labels and Milestones

Labels

# List labels in the current repo
gh label list

# Create a label
gh label create "accessibility" --color "0075ca" --description "Accessibility improvements"

# Clone labels from another repo (copies all their labels to yours)
gh label clone owner/source-repo

# Delete a label
gh label delete "wontfix"

Milestones

# List milestones
gh api repos/{owner}/{repo}/milestones --jq '.[].title'

# Create a milestone
gh api repos/{owner}/{repo}/milestones \
  --method POST \
  --field title="v2.0 Launch" \
  --field description="All features for the v2.0 release" \
  --field due_on="2026-06-01T00:00:00Z"

8. Output Formatting — JSON, jq, Templates

By default gh outputs human-readable text. For scripting or custom display, you can get raw JSON and filter it.

--json flag

# Get issue data as JSON
gh issue view 42 --json title,body,labels,state

# Get PR data as JSON
gh pr view 56 --json title,number,state,mergeable,reviews

# List issues as JSON
gh issue list --json number,title,labels,assignees

--jq flag (filter JSON inline)

# List just issue numbers and titles
gh issue list --json number,title --jq '.[] | "\(.number): \(.title)"'

# Get the names of all labels on an issue
gh issue view 42 --json labels --jq '.labels[].name'

# Count open PRs
gh pr list --json number --jq 'length'

# List reviewers who approved a PR
gh pr view 56 --json reviews --jq '[.reviews[] | select(.state=="APPROVED") | .author.login] | unique'

--template flag (Go templates)

# Custom formatted output
gh issue list --template '{{range .}}#{{.number}} {{.title}} ({{.state}}){{"\n"}}{{end}}'

Screen reader tip: --json with --jq produces clean, predictable output — ideal for piping to a file or reading with a screen reader. The default human-readable output is also clean, but JSON gives you precise control over what's announced.

9. Aliases — Create Your Own Shortcuts

Aliases let you create custom gh commands from long commands you run often.

# Create an alias
gh alias set bugs 'issue list --label bug'
gh alias set my-prs 'pr list --author @me'
gh alias set review-ready 'pr list --label "ready for review"'

# Use your alias
gh bugs
gh my-prs
gh review-ready

# List all aliases
gh alias list

# Delete an alias
gh alias delete bugs

# Create a shell alias (runs a shell command, not just gh commands)
gh alias set --shell open-pr 'gh pr view $1 --web'
gh open-pr 56   # opens PR #56 in the browser

Useful aliases to set up

# Issues assigned to you
gh alias set mine 'issue list --assignee @me'

# Your open PRs
gh alias set mypr 'pr list --author @me --state open'

# Check CI on current branch's PR
gh alias set ci 'pr checks'

# View current PR
gh alias set pr 'pr view'

10. Extensions — Adding New Commands

Extensions add new gh subcommands written by the community.

# Browse available extensions
gh extension search

# Install an extension
gh extension install owner/gh-extension-name

# List installed extensions
gh extension list

# Update all extensions
gh extension upgrade --all

# Update a specific extension
gh extension upgrade owner/gh-extension-name

# Remove an extension
gh extension remove owner/gh-extension-name

Useful extensions

Extension What it does Install
github/gh-copilot Ask Copilot questions in the terminal gh extension install github/gh-copilot
nicokosi/gh-notify Desktop notifications for GitHub events gh extension install nicokosi/gh-notify
mislav/gh-branch Better branch switching with fuzzy search gh extension install mislav/gh-branch

11. Copilot in the CLI

Install the Copilot extension once, then ask coding and git questions without leaving the terminal.

# Install (one time)
gh extension install github/gh-copilot

# Ask for a command suggestion
gh copilot suggest "squash my last 4 commits into one"
gh copilot suggest "find which commit introduced a bug in auth.js"
gh copilot suggest "create a pull request from my current branch"

# Explain a command you don't recognize
gh copilot explain "git rebase -i HEAD~3"
gh copilot explain "git bisect start"
gh copilot explain "find . -name '*.md' -mtime -7"

Copilot CLI shows the suggested command, explains what it does, and asks whether to run it — perfect for learning while doing.

See also: Appendix AA: Advanced Git Operations, Section 11 for more Copilot CLI examples with git operations.

12. Screen Reader Tips

The GitHub CLI is one of the most screen-reader-friendly ways to use GitHub. Here's why and how to get the most out of it.

Why the CLI works so well

  • Plain text output — no visual noise, no unlabelled buttons, no hidden dialogs
  • Predictable structure — every command produces consistent output you can navigate with arrow keys
  • No focus traps — you control when you read output; nothing streams unexpectedly
  • Keyboard-first by design — everything is a command you type

Tips by task

Reading issues and PRs:

# Pipe output to less for page-by-page reading
gh issue view 42 | less

# Save to a file and open in your editor
gh pr view 56 > pr-56.md
code pr-56.md

Navigating long lists:

# Limit results to a manageable number
gh issue list --limit 10

# Combine with search to narrow down
gh issue list --search "keyboard" --limit 5

Getting just what you need:

# Get just the PR title
gh pr view 56 --json title --jq '.title'

# Get just the issue body
gh issue view 42 --json body --jq '.body'

# Get CI check status as a simple list
gh pr checks 56 --json name,state --jq '.[] | "\(.state): \(.name)"'

Creating content without a browser:

# Write your issue body in a text file first (easier with a screen reader)
# Then create the issue from the file
gh issue create --title "Bug: focus lost after modal closes" --body-file ./issue.md

NVDA / JAWS (Windows)

  • Run gh commands in Windows Terminal or the VS Code integrated terminal — both work well with NVDA/JAWS
  • Use Insert+Down (NVDA) or Insert+F12 (JAWS) to read the current line of terminal output
  • For long output, use | less and navigate with Space (next page) and b (back)

VoiceOver (macOS)

  • Run gh in Terminal.app or VS Code integrated terminal
  • VO+Right moves through terminal output character by character; VO+Down line by line
  • Use Ctrl+C to stop a running command if output is too long

13. Quick Reference Card

Authentication

Command What it does
gh auth login Sign in to GitHub
gh auth status Check login status
gh auth logout Sign out

Repos

Command What it does
gh repo clone owner/repo Clone a repo
gh repo fork owner/repo --clone Fork and clone
gh repo create name --public Create a new repo
gh repo view View current repo info
gh repo sync Sync fork with upstream

Issues

Command What it does
gh issue list List open issues
gh issue view 42 Read issue #42
gh issue create Create a new issue
gh issue comment 42 --body "..." Add a comment
gh issue close 42 Close an issue

Pull Requests

Command What it does
gh pr list List open PRs
gh pr view 56 Read PR #56
gh pr create Create a PR
gh pr diff 56 See the diff
gh pr checks 56 See CI status
gh pr review 56 --approve Approve
gh pr merge 56 --squash Merge (squash)
gh pr checkout 56 Check out locally
gh pr update-branch Update from base

Releases

Command What it does
gh release create v1.0.0 Create a release
gh release list List releases
gh release download v1.0.0 Download assets

Copilot

Command What it does
gh copilot suggest "..." Get a command suggestion
gh copilot explain "..." Explain a command

Related appendices: Appendix AA: Advanced Git Operations · Appendix AB: GitHub Desktop · Appendix D: Git Authentication · Appendix W: Copilot Reference

Clone this wiki locally