hntui README

The project's README from github.com/ahmd-sh/hntui. As one markdown file: README.md.

hntui: Hacker News in your terminal!

A sleek and elegant tui for browsing one of the best tech news sources.

hntui — Hacker News in your terminal 

curl -fsSL https://raw.githubusercontent.com/ahmd-sh/hntui/main/install.sh | sh
hntui

What it does

Requirements

Any modern terminal with truecolor, mouse support, and UTF-8 will work. I've tested it in Ghostty on MacOS. Linux/Windows is supported by OpenTUI but I haven't tried it (yet).

The prebuilt binaries have no dependencies. Installing through npm (or hacking on the code) needs Bun 1.2 or newer.

Install

curl -fsSL https://raw.githubusercontent.com/ahmd-sh/hntui/main/install.sh | sh

Installs a self-contained binary to ~/.local/bin. You can also grab a binary for your platform directly from the releases page. Binaries cover macOS (Apple Silicon) and Linux (x64, arm64) — on an Intel Mac, use the Bun install below.

With Bun

bun add -g @ahmd-sh/hntui

Or run it once without installing:

bunx @ahmd-sh/hntui

Run

hntui

Press q (or Ctrl-C) to quit.

Updating

hntui update

Checks the latest release and, for binary installs, replaces itself in place. Bun installs update with bun add -g @ahmd-sh/hntui instead (hntui update will tell you so). When a newer release exists, the status bar shows a quiet hint. hntui --version prints the installed version.

Keybindings

Story list

Key Action
j / ↓, k / ↑ Move cursor
gg, G Jump to first or last
Ctrl-D, Ctrl-U, PgDown, PgUp Scroll a half page
c, Enter Open the story and read its comments
h / ←, l / → Previous or next tab
Tab, Shift-Tab Cycle through tabs
1 through 6 Jump to a specific category
S Jump to the Saved list
s Save or unsave the highlighted post
o Open the story's URL in your browser
r Refresh the current feed
t Toggle theme
q, Ctrl-C Quit

Story detail (comments)

Key Action
j / ↓, k / ↑ Move the comment cursor
gg, G Jump to first or last comment
Ctrl-D, Ctrl-U, PgDown, PgUp Scroll a half page
Space Collapse or expand the current subtree
Enter Open the links popup for the current comment
s Save or unsave this story
o Open the story's URL
Esc, Backspace, h / ← Back to the list
t Toggle theme
q Quit
Key Action
j, k, ↑, ↓ Move
gg, G First or last link
o, Enter Open the highlighted link
Esc, Backspace Close the popup

Context menu (right-click)

Key Action
j / ↓, k / ↑ Move
Enter Activate
Esc, Backspace Close

Mouse

Most things you can do with the keyboard, you can do with a mouse too.

Selecting and copying text

Because the app captures mouse events, your terminal's normal click-and-drag selection is intercepted. To select text the regular way:

Themes

Press t to toggle. The dark theme is mostly black with orange accents. The light theme is faithful to news.ycombinator.com: white background, orange topbar, the familiar beige row highlight, and HN's classic grey byline text.

Saved posts

Press s on any story to save it. Saved posts get a small star next to the title and show up in the Saved tab on the right side of the tab strip. The list persists across sessions in ~/.config/hntui/saved.json as a small JSON file. (Config from the app's hackernuis days is migrated automatically on first run.) Press s again to remove a post from the list.

S jumps straight to the Saved list from anywhere.

Development

git clone https://github.com/ahmd-sh/hntui.git
cd hntui
bun install
bun dev    # hot reload

Data comes from the public Hacker News Firebase API.

Releases

Pushing a v* tag triggers two workflows:

To release a new version:

npm version patch   # or minor / major
git push --follow-tags

Acknowledgments

License

MIT, Copyright (c) 2026 Ahmed Shaikh.

hntui (ahmd-sh/hntui)

reader
Searching Database…

148 ·GitHub
Hntui
What is this?hntui is a terminal UI for browsing Hacker News: all six feeds (Top, New, Best, Ask, Show, Jobs), with comment navigation, saved posts, vim and mouse support, themes, and a Knight Rider-style loading animation.
Is this a standalone app or a library I'd import?It's a standalone terminal application you run directly, built on the OpenTUI native TUI framework rather than being a library for other projects.
How do I install and run it?Easiest is the standalone binary installer, which puts a self-contained binary at ~/.local/bin, or you can grab a binary for your platform from the releases page. Alternatively, with Bun installed you can run it once without installing, or install it as a package.
Do I need Bun installed to use this?Prebuilt binaries have no dependencies at all. You only need Bun 1.2 or newer if you install via npm/Bun or want to hack on the code.
Does it work on Intel Macs or Windows?Prebuilt binaries only cover macOS Apple Silicon and Linux (x64, arm64); on an Intel Mac you need the Bun install path instead. Windows support comes from OpenTUI but the author hasn't tested it yet.
Which terminals and platforms does it support?Any modern terminal with truecolor, mouse support, and UTF-8 works; the author tested it in Ghostty on macOS, and Linux/Windows support comes from the OpenTUI framework.
Where is my saved data stored?Saved posts persist locally in a small JSON file at ~/.config/hntui/saved.json; nothing is sent anywhere beyond fetching HN data from its public API.
How do I save a post for later?Press s on any story to save it (press again to unsave). Saved posts get a small star and appear in the Saved tab, reachable instantly with S.
Can I use the mouse instead of vim keys?Yes, almost everything works with the mouse: click tabs to switch feeds, click rows to select or open stories, right-click for a context menu, and scroll with the wheel.
How do I select and copy text from the terminal?Because hntui captures mouse events, normal drag-selection is intercepted. On macOS hold Option while dragging then Cmd-C; on Linux hold Shift while dragging then Ctrl-Shift-C.
Where does the Hacker News data come from?Data comes from the public Hacker News Firebase API.
What are similar projects?Horizon, opentui, Inquirer.js, tokscale, tincan-cli, gh-dash, wuzz, dsh-TUI
Which topics is it in?news-aggregator, reader, terminal-ui, news, vim, bun, github-actions, tui, cli-tool, command-line, command-line-tool, npm
Creator
ahmd-sh
Size
1.3 MB
Stars
148
Updated
CommitOct 01Releasev0.5.1Oct 01
Age
4mo
Commits · 90 Days