binpeek

binpeek is a minimalist hexdump utility inspired by xxd, rewritten in Zig for performance and simplicity. It displays binary files in hexadecimal and ASCII side by side, with configurable colour highlighting — handy for low-level analysis and debugging.

Features

• Hexadecimal and ASCII side-by-side view.
• Colour highlighting by byte category (printable, escape, format, other), configurable via a TOML file.
• Colour is automatic: on when writing to a terminal, off when piped or redirected (override with --color).
• Reads from a file or from standard input.
• xxd-style options: seek, length limit, custom column width, and plain hex output.
• Written in Zig for speed and cross-platform compatibility.

Installation

1. Ensure Zig v0.16.0 or later is installed.

2. Clone the repository:

   git clone https://github.com/strvdr/binpeek

3. Build:

   cd binpeek
   zig build -Doptimize=ReleaseFast

   The binary is produced at zig-out/bin/binpeek.

4. Optional — install it on your PATH and add the config:

   cp zig-out/bin/binpeek /usr/local/bin/          # may require sudo
   cp .config/binpeek.toml ~/.config/

Note: zig build only updates zig-out/bin/binpeek. If you previously copied binpeek into /usr/local/bin (or elsewhere on your PATH), re-run the copy above after rebuilding, otherwise binpeek will keep running the old binary.

Usage

binpeek [options] [file]

With no file (or -), binpeek reads from standard input.

Options

Option	Description
-c, --cols N	Bytes per row (default 16).
-s, --seek N	Skip N bytes before dumping.
-l, --length N	Dump at most N bytes.
-p, --plain	Plain continuous hex, no offsets/ASCII/colour (like xxd -p).
--color=WHEN	Colourize: auto (default), always, or never.
-h, --help	Show help.

N accepts decimal or 0x-prefixed hex (e.g. -l 0x40).

Examples

binpeek file.bin                 # dump a file
binpeek -s 0x100 -l 64 file.bin  # 64 bytes starting at offset 0x100
binpeek -c 8 file.bin            # 8 bytes per row
cat file.bin | binpeek           # read from stdin
binpeek -p file.bin              # plain hex, pipe-friendly
binpeek --color=always file.bin | less -R

Example Output

00000000: 7f45 4c46 0201 0100 0000 0000 0000 0000  .ELF............
00000010: 0300 3e00 0100 0000 1010 0000 0000 0000  ..>.............

Configuration

binpeek supports colour customisation through ANSI escape codes, which work with most terminals and operating systems. Colours are read from ~/.config/binpeek.toml; if the file is absent, sensible defaults are used.

Inside binpeek.toml, under a [Colors] table, you can set:

[Colors]
asciiColors = "green"    # printable characters
binColors = "red"        # other / binary bytes
formatColors = "blue"    # format bytes (0x7f, 0xff)
escapeColors = "yellow"  # whitespace/escape bytes (\t \n \r, 0x1a)

Each value may be any of:

red  green  blue  cyan  yellow  magenta

Contributing

Contributions are welcome! Open an issue or submit a pull request for improvements or bug fixes.

Dependencies

binpeek depends on ztoml, a tiny TOML parser used to read the optional colour config. It is fetched automatically by zig build.

License

MIT © Strydr Silverberg

---

Inspired by xxd, built with Zig's simplicity in mind.🧠