Hands-on review: gh 2.86.0. Public issue reads and JSON filtering, checked October 7, 2026.
Watch the GitHub CLI tutorial
We made this tutorial with Explainroo. The terminal scenes use output from our October 8 run. Installation and login are shown as instructions.
Read the video transcript
Let's read some GitHub issues from the terminal. We'll save the result to a file, then write a task for a coding agent. You can follow along with this public repository. You don't need to clone it or write any code. First, install GitHub CLI. Its command is called gh. The official site has instructions for Windows, macOS and Linux. If you use Homebrew on a Mac, run the command shown here. For another system, follow its instructions on the site, then come back to your terminal. Check that the installation worked with the version command. This machine has version 2.86.0. Yours may be newer. If the command isn't found, open a fresh terminal and try again. If that still fails, check the installation steps for your system. Next, connect your GitHub account. Run the login command and follow its prompts. Choose the browser option when it asks how to authenticate. Complete that login yourself. Once it's done, the agent can use the connection from your shell. Keep your password and access token out of its chat. Before running a new command, have a look at its help. Here we're checking how to list issues. We need a repository, a limit and the fields to return. Those options are listed in the help text. You can ask an agent to read this too. Here's the command we'll use. The repository flag points to the Awesome CLI directory on GitHub. That means the command works from any folder. The limit is three, so we get up to three open issues. We haven't asked for closed issues, so they're left out. The last option requests JSON, with the number and state of each issue. This run returned two open issues, numbered three and one. That's the output from October 8th. You may get a different result as people open or close issues. An empty array means nothing matched. Let's look at issue one on its own. This command asks for the same two fields from a single issue. To read its description and title, run it without the JSON option. That's useful before asking an agent to work on an issue. It needs to know what the issue says. Sometimes a script only needs the issue numbers. Add the filter shown here to pick the number from each object. We now get three and one on separate lines. GitHub CLI includes this filter, so you don't need to install a separate tool for this command. Now save the full result to a file. We've removed the filter to keep the JSON array. The greater-than sign sends that output to the filename on the right. It writes in your current folder and replaces a file with the same name, so choose the filename carefully. Open the saved file to check what you got. This command works on macOS and Linux. PowerShell users can use Get-Content instead. If a command reports an error, check that first. Don't treat an empty file as proof that there are no issues. The request may have failed. We can give the agent the same job now. Name the repository and say which fields you want back. Include the limit so it doesn't fetch more than you need. This task also asks it to report errors and stop before posting or changing anything. You can read the result before deciding what to do next. You now have commands you can run yourself, save in a script or give to an agent. Try reading another issue, or change the fields using the command's help. When you need access to another service, look for its command-line tool in the Awesome CLI directory.
GitHub CLI gives a coding agent commands for issues, pull requests and Actions runs. If the agent has a shell, start there for GitHub work.
We tried the issue-reading command in gh 2.86.0 on October 7, 2026. We named a public repository, asked for JSON and filtered the result. This review covers that read-only task. We didn't run an end-to-end agent benchmark or test write commands.
Install and check the command
Follow the official installation instructions for your operating system. Then check the installed version:
gh --version
If you haven't connected GitHub CLI to your account, use its login command:
gh auth login
The authentication documentation explains the browser flow and token options. Choose credentials that match the account's permissions. Don't paste a token into an agent prompt. Our test used an existing authenticated installation.
gh is GitHub CLI. GitHub Copilot CLI is a different tool, and the commands here don't need it.
Read a few issues from a named repository
First look up the available flags:
gh issue list --help
Then read up to three issues:
gh issue list \
--repo vincentsch/awesome-ai-cli \
--limit 3 \
--json number,state
Our run returned this JSON and exited with status 0:
[{"number":1,"state":"OPEN"}]
The result comes from our public directory repository at the time of the run. Its issues can change. This command didn't change any issue or comment.
--repo matters because an agent can run a command from another working directory. Naming the repository avoids relying on the current checkout. --limit caps the number of issues; the documented default is 30. gh issue list lists open issues by default. Add --state closed or --state all when the task needs them.
The issue list reference lists the filters and JSON fields. This command's JSON is an array. An empty [] means no issues matched this request. It isn't an error by itself. Check the exit status before you use the result.
Filter the result for a script
If the next step needs only the issue number, ask for that field:
gh issue list \
--repo vincentsch/awesome-ai-cli \
--limit 3 \
--json number,state \
--jq '.[].number'
Our run printed:
1
The filter runs on the JSON result. The formatting reference explains --jq. You don't need a separate jq installation for this flag.
That makes a useful building block for a script. You can use the same command from a terminal, a project task or an agent's shell. The JSON scripting guide covers checking output before passing values to another command.
Give the agent the task
You can copy this prompt into an agent that has shell access:
Use gh to read up to 3 open issues in
vincentsch/awesome-ai-cli.
Check gh issue list --help. Return the numbers and states.
If the command fails, report the error and stop.
Ask before posting comments or changing anything.
This is an example prompt, not a transcript of an agent run. The video above covers installing GitHub CLI, logging in, reading issues and using JSON output.
What worked and what this test doesn't cover
The repository flag, field selection and jq filter worked in the installed version we tested. The output was short and easy to use in a script. The help command listed the available options.
This test doesn't show how well an agent handles a large repository, pagination or failed authentication. We also didn't test writing comments, creating issues or merging pull requests.
Those are separate commands that change GitHub. Don't assume they have a dry run because another CLI does. Review the target and the command before you approve them.
If your agent client has no shell, a GitHub MCP connection may be more practical. For an agent that can run commands, start with gh and a read task like this one. The CLI-first article explains why.