hn-cli

Agent-friendly CLI for Hacker News via the Algolia API. Data goes to stdout (parseable), hints/progress to stderr. No authentication required.

• Fast — direct Algolia API, no scraping or HTML parsing
• Agent-friendly — --json on every command, structured exit codes, stderr-only progress
• Zero config — no API keys, no auth, no rate limits
• Single binary — install via Homebrew, Scoop, or go install

$ hn search "local LLMs" -n 3
5632 results:
1. [2127pts 963c] Running Local LLMs Is a Waste of Time  @dang  3mo ago
   https://example.com/local-llms
   HN: https://news.ycombinator.com/item?id=43163011
2. [891pts 412c] Ollama: Run LLMs Locally  @thunderbong  8mo ago
   https://ollama.ai
   HN: https://news.ycombinator.com/item?id=42591244
3. [654pts 287c] How I Run LLMs on a Raspberry Pi  @tosh  1y ago
   https://example.com/rpi-llms
   HN: https://news.ycombinator.com/item?id=41023547

$ hn front -n 3
1. [312pts 142c] Show HN: I built a CLI for everything  @pg  2h ago
   https://example.com/cli
2. [198pts  87c] Why SQLite Is So Great for the Edge  @dang  4h ago
   https://example.com/sqlite
3. [145pts  53c] The death of microservices  @mfiguiere  6h ago
   https://example.com/microservices

$ hn read 43163011 --json | jq '.comments | length'
963

Run hn --help for the full command tree.

Install

Homebrew (macOS / Linux):

brew install voska/tap/hn

Scoop (Windows):

scoop bucket add voska https://github.com/voska/scoop-bucket
scoop install hn

Go:

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

Binary: download from Releases.

Quick Start

# Search stories
hn search "distributed systems" --min-points 100

# Search comments
hn search "Go vs Rust" --comments

# Recent stories sorted by date
hn search "WASM" --sort date --after 2026-01-01

# Current front page
hn front

# Read a story with comments (3 levels deep)
hn read 43163011

# Read with all comments expanded
hn read 43163011 --expand

# User profile
hn user pg

# API health check
hn status

Agent Skill

Install as a Claude Code skill for AI-assisted HN research:

npx skills add -g voska/hn-cli

API

Uses the HN Algolia API -- free, public, no authentication or API keys required.

Output Modes

Commands

All commands support --json.

Exit Codes

Development

make build    # Build to bin/hn
make test     # Run tests with race detector
make lint     # Run linter
make fmt      # Format code

License

MIT