GitHub CLI Notification Extension

A gh extension to view your GitHub notifications from the command line.

demo.mp4

Install

Make sure you have GitHub CLI (gh) installed.

# install
gh ext install meiji163/gh-notify
# upgrade
gh ext upgrade meiji163/gh-notify
# uninstall
gh ext remove meiji163/gh-notify

To use gh notify interactively, install these tools as well:

• Fuzzy Finder (fzf) - This allows for interaction with listed data.
• Python - In cases where gh can't open the URL in your browser, this one-liner is used as a cross-platform solution: python -m webbrowser <URL>

Usage

gh notify [Flags]

Flags	Description	Example
	show all unread notifications	gh notify
-a	show all (read/ unread) notifications	gh notify -a
-e	exclude notifications matching a string (REGEX support)	gh notify -e "MyJob"
-f	filter notifications matching a string (REGEX support)	gh notify -f "Repo"
-h	show the help page	gh notify -h
-n NUM	max number of notifications to show	gh notify -an 10
-p	show only participating or mentioned notifications	gh notify -ap
-r	mark all notifications as read	gh notify -r
-s	print a static display	gh notify -an 10 -s
-u URL	(un)subscribe a URL, useful for issues/prs of interest	gh notify -u https://github.com/cli/cli/issues/659
-w	display the preview window in interactive mode	gh notify -an 10 -w

Key Bindings fzf

Keys	Description
?	toggle help
enter	view the selected notification in the 'less' pager
tab	toggle notification preview
shifttab	resize the preview window
shift↑↓	scroll the preview up/ down
ctrla	mark all displayed notifications as read and reload
ctrlb	browser
ctrld	view diff
ctrlp	view diff in patch format
ctrlr	reload
ctrlt	mark the selected notification as read and reload
ctrlx	write a comment with the editor and quit
esc	quit

Table Format

Field	Description
unread symbol	indicates unread status
time	time of last read for unread; otherwise, time of last update
repo	related repository
type	notification type
number	associated number
reason	trigger reason
title	notification title

---

Customizations

Fuzzy Finder (fzf)

You can customize the fzf key bindings by exporting ENVIRONMENT VARIABLES to your .bashrc or .zshrc. For AVAILABLE KEYS/ EVENTS, refer to the fzf man page or visit junegunn/fzf#environment-variables on GitHub.

• NOTE: How to use ALT commands in a terminal on macOS?

# ~/.bashrc or ~/.zshrc
# The examples below enable you to clear the input query with alt+c,
# jump to the first/last result with alt+u/d, refresh the preview window with alt+r
# and scroll the preview in larger steps with ctrl+w/s.
export FZF_DEFAULT_OPTS="
--bind 'alt-c:clear-query'
--bind 'alt-u:first,alt-d:last'
--bind 'alt-r:refresh-preview'
--bind 'ctrl-w:preview-half-page-up,ctrl-s:preview-half-page-down'"

GitHub Command Line Tool (gh)

In the gh tool's config file, you can specify your preferred editor. This is particularly useful when you use the ctrlx hotkey to comment on a notification.

# To see more details
gh config
# For example, you can set the editor to Visual Studio Code or Vim.
gh config set editor "code --wait"
gh config set editor vim