CLI · Code collaboration · GitHub
GitHub CLI
Review pull requests, inspect checks and manage repository work from the same terminal as your code.
Credential storage fallback. If a secure credential store is unavailable, gh can save its token in a plain-text file. Check the authentication setup before using a shared machine.
Understand the tool
What it does.
GitHub CLI is the gh program: a typed interface to GitHub issues, pull requests, releases and automation runs. Git tracks files and commits; gh handles the collaboration around those files. You can request a readable list or structured JSON for another script.
Why use it?
Start here when the repeated task is checking repository work. One explicit repository and a few filters can produce a review queue without opening several browser tabs. It is especially useful when the next step already happens in a terminal.
A useful fit for
- Pull-request review queues
- Release and workflow inspection
- Small scripts that read GitHub metadata
From need to output
Ways to put it to work.
These are suggested workflows based on the documented capabilities. They are not recorded runtime results.
Use case 01
Prepare a review queue
A maintainer needs the open proposals before a weekly code review.
- Select the owner and repository explicitly.
- List open pull requests and return their numbers, titles and URLs.
- Inspect each change and its checks before deciding who should review it.
Intended outputA bounded list of work with direct links, ready for review.
Use case 02
Investigate a failed workflow
A build failed after a change and the team needs the relevant evidence.
- Locate the workflow run for the affected commit.
- Read the failed job and its logs.
- Record the failure and commit together before proposing a fix.
Intended outputA failure report tied to a specific run rather than a vague build status.
A concrete starting point
List five open pull requests
Replace OWNER/REPO with a repository you can access. The result is JSON containing five or fewer open proposals.
gh pr list --repo OWNER/REPO --state open --limit 5 --json number,title,urlWhat this can change
Makes authenticated GitHub API reads and prints repository metadata. It does not edit, comment on or merge a pull request.
This example has not been executed for this review. Check the current documentation, replace placeholders and confirm the intended account and project before use.
Before you start
Setup and access.
What you’ll need
- Installed gh and a terminal
- GitHub account and permission for the target repository
- Git for workflows that check out or change local branches
- Authentication
- Browser sign-in or a suitably scoped token; organization policies can impose additional authorization.
- Can read
- Repository metadata
- Issues, pull requests and workflow logs within account permissions
- Can write or change
- Comments, merges, releases and settings when the chosen command and account allow them
- Network and data flow
- GitHub.com or the configured GitHub Enterprise host
- Approval and control
- The CLI follows account permissions. Do not assume every write command asks for an additional confirmation.
Check your environment
Compatibility, costs and license.
Compatibility notes
- Windows, macOS and Linux
- GitHub.com, Enterprise Cloud and supported Enterprise Server versions
Costs and account requirements
The CLI is open source. GitHub subscriptions, Actions usage and other hosted services have separate limits and charges.
Current pricing or plan information ↗MIT
Applies to the CLI source. GitHub service terms remain separate.
Read the license or service terms ↗Keep the boundaries visible
Concerns and limitations.
Credential storage fallback
If a secure credential store is unavailable, gh can save its token in a plain-text file. Check the authentication setup before using a shared machine.
A convenient write is still a write
Merge and release commands affect shared work. Verify repository, branch and command arguments before automation runs them.
Where it may fall short
- This is GitHub tooling, not a cross-forge interface.
- Extensions add executable code and need their own review.
Observed behavior · 2026-10-18
Runtime and security findings.
Local alias configuration and execution worked with an empty GitHub configuration. The authentication check reported no signed-in hosts; repository and permission workflows were not exercised.
These checks cover the conditions below. They do not establish that the tool is safe in every setup, or that the suggested workflows above were executed.
What we found
Observed in this evaluation
Configuration works without a GitHub session
An alias could be stored and executed while auth status returned exit 1 with no logged-in hosts. This establishes local command/configuration behavior, not API access or token isolation.
In practice: Run gh auth status before account work and make repository/host targets explicit.
Documented concern · medium severity under stated conditions
Shell aliases extend the command surface
GitHub documents that shell aliases execute through the shell. This probe used a plain version alias and did not test shell aliases or extensions.
In practice: Review imported aliases and extension code before running them; avoid treating a short alias as a complete description of its effects.
Version, environment and fixture
- Version or deployment
- 2.98.0 (2026-08-20)
- Tested target
- GitHub CLI installed Windows executable
- Artifact identity
- SHA-256 a1701e3c806a805981554ace7df04812772c6449bdcfd1a77675013d97786401 of the installed executable; this identifies the tested file, not an independent provenance audit.
- Environment and fixture
- Windows 11 x64; Python 3.12.10 harness. Raw timestamps UTC.
- Fresh per-tool home/config/cache; child environment constructed from OS/runtime paths, explicit isolation variables and no inherited credentials. Synthetic fixtures only; no user account sign-in.
Checks and results
4 recorded checks. Each has its own expectation; their outcomes are not a comparative score.
Installed versionMet expectation
- Method
<user-home>\AppData\Local\Microsoft\WinGet\Packages\GitHub.cli_Microsoft.Winget.Source_8wekyb3d8bbwe\bin\gh.exe --version- Expected
- Print the executable version.
- Observed
- Exit 0. gh version 2.98.0 (2026-08-20) https://github.com/cli/cli/releases/tag/v2.98.0
Empty authentication configurationMet expectation
- Method
gh auth status- Expected
- Report no logged-in hosts and return nonzero.
- Observed
- Exit 1. You are not logged into any GitHub hosts. To log in, run: gh auth login
Write a local aliasMet expectation
- Method
gh alias set ib-local version- Expected
- Store ib-local -> version in the isolated configuration.
- Observed
- Exit 0. The alias was written to the isolated GH_CONFIG_DIR.
Execute the local aliasMet expectation
- Method
gh ib-local- Expected
- Resolve ib-local to the version command.
- Observed
- Exit 0. gh version 2.98.0 (2026-08-20) https://github.com/cli/cli/releases/tag/v2.98.0
Practical caveats
- The test used an existing 2.98.0 binary, not a fresh latest-release installation.
- Local configuration isolation is a test control; it is not an operating-system sandbox.
What this evaluation does not establish
- Authenticated repository reads/writes, organization policy, fine-grained token scopes and merge protections.
- Credential-store fallback, extension installation/execution and adversarial alias behavior.
Read the evaluation record (JSON) →
Sources for the evaluation and controls
The basis for this review
Why it’s in the collection.
An editorial first stop: the task is clear, read-only examples are useful immediately, and authentication and command effects are documented. This is not an adoption or overall-quality ranking.
The number is an editorial starting order within the cli tools collection. It does not measure popularity, speed, reliability or safety.
What we reviewed
- Official manual, repository and authentication behavior
- Documented command and access boundaries
The evaluation above lists the current runtime coverage and untested behavior.
Reviewed Oct 18, 2026. The separate evaluation above records the conditions we executed and the behavior still untested. Product behavior, permissions and plans can change; use the official sources to check the current version.
Follow the evidence
Official sources.
- CLI repository and platform support ↗github.com
- Pull-request list reference ↗cli.github.com
- Authentication and credential storage ↗cli.github.com
- CLI license ↗github.com