A Rust CLI hex-dump utility inspired by UltraEdit's binary viewer. hhead shows a file's contents in hexadecimal and character form, with optional color, UTF-8 decoding, format-specific metadata, and an image minimap.
Looking to hack on
hheador send a pull request? See DEVELOPMENT.md.Long-form recipes, FAQ, and format-internals reference live in the project wiki (sources in
wiki/).
- Configurable display — adjust bytes-per-line, byte limits, and grouping.
- Color output — cyan offsets, magenta separators, colorized minimap.
- UTF-8 mode — decode multibyte text instead of stripping it to ASCII.
- File metadata — size, timestamps, permissions.
- Format detection — PNG, JPEG, GIF, BMP, ZIP, GZIP, TAR, TIFF, PDF, with format-specific fields (dimensions, compression, version, …).
- Image minimap — a 256-color thumbnail of PNG / JPEG / BMP images, rendered inline in your terminal.
- Markdown mode — render Markdown with aligned GFM tables and inline image figures instead of a hex dump.
- Any-document mode —
--mode-anydocconverts PDF, DOCX, XLSX, CSV, EPUB, … to Markdown (via anydoc) and renders it like--markdown(which is implied). - Pager mode — page through any output (
--mode-less) with a built-inless-style pager: scroll, search, jump. - Directory mode — point
--inputat a directory to get atree-style listing;--metaadds anls -lah/du -sh-style block. - Rainbow CSV —
--csv-rainbowpaints each CSV/TSV column in its own color; with--markdownor--mode-anydoc, table columns get the same palette. - Binary-safe — handles any file type.
- Rust 1.88+ (
anydoc's MSRV; the crate itself targets edition 2024). - A terminal that understands ANSI escapes if you want colors or the minimap.
git clone https://github.com/yfyang86/hhead
cd hhead
cargo build --release
# binary at target/release/hheadcargo install --path .hhead --input <FILE|DIR> [OPTIONS]hhead --input document.pdf --width 32 --bytes 128| Option | Description | Default |
|---|---|---|
--input <PATH> |
Input file, or a directory to list as a tree (required) | — |
--width <N> |
Bytes per line in the hex column | 64 |
--bytes <N> |
Maximum number of bytes to read | 256 |
--color |
Colorize offsets and separators | off |
--meta |
Print file metadata before the hex dump | off |
--utf8 |
Decode the character column as UTF-8 | off |
--minimap |
Render a 256-color thumbnail of image input | off |
--minimap-scale <ROWSxCOLS> |
Thumbnail grid size, e.g. 8x12 |
8x12 |
--markdown |
Render Markdown input instead of a hex dump (aligned tables — GFM pipe, pandoc grid and simple/multiline — with figures as minimaps) | off |
--mode-less |
Page through the output interactively, like less (works with the other options; the --bytes limit does not apply) |
off |
--mode-anydoc |
Convert the input to Markdown first (via anydoc), then render it like --markdown (which is implied) |
off |
--csv-rainbow |
Paint each CSV/TSV column in its own color (implies --color; whole file, --bytes does not apply); with --markdown/--mode-anydoc, table columns get the same palette |
off |
--tui-graphics[=<PROTO>] |
Render images (minimap, Markdown figures, display math) through a terminal graphics protocol: bare flag auto-detects, or force kitty/iterm2/sixel/off. Ignored under --mode-less |
off |
--tui-graphics-theme <THEME> |
Ink color for generated graphics (display math): dark = white ink, light = black ink, both on a transparent background |
dark |
--tui-caps |
Print detected terminal capabilities (graphics protocol, truecolor, cell geometry; live-probes an interactive terminal) and exit | off |
--tui-graphics upgrades image output from the 256-color block grid to real
graphics when the terminal supports a protocol — Kitty's APC (also WezTerm
and Ghostty), iTerm2's OSC 1337, or DEC sixel (foot, mlterm, Contour, xterm
-ti vt340). Sixel is encoded in-process; no external converters are needed.
- Auto detection is environment-based and only fires on a real TTY, so piped
output never contains escape sequences. Use
=kitty/=iterm2/=sixelto force a protocol (e.g. when redirecting to a file for later display). - Inside tmux, auto detection resolves to no graphics (passthrough is off by default); a forced protocol is wrapped in DCS passthrough.
- In
--markdown/--mode-anydocdocuments, math spans are rendered once--tui-graphicsis on:$...$inline, pandoc-gfm`$`...`$`inline,$$...$$and ``` math display blocks. Display math becomes a typeset image whentypst(≥ 0.4) is on `PATH`, and everything degrades to a Unicode approximation (`\frac{1}{2}` → `1/2`, `\alpha` → `α`) otherwise. Currency like `$5 and $10` stays literal. --tui-graphics-themepicks the formula ink; the background is always transparent (sixel composites onto black/white instead, as the protocol has no alpha channel).
--tui-caps reports what was detected and, on an interactive terminal,
probes the live terminal (DA1 sixel self-report, cell/window pixel geometry):
$ hhead --tui-caps
hhead tui caps: detected terminal capabilities
terminal program: iTerm.app
graphics protocol: iterm2
auto mode resolves to: iterm2
truecolor: yes
window size: 190x53 cells
window pixels: 1710x1110
probe DA1 sixel: no
probe cell size: 9x18 px
probe window size: 1710x1110 px
env: TERM=xterm-256color TERM_PROGRAM=iTerm.app COLORTERM=truecolor TMUX=<unset>Full help:
hhead --helphhead --input test.txt --width 1600000000: 48 65 6c 6c 6f 20 57 6f 72 6c 64 21 20 54 68 69 |Hello World! Thi |
00000010: 73 20 69 73 20 61 20 74 65 73 74 20 66 69 6c 65 |s is a test file |
00000020: 20 66 6f 72 20 68 65 78 20 64 75 6d 70 2e 0a | for hex dump.. |
hhead --input test.png --meta --color --bytes 64File: test.png
Size: 67 bytes
Created: 1769525204 (unix)
Modified: 1769525204 (unix)
Accessed: 1769525206 (unix)
Permissions: 0644
Format: PNG
Dimensions: 1 x 1
Bit depth: 8
Color type: Grayscale
00000000: 89 50 4e 47 0d 0a 1a 0a 00 00 00 0d 49 48 44 52 |.PNG........IHDR|
00000010: 00 00 00 01 00 00 00 01 08 00 00 00 00 3a 7e 9b |.............:~.|
00000020: 55 00 00 00 0a 49 44 41 54 78 9c 63 60 00 00 00 |U....IDATx.c`...|
00000030: 02 00 01 48 af a4 71 00 00 00 00 49 45 4e 44 ae |...H..q....IEND.|
hhead --input utf8.txt --utf8 --width 2400000000: 48 65 6c 6c 6f 20 e4 b8 96 e7 95 8c 20 f0 9f 8e 89 0a |Hello 世界 🎉. |
Note. In UTF-8 mode the trailing
|column is only strictly aligned for ASCII input — wide (CJK, emoji) and combining characters don't map 1:1 to terminal cells.
hhead --input test/demo.gif --minimap --minimap-scale 32x64 --width 32 --color --metaRenders a 32×64 grid of 256-color blocks sampled from the image, followed by the usual metadata and hex dump.
hhead --input notes.md --markdown --colorRenders the whole file instead of a hex dump (the --bytes limit does not apply): headings, fenced code blocks, and inline emphasis are styled, and GFM tables are padded and aligned per the separator row (:--, --:, :-:):
| Language | Stars | Trend |
|----------|-------|-------|
| Rust | 100k | up |
| Go | 90k | flat |
A lone  line is drawn as a 256-color minimap on the --minimap-scale grid, resolved relative to the Markdown file. Remote (http(s)://) and undecodable images fall back to a one-line placeholder.
hhead --input report.docx --mode-anydoc --color
hhead --input data.csv --mode-anydoc --mode-less # page the converted table--mode-anydoc converts the input to Markdown with anydoc
(PDF, DOCX/ODT, PPTX, XLSX/XLS, ODS, RTF, EPUB, CSV, …) and then renders it
exactly like --markdown, which is implied — the whole file is converted, so
the --bytes limit does not apply, and --mode-less pages the result. If
anydoc cannot convert the file, hhead warns on stderr and falls back:
text input (e.g. already-Markdown files) is rendered as Markdown, anything
else is shown as a hex dump.
hhead --input big.log --mode-less --color --meta--mode-less runs the built-in pager (no external less needed) on whatever
the other options produce — the full hex dump, Markdown render, minimap, or
metadata block. It reads the whole file, so the --bytes limit does not
apply (like --markdown). Keys:
| Key | Action |
|---|---|
q / Esc |
quit |
j / ↓ / Enter |
scroll down one line |
k / ↑ |
scroll up one line |
Space / f / PgDn |
page down |
b / PgUp |
page up |
g / G |
jump to top / bottom |
/ |
search forward (case-insensitive); Enter to run, Esc to cancel |
n / N |
next / previous match |
If stdin or stdout is not a terminal, the pager falls back to dumping the whole output, so piping still works.
hhead --input data.csv --csv-rainbow
hhead --input report.md --markdown --csv-rainbow # rainbow table columns
hhead --input data.xlsx --mode-anydoc --csv-rainbow--csv-rainbow renders CSV/TSV input as text with every column painted in
its own color (cyan, yellow, green, magenta, blue, red, cycling), leaving
the layout untouched. Parsing is quote-aware — a quoted field keeps embedded
delimiters and even line breaks in one field's color — and the delimiter
(,, tab, or ;) is sniffed from the first line. The flag implies
--color, reads the whole file like Markdown mode, and pages with
--mode-less. Combined with --markdown or --mode-anydoc, table columns
are painted with the same palette instead. Non-UTF-8 input falls back to
the hex dump.
hhead --input src --meta --colorWhen --input is a directory, hhead lists it as a tree (like tree)
instead of hex-dumping. With --meta, the tree is preceded by an
ls -lah-style listing of the directory's entries (mode, human-readable
size, UTC mtime) and a du -sh *-style block of recursive sizes with a
total. --color paints directories blue, symlinks cyan, executables green,
and sizes yellow; --mode-less pages the listing.
Directory: src
drwxr-xr-x 4.0K Sep 1 08:51 cli
-rw-r--r-- 482 Sep 1 08:48 lib.rs
...
2.1K cli
482 lib.rs
...
94K total
src
├── cli
│ ├── args.rs
│ └── mod.rs
├── lib.rs
└── ...
5 directories, 18 files
hhead --input test.zip --meta --width 32File: test.zip
Size: 213 bytes
Created: 1769525117 (unix)
Modified: 1769525117 (unix)
Accessed: 1769525117 (unix)
Permissions: 0644
Format: ZIP
Compression: Stored
Compressed size: 47 bytes
Uncompressed size: 47 bytes
First file: test.txt
00000000: 50 4b 03 04 0a 00 00 00 00 00 c7 b1 3b 5c f5 9e fb 90 2f 00 00 00 2f 00 00 00 08 00 1c 00 74 65 |PK..........;\..../.../.......te|
00000040: 73 74 2e 74 78 74 55 54 09 00 03 36 c8 78 69 37 c8 78 69 75 78 0b 00 01 04 f5 01 00 00 04 14 00 |st.txtUT...6.xi7.xiux...........|
00000080: 00 00 48 65 6c 6c 6f 20 57 6f 72 6c 64 21 20 54 68 69 73 20 69 73 20 61 20 74 65 73 74 20 66 69 |..Hello World! This is a test fi|
000000c0: 6c 65 20 66 6f 72 20 68 65 78 20 64 75 6d 70 2e 0a 50 4b 01 02 1e 03 0a 00 00 00 00 00 c7 b1 3b |le for hex dump..PK............;|
hhead inspects the first 1024 bytes of the input and, if the magic bytes match a known format, prints extra fields.
| Format | Magic | Extracted fields |
|---|---|---|
| PNG | \x89PNG\r\n\x1a\n |
Dimensions, bit depth, color type |
| JPEG | \xff\xd8\xff |
Dimensions, components |
| BMP | BM |
Dimensions, bits per pixel, compression, orientation |
| GIF | GIF87a / GIF89a |
Version, dimensions, color-table info |
| ZIP | PK\x03\x04 / \x05\x06 / \x07\x08 |
Compression method, sizes, first filename |
| GZIP | \x1f\x8b |
Compression, modified time, OS, flags |
| TIFF | II\x2a\x00 / MM\x00\x2a |
Endianness, IFD offset |
%PDF- |
Version | |
| TAR | ustar\0 / ustar |
First entry name, size, type, mtime |
Each hex row has three sections:
- Offset — 8 hex digits (16 for files larger than 4 GiB), e.g.
00000000:. - Hex bytes — each byte as two lowercase hex digits, grouped in blocks of 8.
- Character column — printable ASCII (or UTF-8 when
--utf8is set) wrapped in|…|; non-printable bytes render as..
MIT. See LICENSE.
