@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