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): bash $ brew install heartleo/tap/hn winget (Windows): powershell $ winget install heartleo.hn curl (macOS / Linux): bash $ 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: bash $ 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: bash $ 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+): bash $ go install github.com/heartleo/hn-cli/cmd/hn@latest Build from source: bash $ 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: sh 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: powershell $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: sh 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: sh 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 bash $ hn # top stories $ hn new # new stories $ hn best # best stories ## Commands ### Browse Opens the interactive TUI. Defaults to Top stories; switch tabs with ←/→. bash $ 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 bash $ 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: bash HN_TRANSLATE_API_KEY=sk-... HN_TRANSLATE_LANG=Chinese ### Theme | Variable | Description | | ---------- | ------------------------------------- | | HN_THEME | Override theme without editing config | Example ~/.config/hn/config.json: 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!