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

circumflex

License Changelog Go Version

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

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:

  • Text formatting in bold, italics and code where available
  • Labels for Original Posters (OP), Parent Posters (PP) and moderators (mod)
  • Adjustable margins and comment width

^

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.

Tweaks

Low contrast headers

Overview

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

Classic Hacker News header

You can enable the classic Hacker News header with the -n flag.

^

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)
-j Show X is hiring posts from YC-funded startups (does not affect the monthly Who is Hiring? posts)
-t Hide the indentation symbol from the comment section (does not affect quotes)
-n Set the header to orange

Under the hood

circumflex uses:

Screenshots use:

Comments
  • Comments not displayed

    Comments not displayed

    I'm running circumflex on Linux Mint 20.3 (64-bit)

    ~$ uname -a
    Linux xxxxx 5.4.0-126-generic #142-Ubuntu SMP Fri Aug 26 12:12:57 UTC 2022 x86_64 x86_64 x86_64 GNU/Linux
    

    clx was installed using homebrew on linux

    The "correct" version of less seems to be in the path

      ~$ less --version
      less 608 (PCRE2 regular expressions)
      Copyright (C) 1984-2022  Mark Nudelman
    

    When <enter> is pressed on any item, it always returns a screen showing 0 comments 0 points, even though there are many comments

    Screenshot_2022-10-14_16-10-54

    Just in case it matters, I've tried it on the kitty terminal (0.25.2) and xfce4-terminal 0.8.10 (Xfce 4.16)

    Thank you!

  • Got an issue when run go run main.go

    Got an issue when run go run main.go

    When trying to run go run main.go got this:

        panic: runtime error: slice bounds out of range [:28] with capacity 0
    
    goroutine 1 [running]:
    code.rocketnine.space/tslocum/cview.(*Application).HandlePanic(0xc000979e00)
        /Users/user123/go/pkg/mod/code.rocketnine.space/tslocum/[email protected]/application.go:142 +0x85
    panic({0x1801380, 0xc0001432a8})
        /usr/local/Cellar/go/1.17.2/libexec/src/runtime/panic.go:1038 +0x215
    clx/handler.getOnlineStories(0xc000b69b78, 0x17440f3, 0x1c, 0xc5, 0x3e, 0xc00095f680, 0xc0004df800)
        /Users/user123/svalko/circumflex/handler/handler.go:88 +0x28a
    clx/handler.(*StoryHandler).GetStories(0xc0000244c0, 0xc000523780, 0xc000980a40, 0x1167501, 0x0, 0x9c)
        /Users/user123/svalko/circumflex/handler/handler.go:48 +0x79
    clx/model.SetAfterInitializationAndAfterResizeFunctions.func1(0x116a210, 0xc000b69cb0)
        /Users/user123/svalko/circumflex/model/model.go:42 +0xe5
    code.rocketnine.space/tslocum/cview.(*Application).Run.func2({0x17b75a0, 0xc00075c000})
        /Users/user123/go/pkg/mod/code.rocketnine.space/tslocum/[email protected]/application.go:426 +0x2ea
    code.rocketnine.space/tslocum/cview.(*Application).Run(0xc000979e00)
        /Users/user123/go/pkg/mod/code.rocketnine.space/tslocum/[email protected]/application.go:481 +0x34a
    clx/clx.Run(0xc00095f050)
        /Users/user123/svalko/circumflex/clx/clx.go:21 +0xb2
    clx/cmd.Root.func1(0xc0009a0280, {0x1849cc8, 0x0, 0x0})
        /Users/user123/svalko/circumflex/cmd/root.go:34 +0xaa
    github.com/spf13/cobra.(*Command).execute(0xc0009a0280, {0xc000020200, 0x0, 0x0})
        /Users/user123/go/pkg/mod/github.com/spf13/[email protected]/command.go:860 +0x5f8
    github.com/spf13/cobra.(*Command).ExecuteC(0xc0009a0280)
        /Users/user123/go/pkg/mod/github.com/spf13/[email protected]/command.go:974 +0x3bc
    github.com/spf13/cobra.(*Command).Execute(...)
        /Users/user123/go/pkg/mod/github.com/spf13/[email protected]/command.go:902
    main.main()
        /Users/user123/svalko/circumflex/main.go:9 +0x1e
    exit status 2
    

    My environment is:

    >git status HEAD detached at 1.27 nothing to commit, working tree clean

    >go version go version go1.17.2 darwin/amd64

  • Wrong formatting

    Wrong formatting

    Hi, great reader!

    Unfortunately there is something wrong with how the news are printed in my terminal:

    image

    My terminal can print Unicode characters:

    image

    Do you've any hint?

  • panic: runtime error: slice bounds out of range

    panic: runtime error: slice bounds out of range

    I have this issue after installing today. It worked a few seconds then this happened. possibly after a resize of the window.

    panic: runtime error: slice bounds out of range [:37] with capacity 0
    
    goroutine 66 [running]:
    clx/hn/services/hybrid.(*Service).FetchItems(0x0?, 0x24, 0x0?)
    	/home/runner/work/circumflex/circumflex/hn/services/hybrid/hybrid.go:30 +0x4ac
    clx/bubble/list.(*Model).FetchFrontPageStories.func1()
    	/home/runner/work/circumflex/circumflex/bubble/list/list.go:114 +0x88
    github.com/charmbracelet/bubbletea.(*Program).StartReturningModel.func6.1()
    	/home/runner/go/pkg/mod/github.com/charmbracelet/[email protected]/tea.go:469 +0x38
    created by github.com/charmbracelet/bubbletea.(*Program).StartReturningModel.func6
    	/home/runner/go/pkg/mod/github.com/charmbracelet/[email protected]/tea.go:467 +0x11c
    ❯ stty size
    40 127
    

    Originally posted by @matthiasg in https://github.com/bensadeh/circumflex/issues/3#issuecomment-1278625189

  • Runtime error: invalid memory address or nil pointer dereference

    Runtime error: invalid memory address or nil pointer dereference

    I get the following error when I try to run go run main.go (same with prebuilt binary).

    panic: runtime error: invalid memory address or nil pointer dereference                          •
    [signal SIGSEGV: segmentation violation code=0x1 addr=0x8 pc=0x74bc7e]
    
    goroutine 52 [running]:
    clx/hn/services/hybrid.mapStories(0x0)
            /tmp/tmp.LyjH2Hoy4p/circumflex/hn/services/hybrid/hybrid.go:99 +0x3e
    clx/hn/services/hybrid.(*Service).FetchItems(0xc00002e060?, 0x2d, 0x1?)
            /tmp/tmp.LyjH2Hoy4p/circumflex/hn/services/hybrid/hybrid.go:45 +0x40d
    clx/bubble/list.(*Model).FetchFrontPageStories.func1()
            /tmp/tmp.LyjH2Hoy4p/circumflex/bubble/list/list.go:114 +0x96
    github.com/charmbracelet/bubbletea.(*Program).StartReturningModel.func6.1()
            /home/foo/.asdf/installs/golang/1.19.1/packages/pkg/mod/github.com/charmbracelet/[email protected]/tea.go:469 +0x33
    created by github.com/charmbracelet/bubbletea.(*Program).StartReturningModel.func6
            /home/foo/.asdf/installs/golang/1.19.1/packages/pkg/mod/github.com/charmbracelet/[email protected]/tea.go:467 +0x14d
    exit status 2
    

    System info:

    Pop!_OS 22.04 LTS
    Linux 5.19.0-76051900-generic x86_64
    go version go1.19.1 linux/amd64
    tmux 3.3a
    alacritty 0.10.1-rc1
    
  • Panic when running clx

    Panic when running clx

    When running clx I get

    panic: runtime error: index out of range [29] with length 29 [recovered]
    	panic: runtime error: index out of range [29] with length 29
    
    goroutine 1 [running]:
    gitlab.com/tslocum/cview.(*Application).Run.func1(0xc00011fb80)
    	/home/runner/go/pkg/mod/gitlab.com/tslocum/[email protected]/application.go:299 +0x87
    panic(0x843d00, 0xc000a54eb8)
    	/opt/hostedtoolcache/go/1.16.0/x64/src/runtime/panic.go:965 +0x1b9
    clx/model.SetListItemsToCurrentPage(0xc0001d32b0, 0xc0002de0f0, 0x1d, 0x1e, 0x0, 0x1e, 0xc000020640)
    	/home/runner/work/circumflex/circumflex/model/model.go:221 +0x2a5
    clx/model.showPageAfterResize(0xc00007cb90, 0xc0001d32b0, 0xc000078be0, 0x4, 0x4, 0xc00010cc40, 0xc000020640)
    	/home/runner/work/circumflex/circumflex/model/model.go:95 +0xa9
    clx/model.SetAfterInitializationAndAfterResizeFunctions.func1(0x11a, 0x40)
    	/home/runner/work/circumflex/circumflex/model/model.go:43 +0x196
    gitlab.com/tslocum/cview.(*Application).Run.func3(0x80a2a0, 0xc0001d0030)
    	/home/runner/go/pkg/mod/gitlab.com/tslocum/[email protected]/application.go:422 +0x31e
    gitlab.com/tslocum/cview.(*Application).Run(0xc00011fb80, 0x0, 0x0)
    	/home/runner/go/pkg/mod/gitlab.com/tslocum/[email protected]/application.go:457 +0x304
    main.main()
    	/home/runner/work/circumflex/circumflex/main.go:38 +0x150
    

    Tried updating with brew update and running again, with the same error.

  • Extract major version of less before verifying

    Extract major version of less before verifying

    At its current version, the verification process fails when someone is running a patched version of less. For eg. version 581.2

    Though less doesn't usually ship versions like this but version 581.2 is the one that is installed by default on MacOS.

    Current version of circumflex fails with an error as below,

    panic: strconv.Atoi: parsing "581.2": invalid syntax
    
    goroutine 1 [running]:
    clx/cli.VerifyLessVersion(0x260)
    	/home/runner/work/circumflex/circumflex/cli/cli.go:57 +0x78
    clx/cmd.verifyLess(0xa1?)
    	/home/runner/work/circumflex/circumflex/cmd/root.go:125 +0x28
    clx/cmd.Root.func1(0x14000348600?, {0x103494948?, 0x0?, 0x0?})
    	/home/runner/work/circumflex/circumflex/cmd/root.go:43 +0xfc
    github.com/spf13/cobra.(*Command).execute(0x14000348600, {0x1400001e210, 0x0, 0x0})
    	/home/runner/go/pkg/mod/github.com/spf13/[email protected]/command.go:920 +0x5b0
    github.com/spf13/cobra.(*Command).ExecuteC(0x14000348600)
    	/home/runner/go/pkg/mod/github.com/spf13/[email protected]/command.go:1040 +0x354
    github.com/spf13/cobra.(*Command).Execute(...)
    	/home/runner/go/pkg/mod/github.com/spf13/[email protected]/command.go:968
    main.main()
    	/home/runner/work/circumflex/circumflex/main.go:9 +0x20
    

    Signed-off-by: PrayagS [email protected]

  • Help screen is not overwritten properly

    Help screen is not overwritten properly

    Screenshot 2022-10-14 at 11 26 33

    When pressing i or ?, the screen is redrawn to show the keyboard mappings and other helpful information.

    Then pressing Esc or q closes the help screen and shows the list of news items again.

    But the list of news items is redrawn in such a way that the empty lines do not overwrite the lines from the help screen. The resulting view is a mix of a part of the help screen, often skipping some lines next to the news items.

  • Panic when pressing `r` (reload) button twice

    Panic when pressing `r` (reload) button twice

    When I run circumflex as clx -a

    I get panic when I press r button twice

    panic: Unsupported c: 5
    
    goroutine 44 [running]:
    clx/hn/services/hybrid.getCategory(0x20?)
    	/home/user/Projects/circumflex/hn/services/hybrid/hybrid.go:92 +0xc9
    clx/hn/services/hybrid.fetchStoriesList(0x0?)
    	/home/user/Projects/circumflex/hn/services/hybrid/hybrid.go:54 +0x4d
    clx/hn/services/hybrid.(*Service).FetchItems(0x0?, 0x9, 0x0?)
    	/home/user/Projects/circumflex/hn/services/hybrid/hybrid.go:28 +0x36
    clx/bubble/list.Model.Update.func4()
    	/home/user/Projects/circumflex/bubble/list/list.go:587 +0x9b
    github.com/charmbracelet/bubbletea.(*Program).StartReturningModel.func6.1()
    	/home/user/go/pkg/mod/github.com/charmbracelet/[email protected]/tea.go:469 +0x33
    created by github.com/charmbracelet/bubbletea.(*Program).StartReturningModel.func6
    	/home/user/go/pkg/mod/github.com/charmbracelet/[email protected]/tea.go:467 +0x14d
    

    Platform

    Linux 6.0.2-zen1-1-zen
    go version go1.19.2 linux/amd64
    
  • Error while installing with `go run main.go` from git repo:

    Error while installing with `go run main.go` from git repo: "package embed is not in GOROOT"

    This is the full error: bubble/list/list.go:4:2: package embed is not in GOROOT (/usr/lib/go-1.15/src/embed)

    I'm on Debian 11.5 Bullseye with go installed from apt: go 1.15.15 linux/amd64

    This error makes me unable to install the package.

  • Added Dockerfile to run clx as a container.

    Added Dockerfile to run clx as a container.

    Hi,

    This PR add support for circumflex to run in Docker based environments

    I have tested this on podman. Because we need latest version of less I have to build it from source for a small container image.

    The resulting image is of size 34.6 MB.

    Known issues:

    The terminal colors doesn't seem to work when I run it inside the container.

    Thanks :)

  • Make compatible with go install

    Make compatible with go install

    Is it possible to install via

    go install github.com/bensadeh/circumflex@latest
    

    now it's error with

    go install github.com/bensadeh/circumflex@latest                                                                 1 ↵
    go: downloading github.com/bensadeh/circumflex v0.0.0-20221014062858-feb512648702
    go: github.com/bensadeh/circumflex@latest: github.com/bensadeh/[email protected]: parsing go.mod:
            module declares its path as: clx
                    but was required as: github.com/bensadeh/circumflex
    
News-parser-cli - Simple CLI which allows you to receive news depending on the parameters passed to it
News-parser-cli - Simple CLI which allows you to receive news depending on the parameters passed to it

news-parser-cli Simple CLI which allows you to receive news depending on the par

Jan 4, 2022
📱🥴 TikTok terminal client for browsing & downloading videos
📱🥴 TikTok terminal client for browsing & downloading videos

tiktik ?? ?? - TikTok Terminal Client Name inspiration - this yt vid Huge Thanks to Egor who wrote the parsing part Installation ?? go get -u github.c

Dec 3, 2022
A command line tool that builds and (re)starts your web application everytime you save a Go or template fileA command line tool that builds and (re)starts your web application everytime you save a Go or template file

# Fresh Fresh is a command line tool that builds and (re)starts your web application everytime you save a Go or template file. If the web framework yo

Nov 22, 2021
Pudl - Pudelek.pl news in command line

Pudl Command line tool to help you stay on top of news on pudelek.pl (Polish gos

Feb 4, 2022
An open-source GitLab command line tool bringing GitLab's cool features to your command line
An open-source GitLab command line tool bringing GitLab's cool features to your command line

GLab is an open source GitLab CLI tool bringing GitLab to your terminal next to where you are already working with git and your code without switching

Dec 30, 2022
I like reading news but I also like the terminal. I am leaning and practicing my go.
I like reading news but I also like the terminal. I am leaning and practicing my go.

I made an api and didn't know how to use it. Screenshots The initial screen when you first run the app. The screen after you specify an id. This app u

Jan 14, 2022
t is a command line tool for testing on your terminal.
t is a command line tool for testing on your terminal.

t t is a command line tool for testing on your terminal. Installation $ go get github.com/yusukebe/t/cmd/t Usage Basic usage: $ t hello hello # => PA

May 5, 2022
A command line tool to prompt for a value to be included in another command line.

readval is a command line tool which is designed for one specific purpose—to prompt for a value to be included in another command line. readval prints

Dec 22, 2021
The sntr command-line program gives you convenient access to Sentry directly from your terminal.

sntr: all of Sentry at your fingertips The sntr command-line program gives you convenient access to Sentry directly from your terminal. Disclaimer: th

Jan 31, 2022
a python command-line tool which draws basic graphs in the terminal
a python command-line tool which draws basic graphs in the terminal

Termgraph A command-line tool that draws basic graphs in the terminal, written in Python. Graph types supported: Bar Graphs Color charts Multi-variabl

Dec 30, 2022
Holly🪴 o!rdr command line tool to upload replays to it from the terminal

Holly ?? o!rdr command line tool to upload replays to it from the terminal Holly is a CLI that allows you to upload osu! replays to o!rdr from the ter

Apr 25, 2022
git-xargs is a command-line tool (CLI) for making updates across multiple Github repositories with a single command.
git-xargs is a command-line tool (CLI) for making updates across multiple Github repositories with a single command.

Table of contents Introduction Reference Contributing Introduction Overview git-xargs is a command-line tool (CLI) for making updates across multiple

Dec 31, 2022
git-xargs is a command-line tool (CLI) for making updates across multiple GitHub repositories with a single command
git-xargs is a command-line tool (CLI) for making updates across multiple GitHub repositories with a single command

git-xargs is a command-line tool (CLI) for making updates across multiple GitHub repositories with a single command. You give git-xargs:

Feb 5, 2022
A command line tool for simplified docker volume command built with go

dockervol A command line tool for simplified docker volume command built with go. Features: Remove anonymous volume (beta) Remove volume by matching n

Dec 18, 2021
Watch your favourite anime using the video player of your choice directly from the command line

anime-cli Watch your favourite anime using the video player of your choice direc

Feb 10, 2022
ls Xtended : A command line utility which lets you navigate through terminal like a pro 😎.
ls Xtended : A command line utility which lets you navigate through terminal like a pro 😎.

Navigate through terminal like a pro ?? ?? Demo • ⚗️ Installation • ?? Contribution • ❗ Known Issues ❓ Why? It's a pain to cd and ls multiple times to

Dec 14, 2022
Simple command line serial terminal for the Zolatron 64

ZolaTerm Simple command line serial terminal for the Zolatron 64. Written in Go. I'm using Go routines for receiving text (so that it can be displayed

Nov 7, 2021
Jan 3, 2023
An interactive command-line tool to manage your environments
An interactive command-line tool to manage your environments

goto An interactive command-line tool to manage your environments Overview You always need to login to some Linux machine or connect to a MySQL instan

Jul 11, 2022