@postcli/hackernews

HackerNews, from the terminal.

Browse stories. Submit posts. Comment and upvote. Power AI agents.

Getting Started • CLI • TUI • MCP Server • API • Contributing

Why PostCLI HackerNews?

HackerNews has no official API for write operations and the Firebase API is low-level. PostCLI wraps everything into a fast, local-first toolkit that puts your entire HN workflow in the terminal, in a TUI, or behind an AI agent.

CLI Full command suite for stories, comments, search, submissions, and user profiles. Pipe-friendly --json output.

TUI Interactive terminal UI with tabs for stories, comments, search, and profiles. Keyboard-driven navigation.

MCP Server 14 tools for Claude, GPT, and any MCP-compatible AI agent. Read, write, and engage through natural language.

Getting Started

Prerequisites

• Node.js 18+ (LTS recommended)
• A HackerNews account (for write operations; reading works without auth)

Install

npm install -g @postcli/hackernews

Authenticate

postcli-hn auth login

Enter your HN username and password. Alternatively, paste a cookie manually with auth setup. See the auth guide.

Verify

postcli-hn auth test
# Authenticated as youruser

First commands

postcli-hn stories list                    # top stories
postcli-hn search query "rust async"       # search HN
postcli-hn stories get 42069420            # story details
postcli-hn tui                             # launch the TUI

CLI

Read

postcli-hn stories list                              # top stories (default)
postcli-hn stories list --type ask --limit 10        # Ask HN, top 10
postcli-hn stories list --type show --json           # Show HN as JSON
postcli-hn stories get 42069420                      # full story details
postcli-hn stories past                              # yesterday's top stories
postcli-hn comments list 42069420                    # comments on a story
postcli-hn comments list 42069420 --recursive        # threaded comments
postcli-hn comments get 42069500                     # single comment
postcli-hn user get pg                               # user profile
postcli-hn search query "typescript" --limit 5       # search stories

Write

postcli-hn submit link -t "My Project" -u "https://example.com"   # submit a link
postcli-hn submit text -t "Ask HN: Best CLI tools?" -b "What do you use?"  # text post
postcli-hn comments reply 42069420 "Great post!"                   # reply
postcli-hn stories upvote 42069420                                 # upvote story
postcli-hn comments upvote 42069500                                # upvote comment

JSON Output

Every command supports --json for piping and scripting:

postcli-hn stories list --json | jq '.[0].title'
postcli-hn user get pg --json | jq '.karma'
postcli-hn search query "AI" --json | jq '.[].title'

Command Reference

Command	Description
auth login	Login with username/password
auth setup	Paste cookie manually
auth test	Test authentication status
auth logout	Remove stored credentials
stories list	List stories by type
stories get <id>	Get story details
stories past	Yesterday's top stories
stories upvote <id>	Upvote a story
comments list <story-id>	List comments on a story
comments get <id>	Get a single comment
comments reply <id> <text>	Reply to a story/comment
comments upvote <id>	Upvote a comment
user get <username>	Get user profile
submit link	Submit a link
submit text	Submit a text post
search query <text>	Search stories

Full CLI reference →

Interactive TUI

postcli-hn tui

Tabs

Tab	What it shows
Stories	Browse by type (top, new, best, ask, show, job)
Comments	Recent comments across HN
Search	Search stories by keyword
Profile	User profile lookup

Keybindings

Key	Action
tab	Switch between tabs
1-6	Switch story type
up/down or k/j	Navigate items
enter	Open item detail view
r	Reply (requires auth)
u	Upvote (requires auth)
o	Open in browser
q / esc	Back / quit

TUI guide →

MCP Server

Connect HackerNews to Claude, GPT, or any AI agent via the Model Context Protocol.

Start the server

postcli-hn --mcp

Claude Code

Add to .claude/settings.json:

{
  "mcpServers": {
    "hackernews": {
      "command": "postcli-hn",
      "args": ["--mcp"]
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "hackernews": {
      "command": "postcli-hn",
      "args": ["--mcp"]
    }
  }
}

Available Tools (14)

Tool	Description
test_connection	Test authentication status
list_stories	List stories (top, new, best, ask, show, job)
get_story	Get story by ID
list_comments	List comments on a story
get_comment	Get comment by ID
get_user	Get user profile
search_stories	Search stories via Algolia
list_past_stories	Yesterday's top stories
list_recent_comments	Recent global comments
list_threads	User's comment threads
submit_link	Submit a link
submit_text	Submit a text post
comment	Comment or reply
upvote	Upvote a story or comment

Full MCP reference →

Programmatic API

Use the client in your own Node.js projects:

import { HackerNewsClient } from '@postcli/hackernews/client';

const client = new HackerNewsClient({ cookie: process.env.HN_COOKIE });

// Read
const stories = await client.listStories({ type: 'top', limit: 5 });
const story = await client.getStory(42069420);
const comments = await client.listComments(42069420, { limit: 10 });
const user = await client.getUser('pg');
const results = await client.search('rust async', { limit: 10 });

// Write (requires cookie)
await client.submit({ title: 'My Post', url: 'https://example.com' });
await client.comment(42069420, 'Great post!');
await client.upvote(42069420);

Project Structure

src/
  cli/
    commands/      # auth, stories, comments, user, submit, search
    formatters.ts  # Output formatting (colors, time ago, HTML stripping)
    index.ts       # CLI entry point (commander)
  lib/
    hackernews.ts  # HackerNewsClient (core API wrapper)
    http.ts        # HTTP client with throttling
    models.ts      # Domain models (Story, Comment, User)
    types.ts       # HN API response types
  mcp/
    index.ts       # MCP stdio server
    tools.ts       # 14 tool definitions + handlers
  client.ts        # Client initialization & config
  plugin.ts        # Plugin registration for PostCLI ecosystem
test/
  models.test.ts   # Model constructor and toData() tests
  http.test.ts     # HttpClient construction tests
  mcp-schema.test.ts # MCP tool schema validation
  formatters.test.ts # Formatter function tests
  cli/
    smoke.test.ts  # CLI command existence and --help tests
docs/
  cli.md           # Full CLI command reference
  auth.md          # Authentication guide
  mcp.md           # MCP server documentation
  tui.md           # TUI guide
skills/
  hn-stories.md    # Stories skill
  hn-comments.md   # Comments skill
  hn-search.md     # Search skill
  hn-submit.md     # Submit skill
  hn-profile.md    # Profile skill

Authentication

PostCLI supports two auth methods:

Method	Command	How it works
Login (default)	auth login	Enter username/password, cookie is obtained from HN
Manual paste	auth setup	Paste cookie from browser DevTools

Credentials are stored at ~/.config/postcli/.env with 0600 permissions (owner-only read/write).

Auth setup guide →

Contributing

Contributions are welcome.

Setup

git clone https://github.com/postcli/hackernews.git
cd hackernews
npm install
npm run build
npm test

Development

# Run CLI in dev mode
npm run cli -- stories list

# Run MCP with inspector
npm run dev:mcp

# Run tests
npm test

Guidelines

1. Open an issue first to discuss the change
2. Fork the repo and create a branch from main
3. Write tests for new functionality
4. Run npm test and npm run build before submitting
5. Keep PRs focused on a single change

Disclaimer

This is an unofficial tool, not affiliated with or endorsed by Y Combinator or HackerNews. It uses the public Firebase API for reads and the web interface for writes. Use at your own risk.

License

AGPL-3.0