CLX(1)

📦 version 5.0, in nixpkgs unstable

🌸 NAME 🌸

okay bestie, meet circumflex — this is the clx manual page, and it’s literally giving “Hacker News in your terminal” energy. 💖

✨ SYNOPSIS ✨

clx [OPTION]...

clx COMMAND [ARGS]

💖 DESCRIPTION 💖

circumflex lets you browse Hacker News in your terminal. Visit the comment section or read the article in Reader Mode. no cap, it’s a whole vibe. 🦋

🎀 KEYBINDINGS 🎀

  • Enter — read the comment section. 💬
  • Space — read the article in Reader Mode. 📖
  • r — re-fetch submissions for the current category. 🔄
  • / — search Hacker News. See Search. 🔍
  • Tab — change category (use Shift + Tab to change in the opposite direction). 🗂️
  • o — open link to article in browser. See CLX_BROWSER. 🌐
  • c — open comment section in browser. 💻
  • f, V — add currently highlighted submission to favorites. ⭐
  • x — remove currently highlighted submission from favorites. 🗑️
  • u — toggle read/unread for the currently highlighted submission. 👀
  • z — toggle the wide (split-pane) layout for the session. See --wide-view. 🪟
  • j, k — move down/up one item. ⬇️⬆️
  • h, l — previous/next page. 📄
  • g, G — go to the top/bottom of the list. 🔝🔚
  • i, ? — bring up the help screen. ❓
  • q, Esc — quit to prompt. 🚪

💬 COMMENT SECTION 💬

The comment section has two interaction modes: read mode and navigate mode. periodt. 💅

📖 Read Mode 📖

The default mode. Scroll through the comment section line by line. 🧚

  • j, k — scroll down/up one line. ⬇️⬆️
  • d, u — scroll down/up half a page. 📜
  • Space / f, b — page down/up. 📄
  • g, G — go to top/bottom. 🔝🔚
  • n, N — jump to next/previous top-level comment. 🧵
  • / — search within the comment section. While a search is active, n/N jump between matches. 🔍
  • h, l — collapse/expand one level. 🪗
  • o — open link to article in browser. 🌐
  • c — open comment section in browser. 💻
  • J, K — open the comment section of the next/previous story on the front page. 📰
  • Enter — toggle collapse all. 🫣
  • a — switch to navigate mode. 🧭
  • Tab — open the link selector. j/k step between the links in the comment section; Enter opens the selected link in Reader Mode, and q or Esc walks back. Links to other Hacker News discussions open as comment sections; links that cannot be read in Reader Mode are dimmed and inert. 🔗
  • z — toggle the wide (split-pane) layout for the session. 🪟
  • i, ? — bring up the help screen. ❓
  • q, Esc — go back. ↩️

Jump between individual comments instead of scrolling line by line. it’s giving precision. 🎯

  • j, k — next/previous comment. ⬇️⬆️
  • d, u — scroll down/up half a page. 📜
  • Space / f, b — page down/up. 📄
  • g, G — go to top/bottom. 🔝🔚
  • n, N — jump to next/previous top-level comment. 🧵
  • / — search within the comment section. While a search is active, n/N jump between matches. 🔍
  • h, l — collapse/expand current comment. 🪗
  • o — open link to article in browser. 🌐
  • c — open comment section in browser. 💻
  • J, K — open the comment section of the next/previous story on the front page. 📰
  • Enter — toggle collapse for current comment. 🫣
  • Tab — open the link selector. 🔗
  • z — toggle the wide (split-pane) layout for the session. 🪟
  • i, ? — bring up the help screen. ❓
  • a, q, Esc — switch to read mode. 📖

🌈 READER MODE 🌈

  • j, k — scroll down/up one line. ⬇️⬆️
  • d, u — scroll down/up half a page. 📜
  • Space / f, b — page down/up. 📄
  • g, G — go to top/bottom. 🔝🔚
  • n, N — jump to next/previous section. 🧭
  • / — search within the article. While a search is active, n/N jump between matches. 🔍
  • Enter — toggle article images. See --graphics and --show-images-on-open. 🖼️
  • h, l — hide/show article images. 🙈🦋
  • Tab — open the link selector. j/k step between the article’s links; Enter follows the selected link in Reader Mode, and q or Esc walks back to the page it was opened from. Links that cannot be read in Reader Mode are dimmed and inert. 🔗
  • o — open link to article in browser. 🌐
  • c — open comment section in browser. 💻
  • J, K — open the next/previous story on the front page in Reader Mode. 📰
  • z — toggle the wide (split-pane) layout for the session. 🪟
  • i, ? — bring up the help screen. ❓
  • q, Esc — go back. ↩️

Press / to search all of Hacker News, powered by Algolia. While searching, the sort and date filters replace the category tabs in the header. iykyk. ✨

  • s — toggle sorting between popularity and date. 🔀
  • d — cycle the date range. 📅
  • r — re-run the search with the current filters. 🔄
  • Tab — leave search and rejoin the category cycle. 🗂️
  • q, Esc — leave search. 🚪

💅 OPTIONS 💅

All options can also be set persistently in config.toml (see FILES); flags take precedence over the config file. bestie, the config file is not the boss of the flags. 👑

  • -a n, --article-width=n — set the article width in Reader Mode to n columns. 📏
  • --categories=list — set the categories in the header. Available categories: top, best, new, ask, show, jobs, favorites. Separate categories with comma. The first category is the view shown on launch; it appears as the clx logo in the header rather than as a named tab. Default: "top,best,ask,show,favorites". 🗂️
  • -c n, --comment-width=n — set the comment width to n columns. 📐
  • --graphics=mode — set whether article images can be drawn at all. Drawing them requires a terminal that supports the Kitty graphics protocol, such as Ghostty, Kitty or Konsole. auto (the default) asks the terminal and believes the answer; where none comes back, images are shown as a text placeholder and are not even downloaded. always assumes support without asking — for terminals that can draw images but whose answer never arrives, such as tmux without allow-passthrough on, or ones clx declines to probe because the question itself misbehaves there. On a terminal that genuinely cannot draw images, forcing it on will print stray escape sequences. never refuses images outright: nothing is drawn, nothing is downloaded, and no escape sequence is sent. Images are scaled to their size on the page and centered. JPEG, PNG, GIF, WebP, AVIF and SVG images are drawn; other formats keep the placeholder. Whether they are shown as soon as an article opens is set separately; see --show-images-on-open. 🖼️
  • --indent=n — set the comment section indent size to n spaces per nesting level. When the requested indent would shrink a comment’s text column below a readable minimum, the indent plateaus and deeper comments share an ancestor’s indent level while the depth-colored bar continues to convey nesting. Default: 1. 🪜
  • -n, --nerdfonts — enable Nerd Fonts icons as decorators for some elements (requires a Nerd Font-patched font). Auto-enabled for Ghostty, which embeds Nerd Fonts. 🧚
  • -d, --no-history — disable marking stories as read. 🙈
  • --pages=n — set the number of pages to fetch per category, between 1 and 5. Higher values fetch more stories but increase load time. Only applies to top, new and best. Ask, show and jobs always fetch one page because their story pools are small (~150-200 stories). Default: 3. 📚
  • --show-images-on-open — show images as soon as an article opens, rather than waiting for Enter. Off by default, so articles open as text and images are revealed on demand. Has no effect where images cannot be drawn. 🌸
  • -v, --version — show the current version of circumflex. 🏷️
  • -w value, --wide-view=value — show the comment section and Reader Mode in a pane next to the front page instead of replacing it. Set to always, never, or the minimum terminal width in columns at which the split kicks in. Press z to toggle the split for the current session. Default: 180. 🪟

👑 COMMANDS 👑

  • clx add [ID] — add item to list of favorites by ID. ⭐
  • clx article [ID] — go directly to Reader Mode for a given item ID without first going through the main view. 📖
  • clx comments [ID] — go directly to the comment section for a given item ID without first going through the main view. 💬
  • clx url [URL] — open a URL directly in Reader Mode. 🔗
  • clx clear-history — clear the history of visited items. 🧹
  • clx default-config — generate a starter config file in the config directory. See FILES. 🛠️
  • clx default-theme — generate a starter theme file in the config directory. See FILES. 🎨

🕰️ HISTORY 🕰️

circumflex tracks which stories you have visited. Visited stories are dimmed in the list. When returning to a comment section, comments posted since your last visit are highlighted with a new-comment indicator. 👀✨

Use clx clear-history to reset history, or --no-history to turn tracking off entirely. 🧹

⭐ FAVORITES ⭐

Press f to add the currently highlighted submission to your list of favorites. Remove submissions from the Favorites page with x. 💖

The favorites file is TOML, suitable for hand-editing or version control. A favorites.json from versions before 5.0 is migrated automatically and left in place. 📁

🌿 ENVIRONMENT 🌿

  • XDG_CONFIG_HOME, XDG_CACHE_HOME — override the directories where circumflex stores its config and cache files. See FILES for what lives where. 🗂️
  • CLX_BROWSER — command used to open URLs (article links and comment pages). The URL is appended as the final argument. For example, CLX_BROWSER="firefox --new-tab" opens links in a new Firefox tab. When unset, the platform default opener is used (open on macOS, xdg-open on Linux, rundll32 on Windows). 🌐

📁 FILES 📁

  • $XDG_CONFIG_HOME/circumflex/config.toml — TOML configuration holding persistent defaults for the command-line options. Run clx default-config to write a starter file listing every key with its default value. Flags override values set here. 🛠️
  • $XDG_CONFIG_HOME/circumflex/theme.toml — TOML color theme. Run clx default-theme to write a starter file pre-populated with every key and its default value. Values may be named colors (red, bright_blue, ...), hex strings (#ff8800), or ANSI 256 indices (0-255). Unrecognized values render with no styling. 🎨
  • $XDG_CONFIG_HOME/circumflex/favorites.toml — saved favorites. A favorites.json from versions before 5.0 is migrated here automatically. ⭐
  • $XDG_CACHE_HOME/circumflex/history.json — IDs of visited stories. 🕰️

When the XDG variables are unset, the platform defaults apply: ~/Library/Application Support/circumflex/ and ~/Library/Caches/circumflex/ on macOS; ~/.config/circumflex/ and ~/.cache/circumflex/ on Linux. 🍓

💖 AUTHOR 💖

This whole thing — every keybinding, every flag, every little delight — was written by Ben Sadeh. That's the human. Say thank you to the human 🫶

okay bestie, that's the whole page, you made it to the end, we love a completionist queen 👑

You're reading the man page for CLX(1) from circumflex 5.0, dated 2026-07-29 — that's the source, the version, and the day it was stamped, all in one cute little footer bow 🎀

Now go press some keys, search something, favorite something, and live your best main-character terminal life. ngl I'm a little obsessed with you for reading all of this. periodt 💅✨

📦 where this page comes from