README
¶
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
- ⚡️ Vim-style navigation — scroll through, jump between and collapse threads with familiar keybindings
You might also like:
- 🔍 Search — quickly find old submissions by searching all of HN
- 🪟 Wide view — story list and content side by side on wide terminals
- 🤹 Native terminal colors — you bring your own color scheme,
circumflexdoes the rest - 💎 Nerd Fonts — full support for Nerd Fonts as icons
- ❤️ Add to favorites — save interesting submissions for later
Installing
The binary name for circumflex is clx.
# Homebrew
brew install circumflex
# Nix
nix-shell -p circumflex
# AUR
yay -S circumflex
# Go
go install github.com/bensadeh/circumflex/cmd/clx@latest
# From source
go run ./cmd/clx
Features
Comment section
Press Enter to view the comment section.
The comment section has two modes: read mode and navigate mode.
In read mode, you can scroll using the usual vim bindings. You can also jump between top-level comments (
n/N), and you can expand and collapse threads by quote level (h/l) or all at once
(Enter).
Press a to enter navigate mode, where you can individually select comments and collapse specific threads.
Press Esc to return to read mode.
circumflex is read-only and does not support logging in, voting or commenting.
Reader Mode
Press Space to read the linked article in Reader Mode. Just like in the comment section, you can jump between headers using n/N, and you can scroll using the usual vim bindings.
In terminals with Kitty graphics support, press Enter to show the article's images.
Link selector
Press Tab to select links in the comment section or in Reader Mode. Move between links with j/k and open the selected one with Enter.
Links open in place: articles in Reader Mode, links to other Hacker News discussions in the comment section. Press q to go back to where you were.
Wide view
On wide terminals (180 characters), circumflex opens in dual pane mode. Toggle it for the session with z,
or turn it off entirely with:
clx --wide-view never
Search
Press / to search all of Hacker News, powered by Algolia. Sort by popularity or date with s and narrow the date range with d.
The comment section and Reader Mode also support search in the content with /: search for the term and jump between matches with n/N.
Favorites
Press f to add the highlighted submission to your favorites. Remove it with x.
You can also add a submission by ID from the command line:
clx add [id]
Favorites are stored in favorites.toml in the config directory, human-readable and VCS-friendly. A
favorites.json from earlier versions is migrated automatically.
History
Visited submissions are marked as read, and comments added since your last visit are highlighted.
History is stored in history.json in the cache directory. Disable tracking with -d/--no-history, or clear it with:
clx clear-history
Categories
Switch between categories with Tab. The header shows top, best, ask, show and favorites by default.
Pick which ones appear (and in what order) with the --categories flag:
clx --categories top,new,best
Available categories are top, best, new, ask, show, jobs and favorites.
Theme and Configuration
circumflex uses your terminal's color scheme by default. If you want to customize the colors or set any flags
persistently, use the following commands to write out the default config to the config directory:
clx default-config
clx default-theme
Keymaps
Main view keybindings — press i in any view for the full list, including comment and reader mode.
| Key | Action |
|---|---|
| Enter | View comments |
| Space | Reader Mode |
| Tab | Next category |
| / | Search Hacker News |
| r | Refresh stories |
| o | Open story in browser |
| c | Open comments in browser |
| f | Add to favorites |
| x | Remove from favorites |
| u | Toggle read |
| z | Toggle wide view |
| q | Quit |
Usage
Run clx help or man clx for a full list of available commands and flags.
Directories
¶
| Path | Synopsis |
|---|---|
|
clx
command
|
|
|
gen-completions
command
|
|
|
gen-config-example
command
|
|
|
gen-theme-example
command
|
|
|
guess-report
command
Command guess-report scores highlight.GuessLang against the real web.
|
Command guess-report scores highlight.GuessLang against the real web. |
|
Package frame draws the faint rounded box that the meta block and the help screens' panels share: an opening rule that doubles as the header row, body rows between side borders, and a closing rule.
|
Package frame draws the faint rounded box that the meta block and the help screens' panels share: an opening rule that doubles as the header row, body rows between side borders, and a closing rule. |
|
Package graphics tracks the terminal's Kitty graphics support and builds the escape sequences behind reader mode's high-resolution images.
|
Package graphics tracks the terminal's Kitty graphics support and builds the escape sequences behind reader mode's high-resolution images. |
|
Package headline styles story titles for the list rows and pane headers.
|
Package headline styles story titles for the list rows and pane headers. |
|
services/algolia
Package algolia searches Hacker News through the Algolia HN Search API.
|
Package algolia searches Hacker News through the Algolia HN Search API. |
|
Package layout owns the terminal geometry: the wide-layout split arithmetic and the width every text column derives from the pane it renders in.
|
Package layout owns the terminal geometry: the wide-layout split arithmetic and the width every text column derives from the pane it renders in. |
|
Package meta renders the story meta block: the header a detail view draws above its content.
|
Package meta renders the story meta block: the header a detail view draws above its content. |
|
Package view is the application coordinator: it owns the state machine, routes messages, orchestrates fetches and lays out the panes.
|
Package view is the application coordinator: it owns the state machine, routes messages, orchestrates fetches and lays out the panes. |
|
list
Package list is the story-list pane: a pager over fetched stories plus its rendering.
|
Package list is the story-list pane: a pager over fetched stories plus its rendering. |
|
pane
Package pane holds what the full-screen detail views — the comment section and reader mode — share: the content-aware viewport and search engine, frame chrome and footers, browser commands, and the standalone runner.
|
Package pane holds what the full-screen detail views — the comment section and reader mode — share: the content-aware viewport and search engine, frame chrome and footers, browser commands, and the standalone runner. |