HEE-PRINT(1) HEE Tools HEE-PRINT(1)
NAME
hee-print - render files nicely for terminal surfaces
SYNOPSIS
hee-print [--no-header] [--animate] [--image-format FMT] [--] FILE...
hee-print [--no-header] --stdin [--hint md|yaml|json|image|text]
SOMETHING | hee-print [--hint md|yaml|json|image|text]
hee-print help
DESCRIPTION
Picks a renderer from the file extension. When the nicer tool is missing,
it degrades to a plainer one -- and SAYS SO on stderr, naming what is
missing, so a plain render is never mistaken for a pretty one. Never
prompts, never writes. A degrade still exits 0: the file was rendered.
.md/.markdown -> glow -p, else bat/batcat, else cat (+ WARNING)
.yml/.yaml -> yq -P (the mikefarah yq only), else bat/batcat,
else cat (+ WARNING naming the yq that was found)
.json -> jq ., else bat/batcat, else cat (+ WARNING)
.png/.jpg/.jpeg/.gif/.webp
-> chafa (a still; --animate plays a GIF for 10 s), else
`file` plus a WARNING naming the missing renderer --
never a raw byte dump to the terminal
other -> bat/batcat -p --paging=never, else cat
On yq: Debian and Ubuntu ship a DIFFERENT `yq` -- a Python jq wrapper
(`yq 3.x`) that does not understand `-P` and errors on it. hee-print
therefore uses yq only when `yq --version` reports the mikefarah yq,
and otherwise degrades with a WARNING. `hee tools-update` installs the
pinned mikefarah yq into ~/.local/bin, ahead of the distro one on PATH.
Images: the format that is known to work is the default, measured from
where the tool is running, not guessed (operator, 2026-09-06: "when you
find what works in tmux and not, make it the default and add a switch
to try something else"):
inside tmux, allow-passthrough on -> sixels, passed through to the
outer terminal (which must draw
them; tmux 3.4 cannot itself)
inside tmux, allow-passthrough off -> symbols (pixels cannot leave tmux)
kitty (KITTY_WINDOW_ID) / WezTerm -> kitty
iTerm2 -> iterm
Windows Terminal (WT_SESSION) -> sixels
anything else -> chafa's own guess
--image-format FMT try something else: symbols, sixels, kitty, iterm,
or auto. HEE_PRINT_IMAGE_FORMAT (heerc or environment)
is the same override, persistent. `--image-format
show` prints the format that would be used and why.
--no-header suppress the per-file header printed when given several files
--animate let an animated image play (10 s) instead of showing a still
--stdin read the document from stdin instead of a path. Implied when
no FILE is given and stdin is a pipe, so `foo | hee-print`
works -- answering a piped document with the usage page tells
the reader nothing about what went wrong
--hint which renderer to use when reading stdin; ignored otherwise.
Omit it and the bytes are sniffed with file(1), so a piped
image renders instead of being cat'd at the terminal
EXIT STATUS
0 rendered 2 usage error or no file given
EXAMPLES
A terminal takes text, so pasting an image into one gives you nothing
useful. The image is on the clipboard: read the clipboard, not the
terminal. Whichever tool your session has --
wl-paste --list-types Wayland: what is on it
wl-paste --type image/png > image.png Wayland: write it
xclip -selection clipboard -t image/png -o > image.png X11
hee-print image.png look at it
Or write and view in one pass. This tool never writes, so tee does that:
wl-paste --type image/png | tee image.png | hee-print
With no --hint the piped bytes are sniffed with file(1), so that renders
as an image instead of spraying it across the terminal.
Any command that emits a document works the same way:
hee exif read image.png --provenance | hee-print
curl -s https://example.com/data.json | hee-print
Proven in CI over checked-in fixtures -- each renders and exits 0 even
where the pretty renderer is absent, because a degrade is still a render:
$ hee print tests/fixtures/print/sample.json # ci
$ hee print tests/fixtures/print/sample.yaml # ci
$ hee print tests/fixtures/print/sample.md # ci
$ hee print --image-format show # ci
HEE-PRINT(1)