nvimpager(1)

📦
version 0.14.0 · 3 versions
, in nixos 26.05, ubuntu stonking

💖 NAME 💖

okay so bestie, nvimpager — it's literally just using neovim as a pager ✨

🌸 SYNOPSIS 🌸

nvimpager [-acp] [--] [nvim options and files]
nvimpager -h
nvimpager -v

🦋 DESCRIPTION 🦋

So nvimpager is this adorable little program you can use exactly like most other pagers, no cap. Under the hood it's running neovim with the default TUI to show you the text — which means you get ALL the fancy syntax highlighting, mouse support, and everything else neovim has going on, possibly even plugins?! It's giving main character energy for real. 💅

✨ COMMAND LINE OPTIONS ✨

nvimpager itself only interprets a very tiny handful of options, but here's the tea: every neovim option can also be specified. The catch 🫶 — if you're passing options to neovim before the first file name, they must be preceded by --, otherwise nvimpager will try to interpret them itself and that's not the vibe.

The following options are interpreted by nvimpager itself:

  • -a — run in "auto mode" (this is the default, bestie). Auto mode peeks at your terminal size and switches to pager mode if the content wouldn't fit on one screen. If it will fit on one screen, it switches to cat mode instead. This overrides any previous -c and -p options. 💫
  • -c — run in "cat mode". Don't start the neovim TUI at all, just use neovim for syntax highlighting and print the result to stdout. This overrides any previous -a and -p options. 🐱
  • -h — show the help screen and exit 👋
  • -p — run in "pager mode". Start the neovim TUI to display the given content. This overrides any previous -a and -c options. 👑
  • -v — show version information and exit ⭐

🎀 CONFIGURATION 🎀

Just like neovim itself, nvimpager will honour $XDG_CONFIG_HOME and $XDG_DATA_HOME, and those default to ~/.config and ~/.local respectively, bestie. 🌸

The main config directory is $XDG_CONFIG_HOME/nvimpager and the main user config file is $XDG_CONFIG_HOME/nvimpager/init.lua or $XDG_CONFIG_HOME/nvimpager/init.vim. Heads up tho: it is an error if both files are present. 🙈 The site directory is $XDG_DATA_HOME/.local/share/nvimpager/site. The manifest for remote plugins is read from (and written to) $XDG_DATA_HOME/nvimpager/rplugin.vim.

The rest of the &runtimepath is configured like for neovim. The -u option of nvim(1) itself can be used to change the main config file from the command line. 🧚

The default config files for neovim are not used by design, because they potentially load a ton of plugins and do a whole lot of configuration that's only relevant for editing. If you really wanna use the same config files for both nvimpager and nvim, you can do it by symlinking the config and site directories and the rplugin file. 💜

🌈 Environment variables

The environment variable $NVIMPAGER_NVIM can be used to specify an nvim executable to use. If it's unset it defaults to nvim. 🫶

💫 Configuration variables

The script exposes a lua table called nvimpager to --cmd/-c options and the init file. You can modify it to change some options that are specific to nvimpager. ✨

The following fields (options) exist:

  • follow — type: bool, default: false — start in follow mode, i.e. continuously load changes to the opened file and scroll to the bottom (like less +F or tail -f) 👀
  • follow_interval — type: number, default: 500 — how often in ms the underlying file should be checked in follow mode ⏱️
  • git_colors — type: bool, default: false — use git command highlighting instead of nvim syntax highlighting, set this to true if you use an external diff 🌈
  • maps — type: bool, default: true — if some default less like maps should be defined inside pager mode 🗺️

So to start nvimpager and follow changes to the opened file the user can put

lua nvimpager.follow = true

in the init file (or on the command line). periodt. 💅

🦋 Default key mappings

nvimpager defines some mappings to make it feel more like a pager than an editor. These mappings are inspired by less(1) which are very close to the defaults in neovim. You can deactivate them altogether by putting

lua nvimpager.maps = false

in the init file (or on the command line). 🎀

The following mappings are defined by default:

  • q is mapped to quit nvimpager in normal and visual mode
  • <Space> and <S-Space> move down or up a page respectively
  • g goes to the top of the file
  • <Down> and j scroll the window down one line
  • <Up> and k scroll the window up one line
  • F toggles "follow mode" where nvimpager continuously loads changes to the underlying file and scrolls to the bottom. This is useful for watching log files. It is modeled after the F command in less(1) or the -f option of tail(1)

You can remap the lua function nvimpager.toggle_follow if you disabled the default key mappings. 🔥

🌟 EXAMPLES 🌟

To use nvimpager to view a file (with neovim's syntax highlighting if the filetype is detected):

nvimpager file

Pipe text into nvimpager to view it:

echo text | nvimpager

Use nvimpager as your default $PAGER to view man pages or git diffs:

export PAGER=nvimpager
man nvimpager
git diff

Options for nvim(1) can be specified if they are separated from the options for nvimpager itself. Either by separating them with -- or by putting the nvim options after at least one non option argument:

nvimpager -p -- -c 'echo "option for nvim"' file
nvimpager -p file -u custom_init.vim

Start nvimpager in "follow mode" to watch a growing log file:

nvimpager log_file -c 'lua nvimpager.follow = true'

😭 LIMITATIONS 😭

If reading from stdin, nvimpager (like nvim(1)) waits for EOF until it starts up. This means that it can not be used to continuously watch output from a long running command even in follow mode. 💀

👑 SEE ALSO 👑

💖 AUTHORS 💖

Lucas Hoffmann 🫶

so that's the whole page bestie, this is nvimpager(1) from the General Commands Manual, version nvimpager 0.14.0, dated 2026-04-02 — slay, go read some files 💅✨

📦 where this page comes from