circumflex is a command line tool for browsing Hacker News in your terminal

Main features

• 🛋 Everything in one place — read both the comment section and articles in Reader Mode
• 🌈 Syntax highlighting — syntax-aware formatting for comments and headlines
• ⚡️ Read it with less — use the pager you already know for quick and simple navigation

You might also like:

• 🤹 Native terminal colors — you bring your own color scheme, circumflex does the rest
• 💎 Nerd Fonts — full support for Nerd Fonts as icons
• ❤️ Add to favorites — save interesting submissions for later

Table of Contents

• Installing
• Comment section
• Reader mode

• Syntax highlighting
• Nerd Fonts
• History

• Favorites
• Settings
• Keymaps

• Under the hood

Installing

The binary name for circumflex is clx.

Package managers

# Homebrew
brew install circumflex

# Nix
nix-env -iA nixpkgs.circumflex

# AUR
yay -S circumflex

From source

# Clone, change to dir and install
git clone https://github.com/bensadeh/circumflex.git && cd circumflex && go install

Note When building from source, make sure that $GOPATH/bin is in your PATH environment variable and that you are using the latest version of less.

Comment section

Overview

Press Enter to read the comment section.

Comments are pretty-printed and piped to the pager less. To present a nice and readable comment section, circumflex features:

• Rainbow-colored indentation blocks
• Text formatting in bold, italics and code where available
• Labels for Original Posters (OP), Parent Posters (PP) and moderators (mod)

Navigation

The following pair of shortcuts are recommended for browsing and navigating the comment section.

• d/u to scroll half a screen
• j/k to scroll one line at a time
• h/l to hide and show replies
• n/N to jump to the next top-level comment

Reader mode

Press Space to read the submission link in Reader Mode.

Note Some websites do not work well with Reader Mode. If the submission URL points to a domain with known Reader Mode incompatibility, the link cannot be opened in Reader Mode. See validator.go for a full list of incompatible sites.

Syntax highlighting

Quotes

Quotes are indented, italicized and dimmed in order to distinguish them from the rest of the comment.

Hacker News and forum idiosyncrasies

`Code snippets`, @username mentions, $variables and URLs are highlighted.

References

References on Hacker News are formatted as numbers inside brackets. circumflex highlights these numbers for easier cross-referencing.

Categories

Headlines containing the text Ask HN, Tell HN, Show HN and Launch HN are highlighted.

YC-funded startups

Twice a year, Y Combinator funds start-ups through its accelerator program. circumflex highlights these startups to signalize their affiliation with YC.

Nerd Fonts

If you have a Nerd Fonts-patched fonts, you can run clx with the -n or --nerdfonts flag.

History

Mark submissions as read

Visited submissions are marked as read.

Highlight new comments

Comments that are new since the last visit are highlighted.

Disabling history

A list of submissions (by ID and last time visited) are stored in ~/.cache/circumflex/history.json. Disable marking submissions as read by running clx with the -d or --disable-history flag.

You can delete your browsing history from the command line:

clx clear

Favorites

Press f to add the currently highlighted submission to your list of favorites. Remove submissions from the Favorites page with x.

You can add any submission by its ID from the command line:

clx add [id]

Favorites are stored in ~/.config/circumflex/favorites.json. circumflex pretty-prints favorites.json to make it both human-readable and VCS-friendly.

Settings

Overview

Run clx help or man clx for a list of available commands and settings.

Commands

add [ID]    Add item to list of favorites by ID
view [ID]   Go directly to the comment section by ID
read [ID]   Read the linked article associated with an item based on the ID
clear       Clear the history of visited IDs

Flags

-a, --auto-expand           Automatically expand all replies upon entering
                              the comment section
    --categories=[string]   Set the categories in the header
                              (available: "top,new,ask,show,best")
                              (default: "top,new,ask,show")
-c, --comment-width=[int]   Set the comment width 
                              (default 70)
-e, --disable-emojis        Disable conversion of smileys to emojis
-d, --disable-history       Disable marking stories as read
-t, --hide-indent           Hide the indentation bar to the left of the reply
-n, --nerdfonts             Enable Nerd Fonts
    --no-less-verify        Disable checking less version on startup
-o, --plain-comments        Disable syntax highlighting for comments
-p, --plain-headlines       Disable syntax highlighting for headlines
-v, --version               Print current version

Keymaps

Press ?/i to show a list of available keymaps:

Under the hood

circumflex uses:

• Bubble Tea for the TUI
• cobra for the CLI
• Algolia's Search API for submissions
• cheeaun's unofficial Hacker News API for comments
• less for viewing comments and articles
• go-term-text and lipgloss for text formatting
• go-readability, html-to-markdown and Glamour for formatting

Screenshots use:

• iTerm2 for the terminal
• Palenight Theme for the color scheme
• JetBrains Mono for the font