NAME
nup - n-up, multi-column paged output for commands and files
SYNOPSIS
nup [ options ] file ...
nup -e [ options ] command ...
-h --help show help
--version show version
-d --debug debug mode
-n --dryrun dry-run mode
-e --exec execute command mode
--alias=CMD=OPTS set command alias
-V --parallel parallel view mode
-D --document document mode (default: on)
-F --no-paginate disable page mode
-A --auto-paginate auto disable page mode for single column
-L --lateral all pages in one row, scrolled sideways
-H --filename show filename headers (default: on)
-C --pane=#[,#] number of columns, and rows (e.g., 2,2)
-P --page=# page height in lines
-S --pane-width=# pane width (default: 85)
--bs --border-style=# border style (default: heavy-box)
--ls --line-style=# line style (none/truncate/wrap/wordwrap)
--runin=# run-in width for line breaking
--runout=# run-out width for line breaking
--runlen=# set both run-in and run-out
--boundary=# fold boundary: word, space or none
--cm --colormap=# color mapping (LABEL=COLOR)
--[no-]page-number page number on border (default: on)
--textconv[=EXT] textconv for non-text files
--pager=# pager command (empty to disable)
--no-pager disable pager
-T --device=# output device: tty, pdf, or a paper for PDF
(e.g., a4, a4p, a3l)
-o --output=FILE output file (PDF when it ends with .pdf)
--pdf-opts=# options for ansi2pdf (e.g., "-l 80")
--geometry print the size and the kind of the device
--white-board black on white board
--black-board white on black board
--green-board white on green board
--slate-board white on dark slate board
VERSION
Version 1.14
DESCRIPTION
N-up (command: nup) is a multi-column paged output tool. It provides a convenient way to view files or run commands in n-up layout using the App::optex::up module through optex.

nup automatically detects the mode based on the first argument: if it is an existing file, n-up file view mode is used; if it is an executable command, n-up command mode is used. Use -e option to force command mode when needed.
In file view mode, nup stops parsing its own options at the first file name and hands the file names and everything after them to ansicolumn unchanged. Options of ansicolumn that nup does not provide can therefore be given after the file names:
nup -C2 file1.txt file2.txt -w 170
Here -w 170 sets the output width for ansicolumn. To set the width when no terminal is available, the COLUMNS environment variable works in both modes; see "Terminal Size".
OPTIONS
General Options
- -h, --help
-
Show help message.
- --version
-
Show version.
- -d, --debug
-
Enable debug mode.
- -n, --dryrun
-
Dry-run mode. Show the command without executing.
- -e, --exec
-
Force command execution mode. Normally the mode is auto-detected, but use this option when you want to execute a file as a command.
- --alias=NAME=CMD OPTS...
-
Define command alias. When a command matches NAME, it is replaced by CMD with specified OPTS. This can be used to add default options or to substitute a different command. Multiple
--aliasoptions can be specified.Default aliases:
bat bat --style=plain --color=always batcat batcat --style=plain --color=always mdcat mdcat --ansi rg rg --color=always tree tree -CExample:
nup --alias='grep=ggrep --color=always' grep pattern file - -V, --parallel
-
Enable parallel view mode for ansicolumn. In this mode, each file is displayed in its own column without pagination, similar to
--no-paginate. Automatically enabled when multiple files are specified. Single file or stdin input results in single column output. - -D, --document
-
Enable document mode for ansicolumn. This mode is optimized for viewing documents with n-up page-based layout. Enabled by default. Use
--no-documentto disable. - -F, --no-paginate
-
Disable page mode. Without pagination, the entire content is split evenly across columns. Page mode is the default; use --paginate to re-enable if needed.
- -A, --auto-paginate
-
Automatically disable page mode when only one column fits the terminal. This is useful when using
nupasMANPAGER, where single-column page splitting wastes space. - -L, --lateral
-
Put all the pages in one row, however wide it becomes, instead of filling the screen with as many panes as fit and going on below. The row is as high as the screen, and it is seen by scrolling sideways in the pager.
The screen shows the same number of panes as without this option: as many as fit, or the number given by
-C. With-C4, four pages are on the screen at a time, each a quarter of it wide.When the pager is
less,nupadds-S --shift=N --rscroll=-to it, where N is the width of a pane: the lines are not wrapped, and the right and left arrow keys move by one page.handlmove to the left and to the right as well, andHandLgo to the left end and to the right end of the row:nupsets theLESSKEY_CONTENTenvironment variable toh left-scroll;l right-scroll;H no-scroll;L end-scrollwhen it is not set.
handHare the help ofless, which is not on a key then: setLESSKEY_CONTENTyourself to keep it. The options are added toNUP_PAGER,NUP_PAGE_PAGERand--pageras well when the command isless; another pager is used as it is, and has to be told not to wrap the lines.What works depends on the version of
less, and the build oflessin tecolicom/tap keeps the panes at the edge of the screen in a search as well; see "LESS".nup -L man perlfunc nup -L -C4 README.mdThis is for the pages of one input. It cannot be used with more than one file,
--parallel,--no-paginate, rows (-R,-C2,2,-G) or PDF output (-T,-owith.pdf).--auto-paginateis ignored. The pages are laid out once, for the height of the terminal at that time. - -H, --filename
-
Show filename headers in file view mode. Enabled by default. Use
--no-filenameto disable.
Layout Options
- -C C[,R], --pane=C[,R]
-
Set the number of columns (panes), and the number of rows when it is given after a comma. For example,
-C2creates 2 columns, and-C2,3creates 2 columns and 3 rows. - -R N, --row=N
-
Set the number of rows. This option is kept for compatibility and may be removed in the future.
- -G CxR, --grid=CxR
-
Set grid layout.
-G2x3is equivalent to-C2,3. This option is kept for compatibility and may be removed in the future. - -P N, --page=N
-
Set the page height in lines.
- -S N, --pane-width=N
-
Set the pane width in characters. Default is 85.
Style Options
- --bs=STYLE, --border-style=STYLE
-
Set the border style. Default is
heavy-box. - --ls=STYLE, --line-style=STYLE
-
Set the line style. Available:
none,truncate,wrap,wordwrap. - --runin=N, --runout=N, --runlen=N
-
Set the run-in and run-out widths that ansicolumn uses for line breaking (kinsoku) when it folds long lines.
--runlensets both. They are given to ansicolumn after the values in ~/.ansicolumnrc, so they take precedence. Without them, ansicolumn uses the values in ~/.ansicolumnrc, or 2. - --boundary=
word|space|none -
Set where ansicolumn may break a line when it folds long lines, as its
--boundaryoption:worddoes not break inside an alphanumeric word,spacenot inside a sequence of non-space characters, andnonebreaks anywhere. Like--runin, it is given to ansicolumn after ~/.ansicolumnrc. Without it, ansicolumn uses the value in the rc file, orwordin document mode. - --cm=SPEC, --colormap=SPEC
-
Set color mapping. Specify as
LABEL=COLOR(e.g.,--cm=BORDER=R). Available labels:TEXT,BORDER. - --[no-]page-number
-
Show page number on the bottom border of each column. Enabled by default. Use
--no-page-numberto disable. - --white-board, --black-board, --green-board, --slate-board
-
Predefined color schemes for board-style display.
Text Conversion
- --textconv[=EXT,...]
-
Enable text conversion for non-text files using App::optex::textconv. When any of the specified file extensions are found in the arguments, the
textconvmodule is loaded to convert them to text before display.Default extensions:
pdf,docx,docm,pptx,pptm,xlsx,xlsm,jpg,jpeg.Use
--textconv=noneto disable.
Pager Options
- --pager=COMMAND
-
Set the pager command. Default is
NUP_PAGERorless -F +Gg. When page mode is active,NUP_PAGE_PAGERtakes precedence overNUP_PAGER. Viewing multiple files (or-Vparallel view) produces parallel layout which has no page structure, sonupdisables page mode andNUP_PAGE_PAGERis not used there. ThePAGERvariable is not used to avoid an infinite loop whenPAGERis set tonup.+Ggmakeslessread all input before displaying, so that-Fand the percentage work; see "LESS" for the settings ofless.Use
--pager=(empty) or--no-pagerto disable pager. - --no-pager
-
Disable pager.
PDF Output
- -T DEVICE, --device=DEVICE
-
Set the device to show the output on. The default is
tty, the terminal. Any other device is a paper, and the output is printed to PDF byansi2pdf, instead of being shown on the terminal.The name of a paper is the one for the
-poption ofansi2pdf, such asa4,a3,b5orletter. A paper is used in landscape orientation. The letterporlafter the name gives the orientation:a4pis A4 in portrait, anda4lis A4 in landscape. The devicepdfis the default paper ofansi2pdf, A4.nup -T a4 man nup > nup.pdf # A4, landscape nup -T a4p -C1 man nup | lpr # A4, portraitA sheet of paper takes the place of the terminal, and
ansi2pdftakes the place of the pager. The size of a sheet in columns and lines is asked toansi2pdf, the output is formatted for that size in the same way as for a terminal, and each screen is printed on a sheet as it is. The default is a landscape A4 sheet of 60 lines, which has room for two panes of the default width. - -o FILE, --output=FILE
-
Write the output to FILE. When the name ends with
.pdf, the output is PDF without-Tas well.nup -o nup.pdf man nup # A4, landscape nup -T a3 -o nup.pdf man nup # A3, landscapeOtherwise, what is shown on the terminal is written to the file as it is, with the ANSI sequences and in the size of the terminal, and the pager is not used.
-T ttydoes so for a name ending with.pdfas well.nup -o nup.txt man nup # the same as --no-pager > nup.txt - --geometry
-
Print the size of the device in columns and lines and its kind,
ttyorpdf, and exit. No file is read and no command is run.$ nup -T a4p --geometry 100 60 pdf $ nup -o nup.pdf -P 80 --geometry 275 80 pdfFor a paper, the size is that of a sheet, which follows
-T,-o,-P, the number of rows,--pdf-optsand-wofansicolumngiven after the file names. For the terminal, it is the size of the terminal. This is for a program that formats text before giving it tonup, as mdee(1) does. - --pdf-opts=OPTIONS
-
Give other options to
ansi2pdf, such as the number of lines on a sheet, the margin and the fonts. They are given after the paper, so they take precedence.nup -o nup.pdf --pdf-opts='-l 80 -m 15' man nup
The -P option sets the number of lines of a page for PDF as well: a sheet has that many lines for each row. The -w option of ansicolumn, given after the files or the command, sets the number of columns of a sheet. The font size follows them, and the one that is not given is decided to fill the sheet. With neither of them, a sheet has 60 lines.
nup -o nup.pdf -P 80 man nup # 80 lines on a sheet
nup -o nup.pdf -C2,2 -P 40 man nup # 2x2 pages of 40 lines
nup -o nup.pdf -C3 file -w 300 # 300 columns on a sheet
Terminal Size
The terminal size is taken from the controlling terminal (/dev/tty). When it is not available, as when nup is run without a terminal, the COLUMNS environment variable gives the width (default 80), and LINES gives the height (default 24) used to split the screen when the number of rows is set, as in -C2,2:
COLUMNS=170 nup -C2 file1.txt file2.txt
LESS
nup is made to be used with less. It sets environment variables for less, and adds options to it for -L. Some of them need a recent version, and a patched build of less does more for the pages of nup.
Environment Variables
nup sets the following environment variables when they are not already defined, to ensure proper display with less:
LESS-
Default:
-R. Required for ANSI color sequences. LESSANSIENDCHARS-
Default:
mK. Recognizes SGR (m) and erase line (K) sequences.
Versions
less590-
--file-sizemakeslessread all input before displaying, as+Ggof the default pager does. Theless581 of macOS does not have it, so+Ggis the default. SetNUP_PAGERto use it:export NUP_PAGER="less --file-size" less661-
LESSKEY_CONTENTis read, which-Luses to put the keysh,l,HandL. An olderlessignores it. less710-
right-limit-scrollstops at the right end of the lines.-Lputs it onl, in place ofright-scroll, which goes on past the end.
-L runs less --align-shift --version to see the version of less, and whether it has the option below.
The Build in tecolicom/tap
tecolicom/tap has a build of less with patches for the pages of nup (kaz-utashiro/less). It adds two options:
- --align-record=N
-
A search shows the whole record (page) that has the match from the top of the screen, instead of the matching line, so that the pages stay in place. N is the lines of a record;
-1is the height of the screen less the prompt line, which is the height of the pages ofnup. A repeated search goes on from the next record. - --align-shift
-
The horizontal shift stays at a multiple of the
--shiftamount, the width of a pane with-L. A search, and the right end, keep the panes at the edge of the screen, andnandNgo through the panes that have a match, one by one.-Ladds this option when thelesshas it.
Install it with Homebrew. It cannot be installed together with the less of Homebrew itself, which has the same command name:
brew install tecolicom/tap/less
Then use --align-record for the pages:
export NUP_PAGER="less --file-size"
export NUP_PAGE_PAGER="less --file-size --align-record=-1"
EXAMPLES
Typical n-up usage:
nup man nup # view manual in n-up layout
nup -C2 man perl # 2 columns
nup -C2,2 man perl # 2x2 grid (4-up layout)
nup -F man perl # no pagination
nup -L man perl # one row of pages, scrolled sideways
nup -L -C4 man perl # four pages on the screen at a time
nup file1.txt file2.txt # view files side by side
nup -C2 a.txt b.txt -w 170 # 2 columns, width 170 (ansicolumn -w)
nup -e ./script.sh # force command mode for a file
nup -o nup.pdf man nup # print to PDF (requires ansi2pdf)
nup -T a4p -C1 file | lpr # print on A4 in portrait
Using nup as a MANPAGER:
export MANPAGER="nup -A"
INSTALLATION
Homebrew
Use tecolicom/tap:
brew tap tecolicom/tap
brew install app-nup
See "LESS" for the build of less in the same tap.
CPAN
Using cpanminus:
cpanm -n App::nup
DIAGNOSTICS
Both stdout and stderr of the command are merged and passed through the n-up output filter. Error messages will appear in the paged output.
EXIT STATUS
The exit status of the executed command is not preserved because the output is passed through a filter pipeline.
SEE ALSO
App::optex::up (bundled), optex
AUTHOR
Kazumasa Utashiro
LICENSE
Copyright 2025-2026 Kazumasa Utashiro.
This software is released under the MIT License. https://opensource.org/licenses/MIT