A command-line interface for fetching and displaying top stories from Hacker News.

hns is a simple, fast Rust command-line tool that pulls top stories from the official Hacker News API and displays them in a clean, readable format. The tool shows story titles, authors, timestamps, text content, and URLs in a structured way, making it easy to browse Hacker News without leaving your terminal.

• Fetch and display the top stories from Hacker News
• Configurable number of stories to display
• Clean formatting with proper handling of HTML content
• Special handling for "Show HN" posts
• Proper decoding of HTML entities
• AI-powered URL summarization using Ollama's gemma3:4b model

% hns --summarize

Ensure you have Rust and Cargo installed. Then:

# Clone the repository
git clone https://github.com/yourusername/hns.git
cd hns

# Build and install
cargo install --path .

To use the --summarize feature, you need to have Ollama running with the gemma3:4b model installed:

1. Install Ollama following the official instructions
2. Pull the gemma3:4b model:

ollama pull gemma3:4b

3. Ensure Ollama is running before using the --summarize flag

# Start Ollama (keep running in a separate terminal)
ollama serve

Run the tool with default settings (shows 5 top stories):

hns

Display the top 10 stories:

hns -m 10

Display the maximum number of stories:

hns --max-stories 25

Display stories with URL summaries:

hns --summarize

Display 10 stories with URL summaries:

hns -m 10 --summarize

For each story, the tool displays:

1. A separator line
2. Timestamp, author, and story ID
3. Story title
4. For "Show HN" posts: URL followed by text content (if available)
5. For regular posts: Text content (if available) or URL

• Rust 1.70.0 or higher
• Cargo

The project includes several files to help with development:

• Makefile - Common development tasks (run make help for details)
• CHANGELOG.md - Track changes between versions
• CONTRIBUTING.md - Guidelines for contributors

• clap - Command-line argument parsing
• reqwest - HTTP client for API requests (and Ollama API calls)
• tokio - Asynchronous runtime
• serde - JSON serialization/deserialization
• serde_json - JSON serialization/deserialization for Ollama API
• chrono - Timestamp formatting
• scraper - HTML parsing
• ego-tree - Tree data structure for HTML parsing
• html2text - HTML to text conversion for URL content

# Clone the repository
git clone https://github.com/yourusername/hns.git
cd hns

# Build in debug mode
cargo build

# Build in release mode
cargo build --release

cargo test

This project uses GitHub Actions for continuous integration and deployment. The workflow automatically:

1. Tests the codebase
2. Builds binaries for multiple platforms (Linux, macOS Intel/ARM, Windows)
3. Creates GitHub releases with packaged artifacts when tags are pushed
4. Publishes to crates.io when a new version is tagged

To create a new release:

# 1. Update the version in Cargo.toml
# 2. Commit the changes
git add Cargo.toml
git commit -m "Bump version to x.y.z"

# 3. Tag the commit
git tag -a vx.y.z -m "Release version x.y.z"

# 4. Push to GitHub with tags
git push && git push --tags

Note: To enable publishing to crates.io, you must set the CRATES_IO_TOKEN secret in your GitHub repository settings.

This tool uses the official Hacker News API:

• https://github.com/HackerNews/API

This project is licensed under the BSD 3-Clause License - see the LICENSE.md file for details.