hn-query

HN CLI utility.

Tech Stack

• Python 3.12+ with src/ layout
• uv — package manager
• Typer — CLI framework
• pytest — testing
• Ruff — linting & formatting
• pre-commit — git hooks

Getting Started

# Install dependencies
uv sync

# Run the CLI
uv run hn-query --help
uv run hn-query top
uv run hn-query top --json
uv run hn-query top --csv
uv run hn-query top --format human --output top.txt

# Run tests
uv run pytest

# Lint & format
uv run ruff check .
uv run ruff format .

# Set up git hooks
uv run pre-commit install

Working with AI Agents

This project includes an AGENTS.md file with instructions for AI coding agents.

Project Structure

See ARCHITECTURE.md for details on how the project is organized and how to grow it as your application evolves.

Commands

• hn-query top: fetch top Hacker News stories (implemented)
• hn-query new: fetch new Hacker News stories (implemented)
• hn-query best: fetch best Hacker News stories (implemented)
• hn-query item <id>: fetch one Hacker News item by ID (implemented)

top options

• --limit, -n: number of stories, default 10, max 100
• --format: human, json, or csv
• --json: shortcut for --format json
• --csv: shortcut for --format csv
• --output, -o: write output to file
• --timeout: HTTP timeout seconds

Python API (Scripts and Notebooks)

hn-query exposes a stable import API in hn_query.api and top-level re-exports in hn_query.

Script example

from hn_query import get_top, stories_to_json

stories = get_top(limit=5, timeout=10.0)
print(stories_to_json(stories))

Notebook example

from hn_query.api import get_item, item_to_json

item = get_item(8863)
item_to_json(item)

Stable exports

Top-level supported imports:

• HNStory
• HNApiError
• get_top, get_new, get_best, get_item
• stories_to_json, stories_to_csv
• item_to_json, item_to_csv