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 —
--jsonon every command, structured exit codes, stderr-only progress - Zero config — no API keys, no auth
- 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 2026-01-14
https://example.com/local-llms
HN: https://news.ycombinator.com/item?id=43163011
2. [891pts 412c] Ollama: Run LLMs Locally @thunderbong 2025-08-02
https://ollama.ai
HN: https://news.ycombinator.com/item?id=42591244
3. [654pts 287c] How I Run LLMs on a Raspberry Pi @tosh 2025-04-11
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 '.children | length'
412Run hn --help for the full command tree.
Homebrew (macOS / Linux):
brew install voska/tap/hnScoop (Windows):
scoop bucket add voska https://github.com/voska/scoop-bucket
scoop install hnOther install methods
Go:
go install github.com/voska/hn-cli/cmd/hn@latestBinary: download from Releases.
# 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
# Search one kind of post, or one author
hn search "database" --tag show_hn
hn search "scheduling" --by dang --comments
# Browse with filters alone, inside a date range
hn search --tag ask_hn --min-points 200 --after 2026-01-01 --before 2026-02-01
# Has this site or URL been discussed?
hn search "github.com/voska" --url
# Next page of results
hn search "WASM" --page 1
# Current front page, in site rank order
hn front
# Other feeds: new, best, ask, show, job
hn front --feed show -n 10
# Read a story with its top comments
hn read 43163011
# Open a collapsed thread by comment ID
hn read 43163150
# Fewer comments, shorter
hn read 43163011 -n 5 --replies 1 --max-chars 300
# Read every comment in full
hn read 43163011 --expand
# User profile
hn user pg
# API health check
hn statusInstall as a Claude Code skill for AI-assisted HN research:
npx skills add -g voska/hn-cliUses the HN Algolia API for search and threads, and the official Firebase API for site ranking and user profiles. Both are free and public, with no authentication or API keys required.
| Flag | Description |
|---|---|
| (default) | Compact plaintext to stdout |
--json |
Structured JSON to stdout |
| Command | Alias | Description |
|---|---|---|
search [query] |
s |
Search stories or comments |
front |
f |
Stories in site rank order, from any feed |
read <id> |
r |
Story or comment with its top comments |
user <username> |
u |
User profile and karma |
status |
API health check with latency | |
version |
Version, commit, build date |
All commands support --json.
| 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 | Network failure, rate limit or server error, safe to retry |
make build # Build to bin/hn
make test # Run tests with race detector
make lint # Run linter
make fmt # Format codeMIT