HackerNews, from the terminal.
Browse stories. Submit posts. Comment and upvote. Power AI agents.
Getting Started • CLI • TUI • MCP Server • API • Contributing
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 | 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. |
- Node.js 18+ (LTS recommended)
- A HackerNews account (for write operations; reading works without auth)
npm install -g @postcli/hackernewspostcli-hn auth loginEnter your HN username and password. Alternatively, paste a cookie manually with auth setup. See the auth guide.
postcli-hn auth test# Authenticated as youruserpostcli-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 TUIpostcli-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 storiespostcli-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 commentEvery 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 | 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 |
postcli-hn tui| 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 |
| 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 |
Connect HackerNews to Claude, GPT, or any AI agent via the Model Context Protocol.
postcli-hn --mcpAdd to .claude/settings.json:
{
"mcpServers": {
"hackernews": {
"command": "postcli-hn",
"args": ["--mcp"]
}
}
}Add to claude_desktop_config.json:
{
"mcpServers": {
"hackernews": {
"command": "postcli-hn",
"args": ["--mcp"]
}
}
}| 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 |
Use the client in your own Node.js projects:
import{HackerNewsClient}from'@postcli/hackernews/client';constclient=newHackerNewsClient({cookie: process.env.HN_COOKIE});// Readconststories=awaitclient.listStories({type: 'top',limit: 5});conststory=awaitclient.getStory(42069420);constcomments=awaitclient.listComments(42069420,{limit: 10});constuser=awaitclient.getUser('pg');constresults=awaitclient.search('rust async',{limit: 10});// Write (requires cookie)awaitclient.submit({title: 'My Post',url: 'https://example.com'});awaitclient.comment(42069420,'Great post!');awaitclient.upvote(42069420);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
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).
Contributions are welcome.
git clone https://github.com/postcli/hackernews.git
cd hackernews
npm install
npm run build
npm test# Run CLI in dev mode
npm run cli -- stories list
# Run MCP with inspector
npm run dev:mcp
# Run tests
npm test- Open an issue first to discuss the change
- Fork the repo and create a branch from
main - Write tests for new functionality
- Run
npm testandnpm run buildbefore submitting - Keep PRs focused on a single change
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.