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
• ⚡️ Familiar tools — content is piped to the pager less

You might also like:

• 🤹 Native terminal colors — you bring your own color scheme, circumflex does the rest
• 🛠 Easy customization — quickly enable or disable features
• ❤️ Add to favorites — save interesting submissions for later

Table of Contents

• Installing
• Keymaps
• Comment section

• Reader mode
• Syntax highlighting
• Favorites

• Headers
• Tweaks
• Settings

• Under the hood

---

Installing

Via Homebrew

circumflex is available as a Tap.

# Install
brew install bensadeh/circumflex/circumflex

# Run
clx

From source

You can also build circumflex from source:

# Run
go run main.go

Keymaps

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

Enter: Read comments
Space: Read article in Reader Mode

r: Refresh
Tab: Change category

o: Open link to article in browser
c: Open comment section in browser

f: Add to favorites
x: Remove from favorites

q: Quit

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
• 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.

Mark submissions as read

Visited submissions are marked as read.

A list of submissions (by ID) 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.

Headers

Run circumflex with the -e/header-type flag and a number to set the header on the main screen:

clx -e [1-3]

Stock dark mode (default)

Stock light mode (1)

No colors (2)

Orange header (3)

Tweaks

Low contrast headers

Some terminals brighten text in bold in order to give them stronger contrast in dark color schemes. circumflex uses bold text to give headers and authors names additional contrast for better legibility.

See example screenshots below (low contrast header) of terminal output which does not brighten bold fonts.

Below are a few examples on how to enable bold text in bright colors in different terminals.

Alacritty

• Set draw_bold_text_with_bright_colors to true
• Define bright_foreground and set it to a brighter value than foreground
• (See alacritty/alacritty/pull/1026 for more info)

Terminal (macOS)

• Check Use bright colors for bold text under Profiles

iTerm (macOS)

• Check Brighten bold text under Profiles → Colors

Settings

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

A table of available flags is provided below:

Flag	Description
-c	Set the comment width
-l	Disable syntax highlighting for the headlines
-o	Disable syntax highlighting in the comment section.
-s	Disable conversion of smileys (:)) to emojis (😊)
-d	Disable marking submissions as read
-r	Show each line with a number relative to the currently selected element (similar to Vim's hybrid line number mode)
-t	Hide the indentation symbol from the comment section (does not affect quotes)
-e	Set the header type

Under the hood

circumflex uses:

• tcell and cview for the TUI
• cobra and viper for the CLI
• Algolia's Search API and cheeaun's unofficial Hacker News API for providing submissions and comments
• less for viewing comments and articles
• go-term-text for text formatting
• go-readability and html-to-markdown for formatting articles in Reader Mode

Screenshots use:

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