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	Customization Environment Variable
?	toggle help	GH_NOTIFY_TOGGLE_HELP_KEY
enter	view the selected notification in the 'less' pager	GH_NOTIFY_VIEW_KEY
tab	toggle notification preview	GH_NOTIFY_TOGGLE_PREVIEW_KEY
shifttab	resize the preview window	GH_NOTIFY_RESIZE_PREVIEW_KEY
shift↑↓	scroll the preview up/ down
ctrla	mark all displayed notifications as read and reload	GH_NOTIFY_MARK_ALL_READ_KEY
ctrlb	browser	GH_NOTIFY_OPEN_BROWSER_KEY
ctrld	view diff	GH_NOTIFY_VIEW_DIFF_KEY
ctrlp	view diff in patch format	GH_NOTIFY_VIEW_PATCH_KEY
ctrlr	reload	GH_NOTIFY_RELOAD_KEY
ctrlt	mark the selected notification as read and reload	GH_NOTIFY_MARK_READ_KEY
ctrlx	write a comment with the editor and quit	GH_NOTIFY_COMMENT_KEY
ctrly	toggle the selected notification	GH_NOTIFY_TOGGLE_KEY
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'"

GH_NOTIFY_FZF_OPTS

This environment variable lets you specify additional options and key bindings to customize the search and display of notifications. Unlike FZF_DEFAULT_OPTS, GH_NOTIFY_FZF_OPTS specifically applies to the gh notify extension.

# --exact: Enables exact matching instead of fuzzy matching.
GH_NOTIFY_FZF_OPTS="--exact" gh notify -an 5

# With the height flag and ~, fzf adjusts its height based on input size without filling the entire screen.
# Requires fzf +0.34.0
GH_NOTIFY_FZF_OPTS="--height=~100%" gh notify -an 5

Modifying Keybindings

You can also customize the keybindings created by this extension to avoid conflicts with the ones defined by fzf. For example, change ctrl-p to ctrl-u:

GH_NOTIFY_VIEW_PATCH_KEY="ctrl-u" gh notify

Or, switch the binding for toggling a notification and toggling the preview.

GH_NOTIFY_TOGGLE_KEY="tab" GH_NOTIFY_TOGGLE_PREVIEW_KEY="ctrl-y" gh notify

NOTE: The assigned key must be a valid key listed in the fzf man page:

man --pager='less -p "^\s+AVAILABLE_KEYS"' fzf

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