hn-cli

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:

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

Claude Code Plugin

This repo also ships hn, a Claude Code plugin that brings Hacker News to Claude.

/plugin marketplace add heartleo/hn-cli
/plugin install hn@hn-cli

Then just ask: what's on HN today. Ask in any language and the digest comes back in that language. See the plugin README for details.

The digest is also published daily at hndigest.heartleo.dev.

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. It is also listed in the awesome-dsh-plugin community registry. 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.

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

Comment Thread

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

Example .env:

HN_TRANSLATE_API_KEY=sk-...
HN_TRANSLATE_LANG=Chinese

Theme

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!