pathcl / circumflex

🌿 It's Hacker News in your terminal

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:

• 🤹 Adaptive 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

Via Homebrew

# Install
brew install circumflex

# Run
clx

From source

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

# Install 
go install

# Run
clx

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

clx add [ID]

Add item to list of favorites by ID.

clx read [ID]

Go directly to Reader Mode for a given item ID without first going through the main view.

clx view [ID]

Go directly to the comment section for a given item ID without first going through the main view.

clx clear

Clear the history of visited IDs from ~/.cache/circumflex/history.json.

Flags

-c n, --comment-width=n

Set the comment width

-p, --plain-headlines

Disable syntax highlighting for the headlines

-o, --plain-comments

Disable syntax highlighting in the comment section.

-e, --disable-emojis

Disable conversion of smileys (:)) to emojis (😊)

-d, --disable-history

Disable marking submissions as read

-t, --hide-indent

Hide the indentation symbol from the comment section (does not affect quotes)

-n, --nerdfonts

Use Nerd Fonts icons as decorators

--force-dark-mode, --force-light-mode

Override setting the color scheme automatically

-a, --auto-expand

Auto expand all replies in the comment section

--no-less-verify

Do not verify less version on startup

Keymaps

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

Key	Description
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

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