Hacker News Terminal Client Documentation

Welcome to the official, detailed documentation for hn-client. A blazing-fast, keyboard-driven Hacker News TUI (Terminal User Interface) built in Go using Bubble Tea.

Installation & Compilation

You can compile and install hn-client directly from source using the Go toolchain.

1. Install Go

Ensure you have Go version 1.21 or higher installed on your machine. Check with:

go version

2. Clone and Compile

Clone the repository and run the build command:

git clone https://github.com/aeon022/hn-client.git
cd hn-client
go build -o hn-client main.go

3. Automated Setup Script

For convenience, you can execute the setup script which builds the binary and links it to your local path:

chmod +x setup.sh
./setup.sh

Configuration File

When you start the application for the first time, a configuration file is automatically created in your home directory at ~/.hn-config.json.

Here is an example of the structure of this file:

{
  "username": "hacker_user",
  "show_dead": false,
  "use_gui_browser": false,
  "cookie": "user_auth_cookie_string",
  "theme": "dracula"
}

Configurable Fields:

• username: Your Hacker News handle, used to check for reply notifications.
• show_dead: Boolean to show/hide dead or flagged stories.
• use_gui_browser: If true, links will bypass terminal browsers and open in your system's GUI browser (Safari, Chrome, Firefox).
• cookie: Saved HN session cookie. Used for submitting stories and replies directly inside the TUI.
• theme: Selected styling layout (orange, dracula, nord, monokai).

Keybindings Reference

The TUI is separated into two main views: the **List View** (stories) and the **Detail View** (story description + comment tree).

1. Navigation & General Keys (Available in all views)

2. Story List View Keys

3. Detail / Comments View Keys

Offline Bookmarks System

The bookmarks system allows you to store stories and their complete comments tree locally for reading on planes, trains, or offline commutes.

How to Bookmark:

1. From the **Story List**, hover over any story and press s. The client will fetch the comments tree in the background and save it.
2. Or, inside the **Detail View**, press s to save the currently loaded story and comments instantly.

Reading Bookmarks:

Press 7 or cycle feeds to the Bookmarks tab. You will see a list of your saved stories sorted by the time they were saved. Pressing Enter opens the comments offline.

Comment Link Extractor

Copypasting URLs out of terminal emulators is often painful. The link extractor solves this completely.

Usage:

1. Inside any story **Detail View**, press u.
2. The TUI will scan the main article text and all comments, extracting any strings matching http:// or https://.
3. An overlay modal will display all extracted links.
4. Use j/k to select a link, and press Enter to open it in your browser.
5. Press Esc or u to close the overlay.

User Profiles Popovers

Quickly look up metadata about Hacker News authors without leaving the terminal view.

Usage:

• Press U (Shift + U) over a selected story or comment.
• The client will fetch the profile information for the item's author from the HN API.
• A popover box displays the **Username**, **Registration Date**, **Karma Score**, and the **About bio** text.
• The bio description is automatically stripped of HTML tags and word-wrapped to fit the overlay container.

New Reply Notifications (🔔)

Stay updated on conversations. If you enter your Hacker News username, hn-client will monitor your recent submissions for replies.

How it works:

1. Configure your username by pressing l and typing your HN handle.
2. At startup and every 60 seconds, a background routine pulls your latest 10 submissions/comments.
3. It checks if those items received new child comments.
4. If new replies are found, a bell notification is shown in the top header: 🔔 (X new, Ctrl+N to clear).
5. Press Ctrl+N to mark all replies as seen, saving them to your local cache at ~/.hn-seen-replies.json.

Vim and Terminal Browser Integration

Writing long responses inside terminal inputs can be restrictive. hn-client offers full external editor support.

1. Quick Replies vs. External Vim Replies:

• Quick Reply (r): Opens a simple text input in the TUI footer. Great for short, one-line responses.
• External Reply (e): Suspends the Bubble Tea TUI session and spawns your system's default text editor (usually Vim or Neovim, configured via your $EDITOR environment variable) with a temporary Markdown file.

2. Creating Submissions (w):

Pressing w in list view spawns a template containing YAML frontmatter:

---
Title: Show HN: My Awesome Go Project
URL: https://github.com/my/project
---
Optional text body here...

Write your title, link, and text, save and quit. The TUI will resume, read the file, and submit it to Hacker News.

CLI Markdown Publisher

In addition to the interactive TUI, hn-client can be executed directly from the CLI to publish drafts or posts saved in Markdown files.

Usage:

hn-client publish post_draft.md

The Markdown file must contain standard YAML frontmatter defining the Title and either a URL (for links) or a text body:

---
Title: Show HN: A fast terminal client in Go
URL: https://github.com/gweiher/hn-client
---
This client is built with Bubble Tea...