@codebam/bunpic

An elegant TypeScript-powered terminal image viewer using Bun.Image and the native Kitty Graphics Protocol.

Installation & Running

You can run bunpic directly without local installation using bunx:

bunx @codebam/bunpic [options] <image-path>

Global Installation

To install bunpic globally on your system:

bun install -g @codebam/bunpic

Once installed globally, run it via the bunpic command:

bunpic [options] <image-path>

Local Development

For developers, clone the repository and run:

bun install
bun run src/index.ts [options] <image-path>

Options

• -w, --width <cols>: Output width in terminal columns (defaults to auto-fitting to 95% of current terminal width)
• -r, --height <rows>: Output height in terminal rows (defaults to aspect ratio)
• -f, --fit <fit>: Fit mode: fill, inside (default: fill)
• -b, --brightness <num>: Adjust image brightness (multiplier, e.g., 1.2)
• -s, --saturation <num>: Adjust image saturation (multiplier, e.g., 0 for greyscale, 1.5 to boost)
• --rotate <deg>: Rotate image (multiples of 90: 90, 180, 270)
• --flip: Flip image vertically
• --flop: Flip image horizontally
• --portable: Force using Bun's portable CPU backend (Bun.Image.backend = "bun")
• --info: Output image metadata only (width, height, format) as JSON
• -h, --help: Show help message

Examples

Display an image at auto-fitted terminal width:

bunpic photo.jpg

Display an image scaled to 40 terminal columns:

bunpic -w 40 photo.jpg

Get image metadata only:

bunpic --info photo.jpg

Apply brightness, saturation, and rotation transformations:

bunpic -w 60 -b 1.2 -s 0.8 --rotate 90 photo.jpg