hn

A terminal client for Hacker News.

Features

• 📰 Story browser — Top, New, Best, Ask HN, Show HN with tab switching
• 💬 Comment threads — navigate with j/k, fold/unfold, lazy-load reply trees
• 🌐 Translation — translate a title with t, all visible titles with T, or a selected comment
• 🔄 Soft refresh — refresh stories or comments without restarting
• 🎨 Themes — hn, mocha, dracula, tokyo, nord, gruvbox
• ⚡ Progressive loading — visible range loads first, more fetched as you scroll

Install

Homebrew (macOS / Linux):

$ brew install heartleo/tap/hn

winget (Windows):

$ winget install heartleo.hn

curl (macOS / Linux):

$ curl -fsSL https://raw.githubusercontent.com/heartleo/hn-cli/main/install.sh | sh

No sudo needed — the binary is installed under your home directory. The install directory is picked from the first of these that is set:

Source	Value
HN_INSTALL_DIR	used as-is
XDG_BIN_HOME	used as-is
XDG_DATA_HOME	$XDG_DATA_HOME/../bin
(default)	$HOME/.local/bin

To install somewhere else:

$ curl -fsSL https://raw.githubusercontent.com/heartleo/hn-cli/main/install.sh | HN_INSTALL_DIR=~/bin sh

The script warns if the install directory is not on your $PATH, and prints the export PATH=... line to add to your shell profile.

The script never calls sudo. To install system-wide, run it as root yourself:

$ curl -fsSL https://raw.githubusercontent.com/heartleo/hn-cli/main/install.sh -o install.sh
$ sudo env HN_INSTALL_DIR=/usr/local/bin sh install.sh

Prebuilt binaries — download from GitHub Releases

Go install (requires Go 1.25+):

$ go install github.com/heartleo/hn-cli/cmd/hn@latest

Build from source:

$ git clone https://github.com/heartleo/hn-cli
$ cd hn
$ go build -o hn ./cmd/hn

DeepSeek Harness Plugin

For DeepSeek Harness there is hacker-news, a plain-ESM plugin that reads the public Hacker News APIs directly. It needs neither an HN API key nor a local terminal client.

Install from npm

The published package is dsh-hacker-news. DSH profiles are pnpm workspace roots, so keep the -w flag:

dsh plugin --profile <name> add -w dsh-hacker-news

If your npm mirror has not indexed the latest release, run the installation against the public registry:

$env:npm_config_registry = 'https://registry.npmjs.org/'
dsh plugin --profile <name> add -w dsh-hacker-news

Start or restart the same profile, then verify that the composed configuration includes dsh-hacker-news:

dsh --profile <name>
dsh --profile <name> --dump-config

Install from source

This form follows the repository's main branch and is intended for development or trying unreleased changes:

dsh plugin --profile <name> add -w github:heartleo/hn-cli#path:/plugins/hacker-news

After installation, ask naturally, for example: what's popular on HN?, search HN for sqlite, or read HN item 49322107 and summarize the discussion.

Tool	What it does
hn_stories	Ranked feeds — top / new / best / ask / show / job
hn_item	An item plus its reply tree in reading order
hn_search	Algolia search, by relevance or date
hn_user	Karma, account age, bio, submission count

See the plugin README for configuration.

Quick Start

$ hn        # top stories
$ hn new    # new stories
$ hn best   # best stories

Commands

Browse

Opens the interactive TUI. Defaults to Top stories; switch tabs with ←/→.

$ hn        # top stories (default)
$ hn top
$ hn new
$ hn best
$ hn ask
$ hn show

Comments

Press Enter on any story to open its comment thread.

• navigate with ↑/↓ or k/j
• press Enter to expand or collapse a reply tree
• press Space to fold or unfold the selected comment
• press C / E to fold or unfold all
• press r to jump to the root comment
• press R to soft refresh
• press Esc to go back

Translation

Translates via any OpenAI-compatible chat completions API. See Configuration to set up an API key.

t   translate selected story title (toggle cached translation)
T   translate all visible titles in one batch request
t   translate selected comment (in comment view)

theme

$ hn theme          # show current
$ hn theme nord     # set globally

Available: hn · mocha · dracula · tokyo · nord · gruvbox

Keys

Story List

Key	Action
Enter	Open comment thread
o	Open in browser
t	Translate selected title
T	Translate all visible titles
← / →	Switch tab
r	Refresh
?	Toggle help
q / Ctrl+C	Quit

Comment Thread

Key	Action
j / ↓	Next comment
k / ↑	Previous comment
gg	Back to top
r	Jump to root comment
Enter	Expand / collapse replies
Space	Fold / unfold selected comment
C / E	Fold / unfold all
t	Translate selected comment
R	Soft refresh
o	Open story in browser
Esc	Back to list
?	Toggle help
Q / Ctrl+C	Quit

Configuration

hn reads ~/.config/hn/config.json. A .env file in the working directory is also loaded automatically; environment variables take precedence over the config file.

Translation

Variable	Default	Description
HN_TRANSLATE_API_URL	https://api.openai.com/v1	API base URL
HN_TRANSLATE_API_KEY	—	API key
HN_TRANSLATE_MODEL	gpt-4o-mini	Model name
HN_TRANSLATE_LANG	Chinese	Target language

Example .env:

HN_TRANSLATE_API_KEY=sk-...
HN_TRANSLATE_LANG=Chinese

Theme

Variable	Description
HN_THEME	Override theme without editing config

Example ~/.config/hn/config.json:

{
  "theme": "mocha",
  "translate": {
    "api_url": "https://api.openai.com/v1",
    "api_key": "sk-...",
    "model": "gpt-4o-mini",
    "language": "Chinese"
  }
}

Contributing

Issues, bug reports, feature suggestions, and general feedback are very welcome:

• 🐛 Report a bug
• 💡 Suggest a feature

[!NOTE] This project is maintained in my spare time, and I currently do not have enough capacity to properly review external pull requests. See CONTRIBUTING.md for details. Thank you for your understanding!