hn

Install

hn is a single static binary on Linux and a universal binary on macOS.

Linux

Native packages install hn, its man page, license, and README. The only runtime dependency is ca-certificates.

Debian / Ubuntu

VERSION=0.4.2
curl -LO "https://github.com/kaushalvivek/hn-cli/releases/download/v${VERSION}/hn_${VERSION}_amd64.deb"
sudo apt install "./hn_${VERSION}_amd64.deb"

Use arm64 instead of amd64 on ARM servers.

Fedora / RHEL / openSUSE

VERSION=0.4.2
curl -LO "https://github.com/kaushalvivek/hn-cli/releases/download/v${VERSION}/hn-${VERSION}-1.x86_64.rpm"
sudo dnf install "./hn-${VERSION}-1.x86_64.rpm"
# openSUSE: sudo zypper install "./hn-${VERSION}-1.x86_64.rpm"

Use aarch64 instead of x86_64 on ARM servers.

Arch Linux

VERSION=0.4.2
curl -LO "https://github.com/kaushalvivek/hn-cli/releases/download/v${VERSION}/hn-${VERSION}-1-x86_64.pkg.tar.zst"
sudo pacman -U "./hn-${VERSION}-1-x86_64.pkg.tar.zst"

Use aarch64 instead of x86_64 on ARM servers.

Alpine Linux

VERSION=0.4.2
curl -LO "https://github.com/kaushalvivek/hn-cli/releases/download/v${VERSION}/hn_${VERSION}_x86_64.apk"
sudo apk add --allow-untrusted "./hn_${VERSION}_x86_64.apk"

Use aarch64 instead of x86_64 on ARM servers.

Any Linux distribution, no root

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

Detects x86_64 or aarch64 and installs to ~/.local/bin. Override with HN_INSTALL_DIR and pin a release with HN_VERSION:

HN_VERSION=0.4.2 HN_INSTALL_DIR="$HOME/bin" sh install.sh

All Linux release binaries are statically linked against musl and run across distributions. They need CA certificates for HTTPS; install ca-certificates on minimal systems.

macOS

Homebrew is the simplest option:

brew install kaushalvivek/tap/hn

Homebrew 7 may ask you to trust a third-party tap on first use. If prompted, run brew trust kaushalvivek/tap.

Or use the same install script as Linux:

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

Direct download

Platform	Archive	Native packages
macOS Apple Silicon + Intel	hn-macos-universal.tar.gz	—
Linux x86_64	hn-linux-x86_64.tar.gz	.deb, .rpm, .pkg.tar.zst, .apk
Linux aarch64	hn-linux-aarch64.tar.gz	.deb, .rpm, .pkg.tar.zst, .apk

VERSION=0.4.2
ASSET=hn-linux-x86_64.tar.gz   # or hn-macos-universal.tar.gz
curl -LO "https://github.com/kaushalvivek/hn-cli/releases/download/v${VERSION}/${ASSET}"
curl -LO "https://github.com/kaushalvivek/hn-cli/releases/download/v${VERSION}/checksums.txt"
# Linux:
sha256sum -c checksums.txt --ignore-missing
# macOS:
# grep " ${ASSET}$" checksums.txt | shasum -a 256 -c -
tar -xzf "$ASSET"
mkdir -p ~/.local/bin
install -m 755 hn ~/.local/bin/hn

Cargo

cargo install --locked --git https://github.com/kaushalvivek/hn-cli

Requires Rust 1.88+.

From source

git clone https://github.com/kaushalvivek/hn-cli.git
cd hn-cli
make install

make install builds with Cargo and installs to /usr/local/bin by default. Use PREFIX=~/.local make install for a user-local install.

Updating

• Linux packages: download and install the new package with the same command.
• Install script: re-run it.
• Homebrew: brew upgrade hn.

Uninstalling

sudo apt remove hn        # Debian / Ubuntu
sudo dnf remove hn        # Fedora / RHEL
sudo pacman -Rns hn       # Arch
sudo apk del hn           # Alpine
rm -f ~/.local/bin/hn     # install-script installs
brew uninstall hn         # Homebrew
rm -rf ~/.config/hn       # optional: remove session and drafts

Quick start

hn                          # open the interactive browser
hn browse --feed new        # start on a specific feed
hn front --limit 10         # line-oriented output
hn thread 8863              # story + comment tree
hn search "rust async" --sort date
hn login                    # authenticated actions
hn whoami

Run hn --help or hn <command> --help for the full surface.

Agents

Every read command supports --json (or HN_JSON=1). The CLI is designed to be discovered without reading the source:

hn capabilities                       # machine-readable command map, schemas, env vars
hn front --limit 5 --json             # structured feed
hn item 8863 --json
hn thread 8863 --json
hn search "sqlite" --type story --limit 10 --json
hn user pg --json

hn front --limit 10 --json \
  | jq -r '.entries[] | "\(.score)\t\(.title)\t\(.id)"'

Errors are JSON on stderr with --json:

{"ok": false, "error": {"code": "rate_limited", "message": "Hacker News rate-limited the request"}}

Exit code is 0 on success and 1 on error. Read commands make no writes and need no account. Authenticated writes are never implicit.

Agent guides: AGENTS.md and llms.txt.

The interactive browser

hn opens a full-screen terminal app with a feed sidebar, story list, detail pane, and threaded comments.

• Keyboard-first, with mouse scrolling
• Threaded comments with collapse/expand
• Search, command palette, help overlay, login modal, and toasts
• Inline composer with context, drafts, retry-safe errors, and immediate in-thread replies
• Vote, favorite, hide, flag, comment, edit, delete, and submit without leaving the terminal
• Feed loading from HN's HTML, with Firebase and Algolia adapters underneath

This is the beginning of the README. Read the rest at the original. Read the full README ↗