Turn gh issue status into a Useful Triage Check

Monday standup, and you cannot remember what is actually still assigned to you: gh issue status lists it in one go.

It shows issues assigned to you, mentioning you, or opened by you, and this guide covers making that output easier to read or feed into a script. The examples were checked with GitHub CLI 2.87.3 from Homebrew on this machine. Allow about ten minutes.

1. Check the installed command and authentication

Confirm which executable will run and ask GitHub CLI whether its authentication is usable:

$ command -v gh
/home/linuxbrew/.linuxbrew/bin/gh
$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh auth status

The path and version are host-specific. This machine also has an Ubuntu gh package registered as version 2.45.0-1ubuntu0.3+esm3, but the shell resolves the Homebrew binary above. When troubleshooting, check the executable path rather than assuming the distribution package is the one in use.

Checkpoint: Continue only when gh auth status reports a valid account for the host you intend to query. If it requests authentication, follow your organisation's approved login process. Do not paste an access token into this guide's commands or into shell history.

2. Run the human-readable status view

From a local checkout of the repository you want to inspect, run:

$ gh issue status
Issues assigned to you
  #123 Fix the import path

Issues mentioning you
  #127 Document the release process

Issues opened by you
  #119 Add a test for the error case

The headings and issue rows depend on your account and repository. Empty sections are normal. The command's purpose is a personal relevance view, not a complete list of every open issue. Use gh issue list when you need filters such as state, label or author across the repository.

If the current directory is not a checkout, remove that ambiguity by selecting the repository explicitly:

$ gh issue status -R OWNER/REPOSITORY

Replace OWNER/REPOSITORY with a real repository name, such as cli/cli. The -R value may also include a GitHub Enterprise host in the documented [HOST/]OWNER/REPO form. A wrong repository is an easy distraction: a successful command can still show an empty or irrelevant view.

3. Select fields for machine-readable output

Use --json when another command or a saved report needs named fields. The status response is an object containing relevance groups, rather than a bare array:

$ gh issue status -R OWNER/REPOSITORY --json number,title,state
{"assigned":[],"createdBy":[],"mentioned":[]}

With matching issues, each group contains issue objects and the requested fields. The exact order and values depend on the repository. The installed help lists fields including number, title, state, author, labels, url, createdAt and updatedAt. Ask for only what the next step needs; smaller output is easier to review and less likely to become a fragile dependency.

Checkpoint: Inspect the top-level shape before writing a filter. This fails because the result is an object:

$ gh issue status -R OWNER/REPOSITORY --json number,title,state --jq '.[]'
expected an object but got: array ([])

The error wording reflects the empty groups on this machine, but the underlying problem is the same: .[] iterates an object incorrectly for the data you asked for.

4. Make a compact report with jq

The --jq option applies a jq expression to the JSON response. Iterate each relevance group, then each issue inside it:

$ gh issue status -R OWNER/REPOSITORY --json number,title,state +  --jq '[(.assigned[]?, .createdBy[]?, .mentioned[]?)] | .[] | [.number, .state, .title] | @tsv'
123	OPEN	Fix the import path
127	OPEN	Document the release process

The ? suffix keeps an empty group from producing an error. This example deliberately leaves out the group name, so it is a compact issue report rather than a record of why each issue was relevant. If that distinction matters, keep the groups separate in your jq expression or use the unfiltered JSON as the input to a longer script.

Do not parse the default prose headings with awk or a regular expression. They are for people and can change as the CLI improves. JSON fields provide a clearer boundary.

5. Format a stable one-line view with a template

Use --template when Go template output is enough and you want to control the line shape without a separate jq process:

$ gh issue status -R OWNER/REPOSITORY --json number,title,state +  --template '{{range .assigned}}{{printf "assigned\t#%v\t%v\t%v\n" .number .state .title}}{{end}}{{range .createdBy}}{{printf "created\t#%v\t%v\t%v\n" .number .state .title}}{{end}}{{range .mentioned}}{{printf "mentioned\t#%v\t%v\t%v\n" .number .state .title}}{{end}}'
assigned	#123	OPEN	Fix the import path

Templates and jq both operate on the fields named by --json. Keep the expression quoted so the shell does not expand braces or spaces. If you need conditional logic, arrays, or a format consumed by another tool, retain JSON and process it with that tool rather than making a template do too much.

6. Diagnose the common failures

A non-zero exit status means the request did not complete normally. Capture it immediately when using the command in a script:

if ! output=$(gh issue status -R OWNER/REPOSITORY --json number,title,state); then
    printf '%s\n' 'gh issue status failed' >&2
    exit 1
fi
printf '%s\n' "$output"

If a field is rejected, run gh issue status --help on the installed version and choose a field listed there. The local manual and current command may not display exactly the same field catalogue: the executable here offers additional fields such as blockedBy, blocking, issueType, parent, subIssues and subIssuesSummary. Treat those names as version-specific and verify them before putting them in automation.

Done means