Overview
gh is the GitHub command-line tool. It creates and reviews pull requests, opens and comments on issues, manages repositories and releases, and can call any GitHub API endpoint with gh api. It uses your GitHub login (set up with gh auth login), so every call acts as you on GitHub. For plain git work such as commit and push, you still use git.
Background
gh is the official GitHub CLI, with its manual at cli.github.com. The tool tested here is gh 2.103.2. The one example that runs here reports that no login exists, in a clean home folder. The version and help examples are reviewed only, because their text changes with each release, and the ones that call GitHub are reviewed only, because they use your login.
Examples
Print the installed version; reviewed only, because the output changes with each release:
gh --version
Read the help text; reviewed only, because it changes with each release:
gh help
Ask for the login state; with no login in a clean home folder, the status is 1:
gh auth status > /dev/null 2>&1; echo "status $?"
Read the help for gh pr; reviewed only, because it changes with each release:
gh pr --help
List the open pull requests of the current repository; reviewed only because it calls GitHub as you:
gh pr list
Create a pull request from the current branch, with a title; reviewed only:
gh pr create --title "Fix the typo" --body "Details here."
Call an API endpoint and pick one field with --jq; reviewed only:
gh api repos/octocat/Hello-World --jq .full_name
Subcommands
gh auth logs in and shows the login state. gh pr works with pull requests. gh issue works with issues. gh repo works with repositories. gh api calls an API endpoint.
Common mistakes
Everything gh does is done as you: gh pr merge, gh repo delete and gh issue close change the real repository, and some cannot be undone. Check the repository it will use (gh repo view) before a command that changes anything, because it picks the one of the current folder. A login token is stored in your keychain or a config file: do not share it, and prefer a token with only the scopes needed. In a script, set GH_TOKEN to a token with limited rights, not your own login.
Portability
The commands are the same on every system, and new ones arrive with new versions. The third example was executed on gh 2.103.2 in a clean home folder (see the development guide for the exact check); the others are reviewed only.
About upstream gh
This is the upstream GitHub CLI. It is one program everywhere; what differs is the version.
References
Original explanations, with upstream documentation for further reading. FreeBSD references are comparison material, not a claim of Apple version equivalence.