🖥️ hntui: Hacker News for the Terminal

Browse Hacker News like a true hacker. A sophisticated and polished Terminal User Interface (TUI) designed for consuming one of the web's premier technical news aggregators.

🚀 Getting Started

Installation Options

Depending on your environment, choose one of the following methods:

Standalone Binary (Recommended) The fastest way to get running. This installs a self-contained executable to ~/.local/bin.
```
curl -fsSL https://raw.githubusercontent.com/ahmd-sh/hntui/main/install.sh | sh
```
Direct Download Visit the Releases Page to grab binaries for:
- Linux (x64 and arm64)
- macOS (Apple Silicon)
- Note: Intel Mac users should use the Bun method below.

Via Bun Requires Bun 1.2+.

# Install globally
bun add -g @ahmd-sh/hntui

# Or execute without installing
bunx @ahmd-sh/hntui

System Requirements

To ensure the UI renders correctly, your terminal must support:

Truecolor
Mouse Input
UTF-8 Encoding

Note: While OpenTUI supports Windows and Linux, the author has not yet fully verified all Windows environments.

🛠️ Functionality & Usage

hntui allows you to navigate all six primary HN feeds: Top, New, Best, Ask, Show, and Jobs. It even features a nostalgic Knight Rider style scanner for loading states (⁠◕⁠ᴗ⁠◕⁠ ).

⌨️ Keybindings Reference

📋 Story List

Key	Action
`j` / `↓` , `k` / `↑`	Navigate cursor
`gg` , `G`	Jump to top or bottom
`Ctrl-D` / `Ctrl-U` / `PgDn` / `PgUp`	Half-page scroll
`c` / `Enter`	Open story & comments
`h` / `←` , `l` / `→`	Switch tabs
`Tab` / `Shift-Tab`	Cycle through tabs
`1` $\rightarrow$ `6`	Jump to specific category
`S`	Open Saved list
`s`	Toggle save status of post
`o`	Open URL in default browser
`r`	Refresh feed
`t`	Switch theme
`q` / `Ctrl-C`	Exit application

💬 Story Details (Comments)

Key	Action
`j` / `↓` , `k` / `↑`	Move comment cursor
`gg` , `G`	Jump to first/last comment
`Ctrl-D` / `Ctrl-U` / `PgDn` / `PgUp`	Half-page scroll
`Space`	Expand/Collapse comment thread
`Enter`	Open links popup
`s`	Save/Unsave story
`o`	Open story URL
`Esc` / `Backspace` / `h`	Return to list
`t`	Switch theme
`q`	Exit

🔗 Links Popup & Context Menu

Context	Key	Action
Links	`j`, `k`, `↑`, `↓`	Navigate links
Links	`gg`, `G`	First/Last link
Links	`o`, `Enter`	Open link
Links	`Esc`, `Backspace`	Close popup
Menu	`j`, `k`, `↑`, `↓`	Navigate menu
Menu	`Enter`	Activate option
Menu	`Esc`, `Backspace`	Close menu

🖱️ Mouse Integration

Most keyboard actions are mirrored via the mouse:

Refresh/Exit: Click the Y tile.
Context Menu: Right-click any story to Save, Open URL, or Open Comments.
Threading: Click a comment header to toggle its subtree.
External Links: Click the story URL in the header to launch your browser.

⚠️ Selecting Text

Since hntui captures mouse events, standard click-and-drag is disabled. Use these modifiers to bypass:

macOS (iTerm2, Ghostty, etc.): Hold Option $\rightarrow$ Drag $\rightarrow$ Cmd-C.
Linux (Kitty, Alacritty, etc.): Hold Shift $\rightarrow$ Drag $\rightarrow$ Ctrl-Shift-C.

🎨 Aesthetics & Persistence

The Light Theme is a tribute to the original news.ycombinator.com aesthetic:

$\text{Background} = \text{White}$
$\text{Topbar} = \text{Orange}$
$\text{Highlight} = \text{Beige}$
$\text{Bylines} = \text{Grey}$

Saved Posts:

Marked with a $\star$ and stored in the Saved tab.
Data persists in ~/.config/hntui/saved.json.
~~hackernuis~~ $\rightarrow$ Old configurations are automatically migrated to the new format.

⚙️ Development & Pipeline

Local Setup

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

The application fetches data via the Hacker News Firebase API.

Release Workflow

The project uses a sophisticated CI/CD pipeline triggered by v* tags:

To trigger a new release: npm version patch (or minor/major) $\rightarrow$ git push --follow-tags.

Maintenance

Binary Users: Run hntui update to check for and install the latest version.
Bun Users: Re-run bun add -g @ahmd-sh/hntui.

🙏 Credits

OpenTUI: Developed by Anomaly.
Knight Rider Animation: Adapted from examples/knight-rider/utils.ts under the MIT License.

License: MIT