GitHub - voska/hn-cli: Agent-friendly Hacker News CLI via the Algolia API

3 min read Original article ↗

hn cli

CI Release Go License: MIT

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 cli demo 

$ 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
Other install methods

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

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

Output Modes

Flag Description
(default) Compact plaintext to stdout
--json Structured JSON to stdout

Commands

Command Alias Description
search <query> s Search stories or comments
front f Current front page stories
read <id> r Story with threaded comments
user <username> u User profile and karma
status API health check with latency
version Version, commit, build date

All commands support --json.

Exit Codes

Code Name Meaning
0 success Operation completed
1 error General error
3 empty No results found
5 not_found Invalid ID or username
8 retryable Transient error, safe to retry

Development

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

License

MIT