HN CLI

A terminal UI for browsing Hacker News, modeled after the HN reader on my personal website.

Installation

``bash


Run directly (no install needed)

bunx @brianlovin/hn-cli

or with npx

npx @brianlovin/hn-cli

Or install globally

bun install -g @brianlovin/hn-cli
hn

Or with npm

npm install -g @brianlovin/hn-cli
hn
`

$3

`bash
git clone https://github.com/brianlovin/hn-cli.git
cd hn-cli
bun install
bun run start
`

Usage

$3

| Key | Action |
| --------- | ---------------------------- |
| j / k | Navigate between stories |
| space | Jump to next root comment |
| o | Open story URL in browser |
| r | Refresh stories |
| c | Chat with AI about the story |
| t | AI-generated tl;dr |
| s | Open settings |

$3

- Click on stories in the sidebar to select them
- Click story title/URL to open in browser

$3

#### TL;DR Summaries

Press t on any story to generate an AI-powered summary. The AI reads the article and all comments, then provides:

- A concise summary of the article
- Key takeaways from the discussion

Summaries are cached locally, so you can revisit them without regenerating.

#### Chat

Press c to start a conversation with an AI about the story. The AI has full context of the article and all comments, so you can ask follow-up questions, get clarification, or dive deeper into specific topics.

#### Bring Your Own API Key

The chat feature requires an API key from either Anthropic or OpenAI. On first use, you'll be prompted to choose a provider and enter your key.

Option 1: Environment variables

`bash


For Anthropic

export ANTHROPIC_API_KEY=sk-ant-...

For OpenAI

export OPENAI_API_KEY=sk-...
`

Option 2: In-app setup

Press s to open settings and you'll be guided through the setup. Your key is stored locally at ~/.config/hn-cli/config.json.

Settings

Press s at any time to open the settings panel.

$3

- Switch between Anthropic and OpenAI
- Change the model (Claude Opus/Sonnet/Haiku, GPT-5 Nano/GPT-5 Mini/GPT-5.2)
- Add or clear API keys

$3

These settings control which stories appear in your feed:

| Setting | Default | Description |
| ------------ | ------- | --------------------------------------- |
| Max Stories | 24 | Maximum number of stories to display |
| Time Window | 24h | Only show stories from the last N hours |
| Min Points | 50 | Minimum points required |
| Min Comments | 20 | Minimum comments required |

$3

| Setting | Default | Description |
| -------------- | ------- | ------------------------------------------- |
| Root Comments | 12 | Maximum root-level comments shown per story |
| Child Comments | 8 | Maximum replies shown per comment |
| Nesting Depth | 3 | Maximum levels of nested replies |

Settings are stored locally at ~/.config/hn-cli/config.json.

Design decisions

The default settings match my HN reader on my personal website. I made these choices so that it's easier for me to keep up with the most interesting stories throughout the day without getting sucked too deep into long comment threads or the flood of new submissions.

---

Development

$3

`bash
bun install # Install dependencies
bun run start # Run the app
bun run dev # Run with hot reload
bun run dev:update # Run with simulated update notification
`

$3

To test the update notification UI without publishing a new version:

`bash
bun run dev:update
`

You can also customize the simulated versions:

`bash
HN_SIMULATE_VERSION=0.2.0 HN_SIMULATE_LATEST=0.5.0 bun run start
`

$3

`bash
bun run test # Run tests
bun run typecheck # Check types
`

$3

`bash
bun run debug # Test long comment wrapping
bun run debug story-list # Test story list view
bun run debug highlighted-comment # Test comment highlighting
`

$3

- src/index.ts - Entry point
- src/app.ts - Main app class with UI and keyboard handling
- src/api.ts - API client for fetching from HNPWA API
- src/config.ts - Configuration and API key management
- src/settings.ts - Configurable filter settings with validation
- src/types.ts - TypeScript types for HN data structures
- src/test/ - Test suite

Telemetry

This CLI collects anonymous usage data to help understand how people use it and what features to improve. No personal information or content is ever collected.

$3

- App launches (with version number)
- Feature usage counts (TLDR, chat, refresh)
- Navigation patterns (stories selected, comments viewed)
- Keyboard shortcut usage

$3

- Story content, titles, or URLs
- Chat messages or AI responses
- API keys or credentials
- IP addresses or location data

$3

Option 1: Settings menu

Press s to open settings, then toggle "Telemetry" off.

Option 2: Launch flag

`bash
hn --disable-telemetry
`

This permanently disables telemetry. Your preference is stored locally at ~/.config/hn-cli/config.json`.

Credits

Built with OpenTUI