Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/bensadeh/circumflex
🌿 It's Hacker News in your terminal
https://github.com/bensadeh/circumflex
cli client command-line console hacker hacker-news hackernews news reader terminal tui ycombinator
Last synced: 4 days ago
JSON representation
🌿 It's Hacker News in your terminal
- Host: GitHub
- URL: https://github.com/bensadeh/circumflex
- Owner: bensadeh
- License: agpl-3.0
- Created: 2020-07-28T05:08:10.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-12-30T12:35:48.000Z (15 days ago)
- Last Synced: 2025-01-03T04:00:57.669Z (11 days ago)
- Topics: cli, client, command-line, console, hacker, hacker-news, hackernews, news, reader, terminal, tui, ycombinator
- Language: Go
- Homepage:
- Size: 40.5 MB
- Stars: 1,332
- Watchers: 6
- Forks: 30
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-github-repos - bensadeh/circumflex - 🌿 It's Hacker News in your terminal (Go)
- awesome-repositories - bensadeh/circumflex - 🌿 It's Hacker News in your terminal (Go)
- awesome-hackernews - circumflex - It's HN in your terminal. `AGPL-3.0` (Clients / CLI & TUI)
- charm-in-the-wild - circumflex - Read Hacker News in the terminal. (_built with Bubble Tea_) (Applications / RSS and News)
- stars - circumflex
- stars - circumflex
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
- ⚡️ **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](#installing)
* [Comment section](#comment-section)
* [Reader mode](#reader-mode)
###
* [Syntax highlighting](#syntax-highlighting)
* [Nerd Fonts](#nerd-fonts)
* [History](#history)
###
* [Favorites](#favorites)
* [Settings](#settings)
* [Keymaps](#keymaps)
###
* [Under the hood](#under-the-hood)
***
## Installing
The binary name for `circumflex` is `clx`.
#### Package managers
```console
# Homebrew
brew install circumflex
# Nix
nix-shell -p circumflex
# AUR
yay -S circumflex
```
#### From source
```console
# Go
go run main.go
```
> [!IMPORTANT]
> When building from source, make sure that you are using the latest version
> of [`less`](http://greenwoodsoftware.com/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.
## 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](https://www.ycombinator.com/companies/), 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:
```console
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:
```console
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
```console
add [ID] Add item to list of favorites by ID
comments [ID] Go directly to the comment section by ID
article [ID] Read the linked article associated with an item based on the ID
url [URL] Open a URL directly in Reader Mode
clear Clear the history of visited IDs
```
### Flags
```console
-a, --auto-expand Automatically expand all replies upon entering
the comment section
--categories=[string] Set the categories in the header
(available: "top,best,ask,show,new")
(default: "top,best,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:
| 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](https://github.com/charmbracelet/bubbletea) for the TUI
* [cobra](https://github.com/spf13/cobra) for the CLI
* [Algolia's Search API](https://hn.algolia.com/api) for submissions
* [cheeaun's unofficial Hacker News API](https://github.com/cheeaun/node-hnapi) for comments
* [`less`](http://greenwoodsoftware.com/less/) for viewing comments and articles
* [go-term-text](https://github.com/MichaelMure/go-term-text) and [lipgloss](https://github.com/charmbracelet/lipgloss) for text formatting
* [go-readability](https://github.com/go-shiori/go-readability), [html-to-markdown](https://github.com/JohannesKaufmann/html-to-markdown)
and [Glamour](https://github.com/charmbracelet/glamour) for formatting
Screenshots use:
* [iTerm2](https://iterm2.com/) for the terminal
* [Palenight Theme](https://github.com/JonathanSpeek/palenight-iterm2) for the color scheme
* [JetBrains Mono](https://github.com/JetBrains/JetBrainsMono) for the font