HackerNews CLI

A small TypeScript CLI for browsing Hacker News from the terminal. Designed for both humans and coding agents.

Installation

Requirements: Node.js 18+

npm install -g hckrnews-cli

Then run:

hn --help

Commands

hn — Interactive TUI

Running hn with no subcommand launches a full-screen terminal UI. Navigate with ↑↓ or jk, open stories with enter, open in browser with o, search with /, and go back with esc.

Story Lists

hn top                    # top stories
hn new                    # newest stories
hn best                   # best stories
hn ask                    # Ask HN posts
hn show                   # Show HN posts
hn jobs                   # job postings

Options (all story list commands):

| Flag | Description | Default | | ----------------- | ------------------------- | ------- | | -l, --limit <n> | Number of stories to show | 30 | | --json | Output as JSON | |

hn top --limit 10
hn best --limit 50 --json

hn item <id> — Story or comment detail

hn item 8863                          # show story details
hn item 8863 --comments               # include top-level comments
hn item 8863 --comments --depth 3     # fetch 3 levels deep
hn item 8863 --comments --limit 20    # show up to 20 top-level comments
hn item 8863 --json                   # output as JSON

| Flag | Description | Default | | ----------------- | ------------------------------------------ | ------- | | -c, --comments | Include comments | | | -d, --depth <n> | Comment tree depth (requires --comments) | 2 | | -l, --limit <n> | Max top-level comments | 10 | | --json | Output as JSON | |

hn comments <id> — Full comment tree

hn comments 8863                    # fetch comment tree
hn comments 8863 --depth 5         # go 5 levels deep
hn comments 8863 --limit 20        # show 20 top-level comments

| Flag | Description | Default | | ----------------- | ----------------------------- | ------- | | -d, --depth <n> | How many levels deep to fetch | 3 | | -l, --limit <n> | Max top-level comments | 10 | | --json | Output as JSON | |

hn user <username> — User profile

hn user pg                         # show profile
hn user pg --submissions 10        # show 10 most recent submissions

| Flag | Description | Default | | ----------------------- | ------------------------------ | ------- | | -s, --submissions <n> | Show N most recent submissions | 0 | | --json | Output as JSON | |

hn search <query> — Search via Algolia

The most powerful command. Supports filtering by type, date, points, author, and more.

hn search "typescript"

All options:

| Flag | Description | Default | | --------------------- | --------------------------------------------------------- | ----------- | | -t, --type <type> | stories, comments, ask, show, front, or all | all | | -s, --sort <sort> | relevance or date | relevance | | -p, --page <n> | Page number (0-indexed) | 0 | | -l, --limit <n> | Results per page (max 50) | 20 | | --after <date> | Only results after date (YYYY-MM-DD or Unix timestamp) | | | --before <date> | Only results before date (YYYY-MM-DD or Unix timestamp) | | | --min-points <n> | Minimum points | | | --min-comments <n> | Minimum number of comments | | | --author <username> | Filter by submitter username | | | --story <id> | Search comments within a specific story | | | --url | Restrict search to URLs only | | | --json | Output as JSON | |

Examples:

Filter to stories only:

hn search "typescript" --type stories

Stories with at least 200 points:

hn search "rust" --type stories --min-points 200

Stories after a date:

hn search "read it later" --type stories --after 2026-01-01

Most recent Ask HN threads:

hn search "hiring" --type ask --sort date

All Show HN posts from 2026:

hn search "" --type show --after 2026-01-01 --sort date

What's on the front page right now (front is a live filter):

hn search "" --type front

Everything a specific user has submitted:

hn search "" --author pg --type stories

Search comments within a specific story:

hn search "usb" --story 8863

Find stories by URL:

hn search "github.com/microsoft/vscode" --url

Exact phrase search:

hn search '"read it later"' --type stories

Exclude a term — stories about Python but not Django:

hn search "python -django" --type stories

Stories between two dates with significant engagement:

hn search "openai" --after 2025-01-01 --before 2026-01-01 --min-points 100 --min-comments 50

Paginate through results:

hn search "machine learning" --type stories --limit 5

hn search "machine learning" --type stories --limit 5 --page 1

Tip: --after and --before accept both YYYY-MM-DD dates and raw Unix timestamps.

Tip: Advanced query syntax is always enabled. Use "quoted phrases" for exact matches and -word to exclude terms.

hn updates — Recently changed items

hn updates
hn updates --limit 20

| Flag | Description | Default | | ----------------- | ------------------------------ | ------- | | -l, --limit <n> | Max items to fetch details for | 10 | | --json | Output as JSON | |

hn maxitem — Current largest item ID

hn maxitem

Contributing

git clone https://github.com/Scarvy/hckrnews-cli && cd hckrnews-cli
npm install
npm run dev -- <command> [options]   # run without building

npm run dev       # run TypeScript directly with tsx (no build step)
npm run build     # compile src/ → dist/
npm run tsc       # type-check only, no output
npm run lint      # type-check + ESLint + Prettier
npm run format    # apply Prettier formatting