How do I use hl with an interactive pager for filtering, copy/yank, and live tailing?

[pamburus]

I'd like to use hl with an interactive pager that supports features like fuzzy filtering, copying/yanking selected lines to clipboard, and live tailing in follow mode.

What are the recommended pagers and how do I configure them?

[pamburus]

Using hl with an interactive pager

hl has a built-in pager profile system that tries candidates in order until one is found. The first thing to do is arrange the candidate list so your preferred pager is tried first and generic environment variables like PAGER don't override your choice.

Step 1 — Set candidate priority

Edit ~/.config/hl/config.toml (Linux/macOS) and override the [pager] section. The key idea: put your preferred profile right after the HL_PAGER entry and before the { env = "PAGER" } entry so that a shell-wide PAGER=less doesn't silently win.

For example, to prefer fzf, then fall back to ov, then less:

[pager]
candidates = [
  # Application-specific env vars still take top priority.
  { env = { pager = "HL_PAGER", follow = "HL_FOLLOW_PAGER", delimiter = "HL_PAGER_DELIMITER" }, profiles = true },
  # Your preferred profiles, in order.
  { profile = "fzf", if = "!os:windows" },
  { profile = "ov" },
  { profile = "less" },
  # Generic PAGER comes last to avoid surprises.
  { env = "PAGER" },
]

If none of the listed pagers are installed, hl falls back to raw stdout.

---

Example: fzf — fuzzy filtering, multi-select, clipboard yank

hl ships with a built-in fzf profile that provides:

• Fuzzy and exact filtering as you type
• Multi-select (Tab / Shift-Tab)
• Copy selected lines with Ctrl-Y (uses pbcopy on macOS, xclip on Linux)
• Follow mode support (--follow)
• Toggle raw view of a line with Enter

Just install fzf and make sure the fzf profile is near the top of your candidates list (right after the HL_PAGER entry) so it takes priority over other installed pagers. The built-in profile works out of the box:

# View mode — filter and browse interactively
hl app.log

# Follow mode — live tail with filtering
hl --follow app.log

Useful keybindings (built-in defaults):

Key	Action
Type text	Filter lines (exact match)
Tab	Select/deselect line
Ctrl-Y	Copy selected lines to clipboard
Enter	Toggle raw view of focused line
Esc	Clear query and selection
Ctrl-Q	Quit
Ctrl-F	Jump to latest (follow mode)

To customise the fzf profile, override it in your config:

[[pager.profiles]]
name = "fzf"
command = "fzf"
delimiter = "newline"
args = [
  "--ansi",
  "--exact",
  "--multi",
  "--no-sort",
  "--no-bold",
  "--highlight-line",
  "--bind=ctrl-q:abort",
  "--bind=enter:toggle-raw",
]
conditions = [
  { if = "os:macos", args = ["--bind=ctrl-y:execute-silent(printf %s\\\\n {+} | pbcopy)"] },
  { if = "os:linux", args = ["--bind=ctrl-y:execute-silent(printf %s\\\\n {+} | xclip -in -sel clip)"] },
  { if = "!mode:follow", args = ["--layout=reverse-list"] },
  { if = "mode:follow", args = ["--tac", "--track", "--tail=100000"] },
]
modes.follow.enabled = true

---

Example: ov — section-aware viewer with follow mode

ov is a terminal pager that supports horizontal scrolling, follow mode, and section-based navigation. The built-in profile:

[[pager.profiles]]
name = "ov"
command = "ov"
args = ["--caption=>", "--wrap=false", "--hscroll-width=4"]
modes.follow.args = ["--follow-mode"]
modes.follow.enabled = true

ov works well for wide log lines where you need horizontal scrolling and want to follow live output at the same time. It also supports line filtering with & (type & then a pattern to show only matching lines).

---

Example: less — simple scrollback with search

The built-in less profile enables ANSI colour and mouse support:

[[pager.profiles]]
name = "less"
command = "less"
args = ["-R", "--mouse"]
env = { LESSCHARSET = "UTF-8" }
modes.follow.enabled = false

less does not support follow mode through hl by default. Use /pattern inside less to search, &pattern to filter and show only matching lines, and q to quit.

If you want additional flags like -S (chop long lines), override the profile:

[[pager.profiles]]
name = "less"
command = "less"
args = ["-R", "-S", "--mouse"]
env = { LESSCHARSET = "UTF-8" }
modes.follow.enabled = false

---

Quick override without editing config

Use the HL_PAGER environment variable for one-off overrides. It supports @profile syntax to reference a named profile:

# Use the fzf profile for this invocation
HL_PAGER=@fzf hl app.log

# Use the ov profile
HL_PAGER=@ov hl app.log

# Use a custom command directly
HL_PAGER="less -RS" hl app.log

# Disable paging entirely
hl -P app.log

---

Summary of candidate resolution order

1. HL_PAGER / HL_FOLLOW_PAGER — explicit per-invocation override
2. Profile candidates — tried in the order listed in pager.candidates
3. PAGER — generic fallback (keep it last to avoid surprises)
4. No pager — raw stdout if nothing is found