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 pages or files 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
--hi --highlight[=#] syntax highlight of files (default: on)
--no-highlight disable syntax highlight (--no-hi)
--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.19
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.The page number has a triangle on each side, as
◂ 2/12 ▸, which tells that the row can be scrolled in that direction: the triangle is filled when there is a page there, and open at the end of the row (◃ 1/12 ▸). They are the%Land%Rof the--labeloption ofansicolumn; give other marks by--mark, after the file names (--mark RIGHT=>> --mark RIGHT_END=).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.nupalso puts the following keys in theLESSKEY_CONTENTenvironment variable, whichless661 or later reads. With three panes on the screen and alessolder than 710, they are:h , left left-scroll one page to the left l . right right-scroll one page to the right H g < K no-scroll the left end of the row L G > J end-scroll the right end of the row space j down noaction ESC-) x 3 the panes on the screen to the right d ^D return b k up u ^U noaction ESC-( x 3 the panes on the screen to the leftThe pages have the height of the screen, and there is nothing to scroll down to:
jandk, the down and up arrows,dandu,^Dand^U, and the return key go on to the next and the previous screen, as space andbdo.noactiondoes nothing and then types the keys after it, here ESC-) three times. It cannot type the arrow keys, so ESC-) and ESC-( are given the same actions as the right and left arrow. InLESSKEY_CONTENT, they are in one line, joined by;, ash left-scroll;l right-scroll;..., and space is written\, a backslash and a space. Withless710 or later,l,., the right arrow and ESC-) areright-limit-scroll, which stops at the right end. A count before.is taken for a decimal point of the number byless; give it to the right arrow instead, as3and the right arrow.The help of
lessonhandHis then on no key, andgandGno longer go to the first and the last line, which are on the screen all the time anyway.When
LESSKEY_CONTENTis set, the keys are added after it, in a#commandsection, so that they win over the same keys there and in~/.lesskey; the other keys stay as they are.NUP_LESSKEYgives the keys in place of those ofnup, in the same way, and they do not change with the panes or theless. Set it empty not to add any keys, andLESSKEY_CONTENTis left as it is:export NUP_LESSKEY=The options are added to
NUP_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.See "LESS INTEGRATION" for what works with the versions of
less, and for the build oflessin tecolicom/tap, with which the screens are the same as without-L.nup -L man perlfunc nup -L -C4 README.mdWith more than one file, or
-V, the files side by side go on to the right in the same way, instead of going on below: each file is a column of its own, without pages, and as many columns as without this option are on the screen. The lines move up and down as usual, and onlyh,l,,,., the arrow keys, ESC-( and ESC-),H,L,<and>are put inLESSKEY_CONTENT, to move by one column and to the ends;gandGgo to the first and the last line.nup -L *.txtWith
--no-paginateand one input, which has nothing to put on the right, this option is ignored. It cannot be used with 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|noneSet 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, with the number of all the pages, as
3/12. With the files side by side (more than one file, or-V), which can be long, it is shown on the top border as well, at the left, under the file name. 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. -
--hi, --highlight[=NAME], --no-highlight
Color the source files by their syntax in file view mode. Enabled by default, and done when the command of the highlighter and Text::ANSI::Highlight::IO are installed; nothing changes without them.
ansicolumnreads each file through the highlighter, with the language told from the name of the file, or from the first line of a script. In a Markdown file, the code in a fence is colored by the language of the fence. A file whose language is not known is shown as it is, and so is a file which has ANSI sequences already. The file names in the headers are not changed.NAME is the highlighter:
pandoc pandoc, by its ansi writer (default) sourcehighlight, gnu source-highlight of GNU Source-highlight, the colors of less skylighting, sky the skylighting command brew install pandoc brew install source-highlight brew install skylightingSet the one to use in
NUP_OPTS:export NUP_OPTS=--highlight=sourcehighlightUse
--no-highlightto disable.--hiis the short name of the option, andskyandgnuare those of the highlighters:--hi=gnu,--no-hi.
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 INTEGRATION" 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 INTEGRATION
nup is made to be used with less. It sets environment
variables for less (see "ENVIRONMENT"), 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.
The pages fill the screen and go on below, and a line down would show
them cut in the middle. So j and k, the down and up arrows,
d and u, ^D and ^U, and the return key
move by the screen, as space and b do, when the output has pages
and the pager is less 661 or later, and J and K go to the
last and the first page, as G and g. The keys are put in
LESSKEY_CONTENT, in the way -L does, and not when NUP_LESSKEY
is set. Without pages (-F, or the files side by side), they move
by the line as usual. e and y are left to move by the line.
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" -
less661LESSKEY_CONTENTis read, which-Luses to put its keys:h,l,,,., the arrow keys, ESC-( and ESC-),H,L,g,G,<,>, space,b,j,k,d,u,^D,^U, the return key,JandK. Without-L, the keys arej,k, the down and up arrows,d,u,^D,^U, the return key,JandK. An olderlessignores it. -
less710right-limit-scrollstops at the right end of the lines.-Lputs it onl,., the right arrow and ESC-), 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, so that the panes are always at the edge of the screen.-Ladds this option when thelesshas it, and the screens are then the same as without-L: space,b,Gand>move by the screens, the last screen shows the last pages and the rest of it is blank, andnandNskip the matches on the screen and move by the screens to the next page that has one.l,.and the right arrow go on until the last page is at the left edge. For this, the keys of-Lare given a count instead of being repeated: with three panes, space andb, and the keys which do the same, are3ESC-) and3ESC-(, andGand>are3L, whileLshows the end of the row at the right edge of the screen.
app-nup of the tap has it inside, and nup of app-nup runs it.
It is put apart from the commands of Homebrew, so the less of
Homebrew itself stays as it is. To use it as less outside of
nup, install it on its own; it cannot be installed together with
the less of Homebrew, which has the same command name:
brew install tecolicom/tap/less
With either, use --align-record for the pages:
export NUP_PAGER="less --file-size"
export NUP_PAGE_PAGER="less --file-size --align-record=-1"
ENVIRONMENT
Read by nup
-
NUP_OPTSOptions given before those on the command line, separated by spaces, so that the options on the command line take precedence. This is useful when
nupis called by another command, asMANPAGER:NUP_OPTS=-L man perlfunc -
NUP_PAGERThe pager command, used when
--pageris not given. Default:less -F +Gg. See--pagerin "Pager Options". -
NUP_PAGE_PAGERThe pager command in page mode, used in place of
NUP_PAGER. See--pagerin "Pager Options". -
NUP_LESSKEYThe keys that
-Lgives toless, in place of those ofnup. Empty for no keys. See-Lin "General Options". When it is set, the keys of the pages without-Lare not added either. -
COLUMNS,LINESThe width and the height of the terminal when
/dev/ttyis not available. See "Terminal Size".
PAGER is not read, so that it can be set to nup.
Set by nup
These are set for less, when they are not set already:
-
LESSDefault:
-R. Required for ANSI color sequences. -
LESSANSIENDCHARSDefault:
mK. Recognizes SGR (m) and erase line (K) sequences.
-L adds its keys to LESSKEY_CONTENT, after those already in
it. See -L in "General Options".
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 -L *.txt # files side by side, scrolled sideways
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
It comes with the build of less in the same tap, which nup runs;
see "LESS INTEGRATION".
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